> ## Documentation Index > Fetch the complete documentation index at: https://docs.miso.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search API > The Search API provides personalized, typo-correcting, semantic search for your site. You send this API the search queries users entered, and the API returns the relevant search results tailored to your users' interests. ### Personalized search Personalized search is a key factor in driving search conversion on many major sites. It is particularly powerful for short search queries (≤ 3 keywords), which account for [up to 80% of search traffic in the U.S.](https://www.statista.com/statistics/269740/number-of-search-terms-in-internet-research-in-the-us/), but are usually the hardest to get right with traditional search engines. This is because shorter search queries tend to match a larger number of results, but there is not enough information in the query strings alone to determine which results the users are actually looking for. For example, when users search for *jeans* on Levi's.com, it is impossible to know which *jeans* the user is looking for, among thousands of options. Even if the user adds: *jeans for men*, it is still unclear to a traditional search engine what style, material, or size the user wants. In the contrary, with Miso's personalized search, we not only analyze the search query itself, but also take into account the *context* in which the searches are made, including who are the users, where are they from, what are their past interactions on the site, what other searches the user made, etc. These signals together allow Miso to generate more than 15% to 20% higher search conversion rate than the traditional non-personalized search engines. ### Balancing relevancy and personalization Although personalization is a powerful technique, over-using it can be harmful to the user experiences. In the context of search optimization, the relevancy of the search results are still the most important criteria, and we don't want personalization to overwhelm the search relevancy. For example, when users search for a very specific term, or directly search for the product names, Miso's algorithm will respond with the most relevant search results first, and then only apply personalization to rerank more ambiguous search results. ### Basic usage For every search query, you let Miso know the user's `user_id` and the search keywords in the API request body, for example: ``` POST /v1/search/search { "q": "jeans", "user_id": "user-123" } ``` For site visitors who do not sign in, you can let Miso know the `anonymous_id` of this visitor: ``` POST /v1/search/search { "q": "jeans", "anonymous_id": "visitor-123" } ``` ### Search response With the query above, Miso responds with the search results like the following: ```javascript { "message":"success", "data":{ "took":50, "total":30, "start":0, "miso_id":"f34b90de-086b-11eb-b498-1ee8abb1818b", "products":[ { "product_id":"505-regular-fit-mens-jeans", "title":"The 505 Regular Fit Men's Jeans", "url":"https://levi.com/jeans/505-regular-fit-mens-jeans/", "size":"29", "material":"Cotton", "color":"Rinse - Dark Wash", "_search_score": 78.12, "_personalization_score": 0.98 } ], "spellcheck":{ "spelling_errors":false } } } ``` * **took**: the amount of time (in milliseconds) Miso took to answer the query * **total**: the total number of matched products. You can paginate through all the products by using the combination of *start* and *rows* parameters (see *Request Body Schema* below) * **miso_id**: a UUID of the search request. You should include **miso_id** in the Interaction records for every interactions that result from this search request, e.g. user click-through a product in the search results. Miso use miso_id to track the search performance and fine-tune the algorithm accordingly. * **products**: an array of [Product records](#operation/content_write_api_v1_products_post) that match the search query, ranked in the order of relevancy and probability that the user will be interested in this product. By default, only the `product_id` of the Product is returned. You can ask Miso to return additional fields by using the *fl* parameter (see *Request Body Schema* below) * **products[ ]._search_score**: the search relevancy score of the products based on keyword matching and Miso's semantic matching. This score is similar to traditional Lucene search score. * **products[ ]._personalization_score**: the score assigned by Miso's personalization algorithm based on users' profile and their interactions on the site. This score quantifies the probability of whether users will be interested in this product or not. * **spellcheck**: an dictionary contains spell checking information. ### Spellcheck and auto-correction According to a [Microsoft Research study](https://www.aclweb.org/anthology/W04-3238.pdf), roughly 10-15% of the queries sent to search engines contain errors. A misspelled search keyword often results in poor search quality, and users have been accustomed to Google's automatic spelling correction functionality and expect the same on your site. However, correcting spelling and typos at scale is a non-trivial machine learning problem. Miso's spellcheck is based on a sequence-to-sequence deep learning model, trained and updated regularly on a corpus of billion tokens. It detects hard-to-spot errors, auto-correct keywords according to its context, and recognize terms that are newer or lesser known. Spellcheck is always on for every search request so you don't need to turn it on. What you need to decide is whether to turn on *auto spelling correction*. For example, the following search request turns on the auto-spelling-correction, and Miso will automatically replace any misspelled queries with their correct spelling: ``` POST /v1/search/search { "q":"whte denem jeans", "user_id":"user-123", "spellcheck":{ "enable_auto_spelling_correction":true } } ``` The API will respond: ```javascript { "message":"success", "data":{ "took":50, "total":30, "start":0, "miso_id":"f34b90de-086b-11eb-b498-1ee8abb1818b", "spellcheck":{ "spelling_errors":true, "auto_spelling_correction":true, "original_query":"whte denem jeans", "original_query_with_markups":"<mark>whte</mark> <mark>denem</mark> jeans", "corrected_query":"white denim jeans", "corrected_query_with_markups":"<mark>white</mark> <mark>denim</mark> jeans" }, "products":[ ...... ] } } ``` The *spellcheck* object contains the following fields: * **spelling_errors** indicates whether there is a spelling error in the query * **auto_spelling_correction** indicates whether the search query has been replaced with the *corrected_query* * **original_query** the original search query * **original_query_with_markups** the original search query with the misspelled words highlighted by `` html tags * **corrected_query** the search query with misspelling and typos corrected * **corrected_query_with_markups** the search query with misspelling and typos corrected, and the corrected parts are highlighted by `` html tags You can opt-out the auto-spelling-correction by setting `enable_auto_spelling_correction=false`. For example: ``` POST /v1/search/search { "q":"whte denem jeans", "user_id":"user-123", "spellcheck":{ "enable_auto_spelling_correction":false } } ``` In this case, Miso will still run spellcheck against the query. However, users' queries will be used as it is, and **auto_spelling_correction** field will be *false*. ### Boosting and Diversification While Miso's personalized search can drive conversion by showing search results that are tailored to users' interests, ultimately, it is important to make sure that the search results meet your business goals. To that end, Miso provides a great set of tools that enable you to fine-tune the search ranking and make it aligned with your goals. One great example is **boosting**. Boosting allows you to define a query that can be used to boost a subset of products to the top of the ranking, or to specific *boost positions*. You can use boosting to run different kinds of promotion campaigns, or to promote certain set of products for individual users that you know they will be interested in. For example, consider a scenario where you need to promote the sales of Nike's products. Then, you might want to use the query below, that will promote the sneakers whose brand are `Nike` to the top of the search result: ``` POST /v1/search/search { "q":"sneaker", "user_id":"user-123", "boost_fq": "brand:\"Nike\"" } ``` For a slightly more complex example, the query below will promote the Nike products which have also been tagged as `ON SALE`: ``` POST /v1/search/search { "q":"sneaker", "user_id":"user-123", "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"" } ``` You can have as complex boosting logic as you want in the boosting query, but it is worth mentioning that Miso will only boost products that are relevant and have high likelihood to convert. In other words, Miso will not boost low performance products even if they match the boosting query. Depending on your boosting rules, in certain cases, you would like to prevent search results from becoming too "plain" due to boosting. For example, you don't want the first page of the search result to contain only Nike products. With Miso, you have two tools to avoid so. First, you can specify `boost_positions` to place boosted products at specific positions in the ranking. For example, the query below will place boosted products only at the first, fourth, seventh places in the ranking (positions are 0-based), and place the remaining products in their original ranking, skipping these three positions. ``` POST /v1/search/search { "q":"sneaker", "user_id":"user-123", "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "boost_positions": [0, 3, 6] } ``` The second tool is `diversification`. Miso's `diversification` algorithm will maintain a desired minimum distance between any two products that have the same attributes. For example, the following query will make sure products made by the same *brand* are at least two slots apart from each other in the search results. ``` POST /v1/search/search { "q":"sneaker", "user_id":"user-123", "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "diversification": { "brand": {"minimum_distance": 2} } } ``` It is also very often to use both "boost_positions" and "diversification" at the same time to make sure that (1) the search results are not overwhelmed by the boosted products, and (2) there is a good mix of products from different brands showing side-by-side to increase product discovery rate. ### Result ordering You can override Miso's default ranking order by specifing a list of fields for Miso to rank the search results. These fields can be any numeric or boolean fields in your Product catalog, or one of the following special fields: * **_personalization_score**: the score that estimates the probability that a user will interact with a product determined by Miso's personalization algorithm. The range of this score is between [0, 1]. The scores are non-uniformly distributed. The Products that are relevant to users' interests will have scores much closer to 1, than products that are not. * **_search_score**: the score that rates the degree of "match" between search keywords and a product's catalog with a focus on Product's titles. This score is mostly based on a variant of [BM25](https://en.wikipedia.org/wiki/Okapi_BM25), but additionally consider the term proximity, typos, term semantic similarity. Its value is always larger than 0, but its range is unbounded. * **_boosting_score**: a binary score indicates whether a Product is boosted by your boosting query. * **_geo_distance**: distance between any point on map, `geo` must be specified when sorting with this field. For example, the following query returns all the Products (because `q=*`), ranked by the `_personalization_score` first, and then by the values in the `custom_attributes.promote_score` field in the Product catalog, then the distance between the product and New York city. ``` { "q": "*", "order_by": [ { "field": "_personalization_score", "tie_breaker": { "type": "relative_difference", "threshold": "0.05" }, "order": "desc" }, { "field": "custom_attributes.promote_score", "order": "desc" }, { "field": "_geo_distance", "geo": { "lat": 40.711967, "lon": -74.006076, } "order": "asc" } ] } ``` #### Mathematical Functions Miso supports mathematical functions that transform and combine different sorting criteria into one. For example, a powerful strategy to improve gross merchandise volume (GMV), but maintain user experience is to sort the products based on the multiplication of personalization scores and product prices. You can achieve this with the following `order_by` query: ``` { "q": "*", "order_by": [ { "field": "_personalization_score * pow(sale_price, 0.5)", "order": "desc" } ] } ``` Function `pow(sale_price, 0.5)` takes the square root of the sale price and avoids very expensive products from overwhelming the ranking. Miso supports all the common mathematical operators including `+`, `-`, `*`, `/`, `%`, `^`, `**`, and more advanced functions including: * Power functions: `pow(X, y)`, `sqrt(X)` * Exponents and logarithms: `exp(X)`, `log(X)`, `log2(X)`, `log10(X)` * Element-wise maximum / minimum: `maximum(X, y)`, `minimum(X, y)` * Absolute function: `abs(X)` * Rounding functions: `round(X)`, `floor(X)`, `ceil(X)` * Trigonometric functions: `sin(X)`, `cos(X)`, `tan(X)`, `asin(X)`, `acos(X)`, `atan(X)` #### Soft Tie-Breaker For scores that have granular resolutions, for example `_personalization_score`,`_search_scores`, or Products' `sale_price`, we usually don't want to rank Products by their raw values. After all, a 0.001 difference in `_personalization_score` or $0.01 difference in sale price typically will not make a difference in users' preferences. In such cases, *soft* tie-breakers should be used to smooth out these minor differences in scores. For example, in the query above, we apply a soft tie-breaker to `_personalization_score` based on score values' relative difference. Specifically, we first sort the score's raw values in the descending order, then for two consecutive values, if their relative difference is no more than a pre-defined threshold (in this case `0.05` or `5%`), they are considered as a tie, and the next field (i.e. `custom_attributes.promote_score`) will be used to determine their ranking. It is also common to utilize tie-breakers to combine the effect of two types of scores. For example, in the following query, we set `threshold=0.2` or `20%` for `_personalization_score`, then only the Products that users are 20% more likely to interact with will be ranked higher, the remaining Products will be ranked by their sale prices. In this way, we combine the effect of personalization score and sale prices, where the Products are roughly ranked by personalization, but favor the pricier products when they have comparable personalization scores. ``` { "q": "*", "order_by": [ { "field": "_personalization_score", "tie_breaker": { "type": "relative_difference", "threshold": "0.20" }, "order": "desc" }, { "field": "sale_price", "order": "desc" } ] } ``` Also note that, when search keywords are present, it is recommended to always include `_search_score` as the first field (plus a tie-breaker) to maintain the relevance of the search results. A tie-breaker is usually required as well to let the subsequent score have effect to the ranking. ``` { "q": "toy story", "order_by": [ { "field": "_search_score", "tie_breaker": { "type": "relative_difference", "threshold": "0.20" }, "order": "desc" }, { "field": "_personalization_score", "tie_breaker": { "type": "relative_difference", "threshold": "0.20" }, "order": "desc" }, { "field": "sale_price", "order": "desc" } ] } ``` ## OpenAPI ````yaml post /v1/search/search openapi: 3.0.2 info: title: Miso API description: > # Overview Miso’s approach to personalization is to train machine learning Engines on three core data sets: 1. Your site’s log of historical and real-time interactions, 2. Your catalog of products and content, and 3. Your users. Miso provides the output of its Engines to you, so you can build search and recommendation experiences that are personalized down to the individual level (n=1 personalization). To see how Miso works and explore the power of its Engines, we recommend following [this tutorial](https://docs.askmiso.com/) to get started with our Playground data. Integrating your site or application with Miso happens in three basic steps: 1. Upload your data 2. Train your Engines 3. Build search and recommendation experiences with the output of your Engines. Miso provides two main integration points. The first is your [Dojo Dashboard](https://dojo.askmiso.com/), which is used to set up your Engines with the conversions you want to optimize and your training schedule. Dojo is also a great way to get familiar with Miso by manually uploading data and exploring the output of Miso’s Engines. In Dojo’s Sandboxes, you can tweak your Engine settings and see visual examples of Miso’s search and recommendations running on your live data. The second integration point is Miso’s API, which lets you automatically manage your data in Miso and build experiences that leverage the output of Miso’s personalization Engines. Miso’s API is composed of two major groups of REST API endpoints: Data APIs and Engine APIs. ### Data APIs Data APIs collect input to Miso's personalization Engines. These APIs all support high-throughput data ingestion through bulk insert, and satisfy GDPR and CCPA compliance by letting users delete their data from Miso. Subcategories of Data APIs are: * [Interaction APIs](#tag/Interaction-APIs), for managing your Interaction records. By uploading historical and real-time Interaction records, you tell Miso how users are engaging with the products and content on your site, and in turn, Miso’s Engines learn how to optimize your conversion funnels. * [Product / Content APIs](#tag/Product-Content-APIs), for managing your Product / Content records. These records provide a deep semantic understanding of your catalog and keep Miso up to date about your offerings so it can make smart and timely suggestions. The `product_id` is how Miso links Product / Content records to your Interaction records. * [User APIs](#tag/User-APIs), for managing your User records. These records tell Miso about your site’s users and visitors, so Miso can build an understanding of user segmentation and behavior in relation to products and content. The `user_id` is how Miso links User records to your Interaction records. As a rule of thumb, we recommend batching up data to avoid timeout risks. For the Product / Content and User Upload APIs, we recommend limiting each API upload call to about 100 records at a time. For the Interaction Upload API, we recommend limiting your calls to around 10,000 records at a time. ### Engine APIs Engine APIs provide the output of Miso's personalization Engines. We designed these APIs with a focus on low latency and high availability. Most of these APIs' 95th percentile response time is under 75ms, and the services are replicated to at least three separate instances for high availability. The types of Engine APIs are: * [Search APIs](#tag/Search-APIs), for getting Miso’s personalized search results for a user, with search-as-you-type and autocompletion. * [Recommendation APIs](#tag/Recommendation-APIs), for retrieving Miso’s recommendations that match users with the products, categories, and product attributes that are likely to drive conversions. # Authentication [View your API Keys in your Dojo Dashboard.](https://dojo.askmiso.com/docs/api-browser) There are three environments in Miso: * **Playground**, a read-only tutorial environment with sample data. * **Development**, for staging, QA, and experimentation. * **Production**, where you run your live integration with Miso. Access a Miso environment by passing in the corresponding API key in your API calls. There is one publishable key and one secret key per environment. API Key can passed with query parameter `api_key`, or using the `X-API-KEY` header. version: 1.1.4 servers: - url: https://api.askmiso.com security: [] tags: - name: Experiment APIs description: > Miso's experiment APIs let you do the A/B testing of your current result with Miso. ### Start an experiment in Dojo. Login to the [dojo](https://dojo.askmiso.com) platform. Create an experiment event for you. ### Start running A/B testing in your environment. #### Implement A/B testing code. Here's an example in NodeJS. You can also use any programming language of you choice. ```nodejs const axios = require('axios'); async function get_user_experiment_info(api_key, experiment_id, user_id) { data = {"user_id": user_id} endpoint = `https://api.askmiso.com/v1/experiments/${experiment_id}/events?api_key=${api_key}` return await axios.post(endpoint, data) } const api_key = '' const experiment_id = "" let user_id = 'user_1234' // use to evaluate a treatment for const user_experiment_info = get_user_experiment_info(api_key, experiment_id, user_id) user_experiment_info.then((response) => { let variant = response.data['variant'] if (variant['name'] == "treatment") { // insert code here to show "treatment" variant } else if (variant['name'] == "control") { // insert code here to show "control" variant } else { // unexpected variant name. raise error throw new Error(`Unexpected variant name ${variant["name"]}`) } }) ``` If you implement A/B testing code in FrontEnd, like JavaScript, and are also worried about exploding the secret api_key. You can choose to use anonymous_id with the public_api_key for this API. Here's an example. ```javascript const apiKey = ''; const experimentId = ''; const anonymous_id = 'user_1234'; // use to evaluate a treatment for function getUserExperimentInfo(apiKey, experimentId, anonymous_id) { const data = { user_id: anonymous_id }; const url = `https://api.askmiso.com/v1/experiments/${experimentId}/events?api_key=${apiKey}`; const options = { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(data), }; return window.fetch(url, options) .then((response) => response.json()) .then((data) => { const variantName = data.variant.name; if (variantName === `${this.treatmentName}`) { // insert code here to show 'treatment' variant } else if (variantName === `${this.controlName}`) { // insert code here to show 'control' variant } else { // unexpected variant name, throw error throw new Error(`Unexpected variant name: ${variantName}`); } }) .catch((error) => console.error(error)); } getUserExperimentInfo(apiKey, experimentId, anonymous_id); ``` - name: Interaction APIs description: >+ Miso’s Interaction APIs let you manage your Interaction records stored with Miso. ### Interaction records Your Interaction records tell Miso about user interactions with products and content on your site or application. From these interactions, Miso understands how users move through your conversion funnels: which products or content assets attract the attention of each individual user, and which products or content ultimately will be purchased or consumed by each of them. With these insights, Miso makes real-time tailored recommendations for each user, and responds to each of their clicks and views on the site (even for anonymous users). Interaction records share some common attributes, but are distinguished by their type. Miso captures 23 different interaction types, divided into the following 6 groups: #### Core click-streams * `product_detail_page_view`: a user viewed the detail page for a product * `search`: a user made a search request with keywords and (optionally) filters The above interactions are the core fuel for Miso's personalization Engines, because they happen in a much higher frequency than other interactions and provide an unbiased and high-fidelity view of users' interests on the site. The collection of these interactions is highly important for Miso's personalization performance. At the minimum, you should implement the `product_detail_page_view` interaction to start with. #### Conversion (eCommerce) * `add_to_cart`: a user added a product to the shopping cart * `remove_from_cart`: a user removed a product from the shopping cart * `checkout`: a user checked out and started the payment process * `refund`: a user refunded the product * `subscribe`: a user subscribed to a product The above interactions are the main revenue drivers for eCommerce sites. It’s important to collect them so that Miso can not only drive click-through rates, but actually improve the revenue in a targeted way. To start with, you should at least implement the `add_to_cart` interaction. #### Consumption (content media) * `read`, `watch`, and `listen` interactions capture how and for how long a user consumed a piece of content. * `add_to_collection`: a user added an product to their personal collection * `remove_from_collection`: a user removed an product from their personal collection If you are a content site, the above interactions are the main drivers to users' satisfaction on the site. Collecting these interactions allows Miso to drive consumption rates and consumption durations for the content on your site. If you run a content site, you should implement at least one of these interactions. #### Feedback signals * `like`, `dislike`, `share`, `rate`, and `bookmark` are common ways users express their interests. These are strong signals for Miso to understand each user's preferences regarding your products or content. You should send these signals to Miso if you have any of these UI patterns on your site. #### Performance Checking * `impression`: a user saw or was presented with a product or content asset (but didn't yet interact with it) * `viewable_impression`: the product or content presented is actually viewed by the user (for example, minimum of 50% of the pixels were in viewable space for at least one continuous second.) * `click`: a user clicked on something (for example, a product item) #### Additional click-streams * `home_page_view`: user viewed your home page * `category_page_view`: a user viewed the page for a specific “group” or “family” or products or content in your catalog * `promo_page_view`: user viewed the promotion pages about certain products * `product_image_view`: user clicked on or otherwise interacted with the product image (e.g. enlarged the image) The above interactions are additional signals for Miso to understand users' behavior on the site. #### Custom * `custom` interaction types are reserved for you to define your own business-specific interaction types. Miso will analyze any custom interactions you define to infer users' interests and preferences. - name: Product / Content APIs description: >+ Miso's Product / Content APIs let you upload, read, and delete Product / Content records that represent your site's catalog. ### Product / Content records Miso analyzes your Product / Content records to provide personalized search and recommendations that connect users with products or content on your site or application. Much of Miso's search and personalization capability relies on understanding your catalog in-depth and drawing correlations between your catalog and your users' consumption or purchasing behaviors. In other words, Miso discovers that, with high correlation, users who are interested in certain product attributes would also be interested in other products with similar or related attributes. (For simplicity, we will often overload the word "products" to mean items for purchase if you are an eCommerce business, and content to consume if you are a content marketplace.) To fully optimize your search and recommendations, it is important to provide Miso with Product / Content records that are complete and accurate. We define a set of common attributes that capture the basics of most eCommerce and content media products, such as `title`, `description`, `categories`, `tags`, `material`, `authors`, etc. If your products' characteristics cannot be fully captured by these fields, we recommend that you specify `custom_attributes`. For Miso, the more complete the product information is, the better its personalized search and recommendations become. - name: User APIs description: >+ Miso’s User APIs let you upload, read, and delete User records that tell Miso about your site’s unique users and visitors. ### User records User records specify relatively static attributes for a given user, such as their `age`, `gender`, `city`, etc. As a rule of thumb, you should put information here that is not already captured in your [Interaction records](#tag/Interaction-APIs). For example, *last_bought_product* is probably not needed here because Miso already can tell that from the [Interaction records](#tag/Interaction-APIs). Miso will discover the correlations between a user's attributes and their behaviors on your site. For example, Miso might determine that users of a certain age group tend to be interested in certain products or a certain price range. These insights will be taken into account when predicting users' interests, in particular for new users who have not yet generated many interaction records. We define a set of common user attributes for e-Commerce and content media sites. Some of them, such as `name` are for display in the Dojo dashboard only. The rest are for model quality. Most attributes are optional and you don't need to specify them if you don't collect such data. On the other hand, you can specify your custom user attributes in the `custom_attributes` field. Miso will analyze custom user attributes to improve the model quality as well. - name: Bulk API description: > The Bulk API provides an efficient interface for making multiple Search / Recommendations / Q&A requests in one API call. These requests will be executed concurrently at the Miso side, and returned at once when all of them are finished. This API is particularly useful when you need to invoke multiple Miso APIs to respond to a user request. Using this API, you can batch multiple API calls into one, and significantly save the network round-trip times. ### Request schema The request schema for this API call is as follow: ``` POST /v1/bulk { "requests": [ { "api_name": "search/search", "body": { ... } }, { "api_name": "recommendation/product_to_product", "body": { ... } }, ... ] } ``` Each request object should contain: * **api_name**: name of the API you want to access. The name should contain a slash `/`. For example, search/search for search requests, search/autocomplete for autocomplete requests, etc. * **body**: the complete request body as if you are making the API request individually. Any errors in one of the requests will be returned, and will not prevent other requests from being executed. ### Response Schema Bulk API endpoint will return the API responses in the same order as they appear in the request. For example, if the Bulk API request is like the following: ``` POST /v1/bulk { "requests": [ {... request 1 ...}, {... request 2 ...} ] } ``` The response will be like: ``` { "data": [ // response for request 1 { "error": false, "status_code": 200, "body": { ... } }, // response for request 2 { "error": false, "status_code": 200, "body": { ... } } ] } ``` Each response object will contain the following fields: * **error**: whether there was an error with the request. You should check this field to determine whether to perform error handling. * **status_code**: status code of the request. * **body**: the response body of the request (as if the request was sent individually). Let's see a complete example with MovieLens data. The following requests will issue two requests in one API call that return the `Sci-Fi` movies directed by *Ridley Scott*, and *James Cameron* respectively in the first and second responses: ``` POST /v1/bulk { "requests": [ { "api_name": "search/search", "body": { "user_id": "test_user", "q": "sci-fi", "fq": "custom_attributes.director:\"Ridley Scott\"" } }, { "api_name": "search/search", "body": { "user_id": "test_user", "q": "sci-fi", "fq": "custom_attributes.director:\"James Cameron\"" } } ] } ``` The response will be like: ``` { "data": [ { "error": false, "status_code": 200, "body": { "data": { "took": 136, "miso_id": "19ab254c-5fb8-11ec-bd48-b20169940af9", "products": [ { "product_id": "blade-runner", "title": "Blade Runner (1982)" } ], "total": 6, "start": 0 } } }, { "error": false, "status_code": 200, "body": { "data": { "took": 116, "miso_id": "19ab254c-5fb8-11ec-bd48-b20169940af9", "products": [ { "product_id": "avatar", "title": "Avatar (2009)" } ], "total": 10, "start": 0 } } } ] } ``` - name: Ask APIs description: >+ Miso's new Ask API is the next generation of question answering APIs. It is designed to provide accurate and concise answers to your questions based on your existing product documents. Ask API offers a seamless and effective way to address complex queries in a near-realtime fasion. Miso preprocesses your product documents, breaking them into segments. When a question is received, Miso finds the most related product and segments, then summarize to a concise and informative answer based on the identified segments, including products related to the question. Possible use case includes: knowledge base, documentation search, customer support, and more. To use the Ask API, you first submit a "question" you want to ask. Question can be any human-readable text. Then a question ID will returned, and the question will be processed in the background. After receving question ID, you can then use the question ID to get latest answer to the question as it is being compiled. ---- For example: If you want to know about the inner workings of nginx: ```json { "question":"How nginx works internally?" } ``` The API would response with a question id. ```json { "data": { "question_id": "ff4775fa-345e-4d28-91b0-8fb8bf095e6a" }, "message": "success" } ``` Then you can send a GET request to `/v1/ask/questions/{question_id}/answer` to get the latest answer as it is being compiled and summerized. You can use `answer_stage` and `finished` to check current answer status. Here's the response of answer API when data is fetched and being verified, before answer is summerized: ```json { "message": "success", "data": { "question": "How nginx works internally?", "question_id": "ff4775fa-345e-4d28-91b0-8fb8bf095e6a", "parent_question_id": null, "answer_stage": "Verifying possible answers", "finished": false, "answer": "Verifying possible answers ...", "sources": [], "related_resources": [], "followup_questions": [] } } ``` Here's the response when answer is fullly summerized: ```json { "message": "success", "data": { "question": "How nginx works internally?", "question_id": "ff4775fa-345e-4d28-91b0-8fb8bf095e6a", "parent_question_id": null, "answer_stage": "Generating summary", "finished": true, "answer": "# How does Nginx work internally?\n\n## Internal requests [1]\n\nNginx differentiates between external and internal requests. External requests...[omitted for simplicity]", "sources": [ { "title": "Internal requests", "product_id": "9781788623551", "child_title": "Internal requests", "child_id": "203", "snippet": "<mark>Internal requests\nNginx differentiates external and internal requests.</mark>" }, { "title": "5. Nginx Core Architecture", "product_id": "9781484216569", "child_title": "5. Nginx Core Architecture", "child_id": "5", "snippet": "Checks if the client can access of the requested the resource.\n<mark>It is at this step that Nginx...[omitted]</mark>" }, { "title": "2. Managing Nginx", "product_id": "9781785289538", "child_title": "2. Managing Nginx", "child_id": "14", "snippet": "<mark>The Nginx connection processing architecture\nBefore you study...[omitted]</mark>" }, { "title": "3. Nginx Core Directives", "product_id": "9781484216569", "child_title": "3. Nginx Core Directives", "child_id": "3", "snippet": "<mark>Understanding the Default Configuration\nThe default configuration...[omitted]</mark>" }, { "title": "4. Nginx Modules", "product_id": "9781484216569", "child_title": "4. Nginx Modules", "child_id": "4", "snippet": "<mark>Based on the context like HTTP, MAIL, and STREAM, it creates a ...[omitted]</mark>" } ], "related_resources": [], "followup_questions": [ "What are the steps involved in processing a request and generating a response in Nginx?", "How do Nginx modules contribute to the internal workings of Nginx?" ] } } ``` Related product IDs will be returned along with human-readable answer. Related text section in the product will also be quoted. If a product has any children, they will also be matched, `child_id` and `child_title` will be included for sources belonging to the product's children. You can use `fq` to limit the search scope, for example, to a specific product type or other condition. If you only want to search for books (no articles of videos), you can use `fq=type:book` like this: ```json { "question":"How nginx works internally?" "fq": "type:book" } ``` If you want the answer to contain any other fields, set `source_fl` when submitting the question. - name: User Recommendations description: >- APIs for recommending products and content to users based on their interests. - name: Product Recommendations description: APIs for recommending related products based on a given product. paths: /v1/search/search: post: tags: - Search APIs summary: Search API description: >- The Search API provides personalized, typo-correcting, semantic search for your site. You send this API the search queries users entered, and the API returns the relevant search results tailored to your users' interests. ### Personalized search Personalized search is a key factor in driving search conversion on many major sites. It is particularly powerful for short search queries (≤ 3 keywords), which account for [up to 80% of search traffic in the U.S.](https://www.statista.com/statistics/269740/number-of-search-terms-in-internet-research-in-the-us/), but are usually the hardest to get right with traditional search engines. This is because shorter search queries tend to match a larger number of results, but there is not enough information in the query strings alone to determine which results the users are actually looking for. For example, when users search for *jeans* on Levi's.com, it is impossible to know which *jeans* the user is looking for, among thousands of options. Even if the user adds: *jeans for men*, it is still unclear to a traditional search engine what style, material, or size the user wants. In the contrary, with Miso's personalized search, we not only analyze the search query itself, but also take into account the *context* in which the searches are made, including who are the users, where are they from, what are their past interactions on the site, what other searches the user made, etc. These signals together allow Miso to generate more than 15% to 20% higher search conversion rate than the traditional non-personalized search engines. ### Balancing relevancy and personalization Although personalization is a powerful technique, over-using it can be harmful to the user experiences. In the context of search optimization, the relevancy of the search results are still the most important criteria, and we don't want personalization to overwhelm the search relevancy. For example, when users search for a very specific term, or directly search for the product names, Miso's algorithm will respond with the most relevant search results first, and then only apply personalization to rerank more ambiguous search results. ### Basic usage For every search query, you let Miso know the user's `user_id` and the search keywords in the API request body, for example: ``` POST /v1/search/search { "q": "jeans", "user_id": "user-123" } ``` For site visitors who do not sign in, you can let Miso know the `anonymous_id` of this visitor: ``` POST /v1/search/search { "q": "jeans", "anonymous_id": "visitor-123" } ``` ### Search response With the query above, Miso responds with the search results like the following: ```javascript { "message":"success", "data":{ "took":50, "total":30, "start":0, "miso_id":"f34b90de-086b-11eb-b498-1ee8abb1818b", "products":[ { "product_id":"505-regular-fit-mens-jeans", "title":"The 505 Regular Fit Men's Jeans", "url":"https://levi.com/jeans/505-regular-fit-mens-jeans/", "size":"29", "material":"Cotton", "color":"Rinse - Dark Wash", "_search_score": 78.12, "_personalization_score": 0.98 } ], "spellcheck":{ "spelling_errors":false } } } ``` * **took**: the amount of time (in milliseconds) Miso took to answer the query * **total**: the total number of matched products. You can paginate through all the products by using the combination of *start* and *rows* parameters (see *Request Body Schema* below) * **miso_id**: a UUID of the search request. You should include **miso_id** in the Interaction records for every interactions that result from this search request, e.g. user click-through a product in the search results. Miso use miso_id to track the search performance and fine-tune the algorithm accordingly. * **products**: an array of [Product records](#operation/content_write_api_v1_products_post) that match the search query, ranked in the order of relevancy and probability that the user will be interested in this product. By default, only the `product_id` of the Product is returned. You can ask Miso to return additional fields by using the *fl* parameter (see *Request Body Schema* below) * **products[ ]._search_score**: the search relevancy score of the products based on keyword matching and Miso's semantic matching. This score is similar to traditional Lucene search score. * **products[ ]._personalization_score**: the score assigned by Miso's personalization algorithm based on users' profile and their interactions on the site. This score quantifies the probability of whether users will be interested in this product or not. * **spellcheck**: an dictionary contains spell checking information. ### Spellcheck and auto-correction According to a [Microsoft Research study](https://www.aclweb.org/anthology/W04-3238.pdf), roughly 10-15% of the queries sent to search engines contain errors. A misspelled search keyword often results in poor search quality, and users have been accustomed to Google's automatic spelling correction functionality and expect the same on your site. However, correcting spelling and typos at scale is a non-trivial machine learning problem. Miso's spellcheck is based on a sequence-to-sequence deep learning model, trained and updated regularly on a corpus of billion tokens. It detects hard-to-spot errors, auto-correct keywords according to its context, and recognize terms that are newer or lesser known. Spellcheck is always on for every search request so you don't need to turn it on. What you need to decide is whether to turn on *auto spelling correction*. For example, the following search request turns on the auto-spelling-correction, and Miso will automatically replace any misspelled queries with their correct spelling: ``` POST /v1/search/search { "q":"whte denem jeans", "user_id":"user-123", "spellcheck":{ "enable_auto_spelling_correction":true } } ``` The API will respond: ```javascript { "message":"success", "data":{ "took":50, "total":30, "start":0, "miso_id":"f34b90de-086b-11eb-b498-1ee8abb1818b", "spellcheck":{ "spelling_errors":true, "auto_spelling_correction":true, "original_query":"whte denem jeans", "original_query_with_markups":"<mark>whte</mark> <mark>denem</mark> jeans", "corrected_query":"white denim jeans", "corrected_query_with_markups":"<mark>white</mark> <mark>denim</mark> jeans" }, "products":[ ...... ] } } ``` The *spellcheck* object contains the following fields: * **spelling_errors** indicates whether there is a spelling error in the query * **auto_spelling_correction** indicates whether the search query has been replaced with the *corrected_query* * **original_query** the original search query * **original_query_with_markups** the original search query with the misspelled words highlighted by `` html tags * **corrected_query** the search query with misspelling and typos corrected * **corrected_query_with_markups** the search query with misspelling and typos corrected, and the corrected parts are highlighted by `` html tags You can opt-out the auto-spelling-correction by setting `enable_auto_spelling_correction=false`. For example: ``` POST /v1/search/search { "q":"whte denem jeans", "user_id":"user-123", "spellcheck":{ "enable_auto_spelling_correction":false } } ``` In this case, Miso will still run spellcheck against the query. However, users' queries will be used as it is, and **auto_spelling_correction** field will be *false*. ### Boosting and Diversification While Miso's personalized search can drive conversion by showing search results that are tailored to users' interests, ultimately, it is important to make sure that the search results meet your business goals. To that end, Miso provides a great set of tools that enable you to fine-tune the search ranking and make it aligned with your goals. One great example is **boosting**. Boosting allows you to define a query that can be used to boost a subset of products to the top of the ranking, or to specific *boost positions*. You can use boosting to run different kinds of promotion campaigns, or to promote certain set of products for individual users that you know they will be interested in. For example, consider a scenario where you need to promote the sales of Nike's products. Then, you might want to use the query below, that will promote the sneakers whose brand are `Nike` to the top of the search result: ``` POST /v1/search/search { "q":"sneaker", "user_id":"user-123", "boost_fq": "brand:\"Nike\"" } ``` For a slightly more complex example, the query below will promote the Nike products which have also been tagged as `ON SALE`: ``` POST /v1/search/search { "q":"sneaker", "user_id":"user-123", "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"" } ``` You can have as complex boosting logic as you want in the boosting query, but it is worth mentioning that Miso will only boost products that are relevant and have high likelihood to convert. In other words, Miso will not boost low performance products even if they match the boosting query. Depending on your boosting rules, in certain cases, you would like to prevent search results from becoming too "plain" due to boosting. For example, you don't want the first page of the search result to contain only Nike products. With Miso, you have two tools to avoid so. First, you can specify `boost_positions` to place boosted products at specific positions in the ranking. For example, the query below will place boosted products only at the first, fourth, seventh places in the ranking (positions are 0-based), and place the remaining products in their original ranking, skipping these three positions. ``` POST /v1/search/search { "q":"sneaker", "user_id":"user-123", "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "boost_positions": [0, 3, 6] } ``` The second tool is `diversification`. Miso's `diversification` algorithm will maintain a desired minimum distance between any two products that have the same attributes. For example, the following query will make sure products made by the same *brand* are at least two slots apart from each other in the search results. ``` POST /v1/search/search { "q":"sneaker", "user_id":"user-123", "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "diversification": { "brand": {"minimum_distance": 2} } } ``` It is also very often to use both "boost_positions" and "diversification" at the same time to make sure that (1) the search results are not overwhelmed by the boosted products, and (2) there is a good mix of products from different brands showing side-by-side to increase product discovery rate. ### Result ordering You can override Miso's default ranking order by specifing a list of fields for Miso to rank the search results. These fields can be any numeric or boolean fields in your Product catalog, or one of the following special fields: * **_personalization_score**: the score that estimates the probability that a user will interact with a product determined by Miso's personalization algorithm. The range of this score is between [0, 1]. The scores are non-uniformly distributed. The Products that are relevant to users' interests will have scores much closer to 1, than products that are not. * **_search_score**: the score that rates the degree of "match" between search keywords and a product's catalog with a focus on Product's titles. This score is mostly based on a variant of [BM25](https://en.wikipedia.org/wiki/Okapi_BM25), but additionally consider the term proximity, typos, term semantic similarity. Its value is always larger than 0, but its range is unbounded. * **_boosting_score**: a binary score indicates whether a Product is boosted by your boosting query. * **_geo_distance**: distance between any point on map, `geo` must be specified when sorting with this field. For example, the following query returns all the Products (because `q=*`), ranked by the `_personalization_score` first, and then by the values in the `custom_attributes.promote_score` field in the Product catalog, then the distance between the product and New York city. ``` { "q": "*", "order_by": [ { "field": "_personalization_score", "tie_breaker": { "type": "relative_difference", "threshold": "0.05" }, "order": "desc" }, { "field": "custom_attributes.promote_score", "order": "desc" }, { "field": "_geo_distance", "geo": { "lat": 40.711967, "lon": -74.006076, } "order": "asc" } ] } ``` #### Mathematical Functions Miso supports mathematical functions that transform and combine different sorting criteria into one. For example, a powerful strategy to improve gross merchandise volume (GMV), but maintain user experience is to sort the products based on the multiplication of personalization scores and product prices. You can achieve this with the following `order_by` query: ``` { "q": "*", "order_by": [ { "field": "_personalization_score * pow(sale_price, 0.5)", "order": "desc" } ] } ``` Function `pow(sale_price, 0.5)` takes the square root of the sale price and avoids very expensive products from overwhelming the ranking. Miso supports all the common mathematical operators including `+`, `-`, `*`, `/`, `%`, `^`, `**`, and more advanced functions including: * Power functions: `pow(X, y)`, `sqrt(X)` * Exponents and logarithms: `exp(X)`, `log(X)`, `log2(X)`, `log10(X)` * Element-wise maximum / minimum: `maximum(X, y)`, `minimum(X, y)` * Absolute function: `abs(X)` * Rounding functions: `round(X)`, `floor(X)`, `ceil(X)` * Trigonometric functions: `sin(X)`, `cos(X)`, `tan(X)`, `asin(X)`, `acos(X)`, `atan(X)` #### Soft Tie-Breaker For scores that have granular resolutions, for example `_personalization_score`,`_search_scores`, or Products' `sale_price`, we usually don't want to rank Products by their raw values. After all, a 0.001 difference in `_personalization_score` or $0.01 difference in sale price typically will not make a difference in users' preferences. In such cases, *soft* tie-breakers should be used to smooth out these minor differences in scores. For example, in the query above, we apply a soft tie-breaker to `_personalization_score` based on score values' relative difference. Specifically, we first sort the score's raw values in the descending order, then for two consecutive values, if their relative difference is no more than a pre-defined threshold (in this case `0.05` or `5%`), they are considered as a tie, and the next field (i.e. `custom_attributes.promote_score`) will be used to determine their ranking. It is also common to utilize tie-breakers to combine the effect of two types of scores. For example, in the following query, we set `threshold=0.2` or `20%` for `_personalization_score`, then only the Products that users are 20% more likely to interact with will be ranked higher, the remaining Products will be ranked by their sale prices. In this way, we combine the effect of personalization score and sale prices, where the Products are roughly ranked by personalization, but favor the pricier products when they have comparable personalization scores. ``` { "q": "*", "order_by": [ { "field": "_personalization_score", "tie_breaker": { "type": "relative_difference", "threshold": "0.20" }, "order": "desc" }, { "field": "sale_price", "order": "desc" } ] } ``` Also note that, when search keywords are present, it is recommended to always include `_search_score` as the first field (plus a tie-breaker) to maintain the relevance of the search results. A tie-breaker is usually required as well to let the subsequent score have effect to the ranking. ``` { "q": "toy story", "order_by": [ { "field": "_search_score", "tie_breaker": { "type": "relative_difference", "threshold": "0.20" }, "order": "desc" }, { "field": "_personalization_score", "tie_breaker": { "type": "relative_difference", "threshold": "0.20" }, "order": "desc" }, { "field": "sale_price", "order": "desc" } ] } ``` operationId: search_v1_search_search_post requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - Secret API Key: [] components: schemas: SearchRequest: title: SearchRequest type: object properties: engine_id: title: Engine Id type: string description: > The engine you want to get results from. When you have more than one engine, you can use this parameter to specify the specific engine you want to get results from. If not specified, the default engine will be used. user_id: title: User Id type: string description: > The user who made the query and for whom Miso will personalize the results. For an anonymous visitor, use `anonymous_id` instead. anonymous_id: title: Anonymous Id type: string description: >- The anonymous visitor who made the query and for whom Miso will personalize the results. Either `user_id` or `anonymous_id` needs to be specified for personalization to work. user_hash: title: User Hash type: string description: > The hash of `user_id` (or `anonymous_id`) encrypted by your [Secret API Key](#section/Authentication/Secret%20API%20Key). `user_hash` is required to prevent unauthorized API access if you are making API calls with a [Publishable API Key](#section/Authentication/Publishable%20API%20Key). You should generate the user_hash via HMAC scheme: you encrypt the desired user_id (or anonymous_id) with your [Secret API Key](#section/Authentication/Secret%20API%20Key) on your backend server, and then let the front-end code send the generated user_hash to Miso APIs to verify the identity of the API caller. As long as the [Secret API Key](#section/Authentication/Secret%20API%20Key) is kept secret, the user_hash prevents a malicious attacker from making unauthorized API calls or impersonating any of your users. Miso APIs accept the case-incentive "hex digest" of user hash, a sample Python 3 code to generate it on your backend server is as follow: ```python import hashlib import hmac YOUR_MISO_SECRET_API_KEY = "039c501ac8dfcac91" key_bytes = YOUR_MISO_SECRET_API_KEY.encode() user_id = "USER_123" # or anonymous_id user_id_bytes = user_id.encode() user_hash = hmac.new( key_bytes, user_id_bytes, hashlib.sha256).hexdigest() # user_hash is "7eb04da5e..." ``` You can find more examples for other languages in this [Github Gist](https://gist.github.com/thewheat/7342c76ade46e7322c3e) user_cohort: title: User Cohort type: object additionalProperties: anyOf: - type: boolean - type: string description: > The user cohort you want to cold-start the recommendation with. For example, the following query will make recommendations based on the preferences of the users whose `country="United States"`, and `gender="Female"` in the User Profile dataset. ``` { "user_cohort": { "country": "United States", "gender": "Female" } } ``` rows: title: Rows type: integer description: Number of search results to return. default: 5 type: title: Type type: string description: > The type of products to return. Use this parameter to make the API return only a certain type of products (see [Product APIs](#operation/content_write_api_v1_products_post)). This is particularly useful for sites that have multiple types of products: For example, on a marketplace site, YOu may model *merchandise* and *store* as two types of *products*. You can then use type parameter to limit the recommendation or search results to return only one kind of them. For instance, the following query will return only *store* products: ``` {"type": "store"} ``` For another example, on a travel website, you might have: *hotel*, *thing to do*, and *restaurant*, three kinds of products. You can use `type` parameter to limit results to one kind of them. For instance, the following query will limit the results to only *hotels* product: ``` {"type": "hotel"} ``` dedupe_product_group_id: title: Dedupe Product Group Id type: boolean description: > Whether to dedupe product based on `product_group_id`. If `dedupe_product_group_id=true`, Miso will prevent products with the same `product_group_id` from showing multiple times in the search or recommendation results. This is particular useful when one product has multiple variants (for example, different sizes, colors, or materials), and you only want to show this product only once in the search or recommendation results. Miso will then return the variant that is most likely to be of the user's interest. default: true additional_interactions: title: Additional Interactions type: array items: anyOf: - $ref: '#/components/schemas/ProductDetailPageView' - $ref: '#/components/schemas/Search' - $ref: '#/components/schemas/AddToCart' - $ref: '#/components/schemas/RemoveFromCart' - $ref: '#/components/schemas/Checkout' - $ref: '#/components/schemas/Refund' - $ref: '#/components/schemas/Subscribe' - $ref: '#/components/schemas/Unsubscribe' - $ref: '#/components/schemas/AddToCollection' - $ref: '#/components/schemas/RemoveFromCollection' - $ref: '#/components/schemas/Read' - $ref: '#/components/schemas/Watch' - $ref: '#/components/schemas/Listen' - $ref: '#/components/schemas/Like' - $ref: '#/components/schemas/Dislike' - $ref: '#/components/schemas/Share' - $ref: '#/components/schemas/Rate' - $ref: '#/components/schemas/Bookmark' - $ref: '#/components/schemas/Complete' - $ref: '#/components/schemas/Feedback' - $ref: '#/components/schemas/Impression' - $ref: '#/components/schemas/ViewableImpression' - $ref: '#/components/schemas/Click' - $ref: '#/components/schemas/Submit' - $ref: '#/components/schemas/HomePageView' - $ref: '#/components/schemas/CategoryPageView' - $ref: '#/components/schemas/PromoPageView' - $ref: '#/components/schemas/ProductImageView' - $ref: '#/components/schemas/Custom' description: > A list of additional interaction records. You can use this fields to simulate user interactions without actually writing them to the interaction dataset. default: [] fl: title: Fl type: array items: type: string description: > List of fields to retrieve. For example, the following request retrieves only the `title` field of each product along with the `product_id`, which is always returned. ``` {"fl": ["title"]} ``` You can also match field names by using `*` as a wildcard. For example, the query below retrieves the `title` and any custom attributes under the `attributes` dictionary. ``` {"fl": ["title", "attributes.*"]} ``` The following retrieves all the available fields: ``` {"fl": ["*"]} ``` For the lowest latency, use an empty array to retrieve just the `product_id` field (which is the default). ``` {"fl": []} ``` default: [] exclude: title: Exclude type: array items: type: string description: >- An array of `product_ids` of products you want to *exclude* from search results. custom_context: title: Custom Context type: object description: > Dictionary of custom context variables for the current browsing session. You can specify context variables specific to your websites or apps in a `{"KEY":VALUE}` format, where `KEY` must be a string, and `VALUE` can be: * a `bool` * a `string` or an `array of string` * a `number` or an `array of numbers` * an `array of objects` * `null` In certain cases, Miso will take these variables into account when generating results. example: session_variable_1: - value_1 - value_2 q: title: Q minLength: 1 type: string description: > The search query the user has entered. Miso will perform full-text search and find any Products that contain every word in this query. You can also set `q="*"` to match all Products, which is commonly used along with Product filtering query `fq` to implement Category Pages. *(to make a search request, You need to specify either `q` or `advanced_q`)* advanced_q: title: Advanced Q minLength: 1 type: string description: > Like Google's Advanced Search, the `advanced_q` parameter let you define query beyond simple full-text search. For one, you can use double-quotes to indicate a phrase search. For example, the following query will only match Products that contain the *phrase* "Toy Story 4", and will not match Products like "4 Toy Story" (because the word order is not the same as the given query). ``` {"advanced_q": "full_text:\"Toy Story 4\""} ``` If you don't want phrase search, you can enclose the search terms with parenthesis to indicate regular full-text query. For example: ``` {"advanced_q": "full_text:(Toy Story 4)"} ``` You can also use AND/OR boolean operators to combine multiple full-text queries. For example, the following query will match Products with phrases "Toy Story 4" and Products with phrases "Toy Story 3", and will not match "Toy Story 2" or "Toy Story 1": ``` {"advanced_q": "full_text:\"Toy Story 4\" OR full_text:\"Toy Story 3\""} ``` Finally, you can use AND/OR boolean operators to combine full-text search with metadata filtering. For example, the following example will find Products with phrase "Toy Story" OR Products which have Tom Hanks as an actor. ``` {"advanced_q": "full_text:\"Toy Story\" OR custom_attributes.actors:\"Tom Hanks\""} ``` *(to make a search request, You need to specify either `q` or `advanced_q`)* boosting_tags: title: Boosting Tags type: array items: type: string description: > When `boosting_tags` is given, and there are pre-defined boost rules have the same tag(s), those boost rules will be matched, regardless if the criteria is met or not. Useful when want to force trigger specific boost campaign. default: [] example: - tag-1 - quetag-2 enable_boosting_campaigns: title: Enable Boosting Campaigns type: boolean description: > When set to true, enable user defined boosting campaigns. By default boosting campaigns are enabled. But you can explicitly set this to false to disable boosting campaigns. default: true include: title: Include type: array items: type: string description: >- An array of product ids you want to *include* into search results, regardless if main query matches. default: [] language: title: Language type: string description: > Two-letter (639-1) language code of the search query. This parameter is useful when you have a multilingual product catalog that contains product metadata in different languages. If given, the search results will prioritize the products that have that specific language and match the search query. Example query: ``` {"language": "fr"} ``` If not given, Miso will search against all the languages in the catalog. like: title: Like type: string description: >- The text snippet that we want to find products that are similar to it category: title: Category type: array items: type: string description: > `category` parameter limits the search results to a particular category or sub-category. This is particularly suitable for implementing Category Pages where you want to show personalized ranking of Products under a specific category. Other filters, such as `q`, `fq`, `boost_fq` will be applied on top of the category filter. A category is represented by a list of strings that correspond to its category hierarchy. For example, the following query returns Products under `Snacks` category: ``` { "q": "*", "category": ["Snacks"] } ``` And the following request returns Products under `Snacks -> Chips` subcategory: ``` { "q": "*", "category": ["Snacks", "Chips"] } ``` spellcheck: title: Spellcheck allOf: - $ref: '#/components/schemas/SpellCheckRequest' description: Spellcheck configuration default: enable_auto_spelling_correction: true start: title: Start type: integer description: > Specifies an offset from which Miso will begin returning results. The default value is `0`. Setting the start parameter to some other number, such as 3, causes Miso to skip over the preceding products and start from the product identified by the offset. default: 0 order_by: title: Order By type: array items: $ref: '#/components/schemas/OrderByDefinition' description: > A list of fields that Miso should use to sort the result, instead of Miso's default ranking order. For example, the following query returns all the Products (because `q=*`), ranked by the `_personalization_score` first, and then by the values in the `custom_attributes.promote_score` field in the Product catalog, then the distance between the product and New York city. ``` { "q": "*", "order_by": [ { "field": "_personalization_score", "tie_breaker": { "type": "relative_difference", "threshold": "0.05" }, "order": "desc" }, { "field": "custom_attributes.promote_score", "order": "desc" }, { "field": "_geo_distance", "geo": { "lat": 40.711967, "lon": -74.006076, } "order": "asc" } ] } ``` default: [] facets: title: Facets type: array items: anyOf: - $ref: '#/components/schemas/FacetDefinition' - type: string description: > Specifies a list of fields to create facet search against. You can specify `facets` in a string array. For example, the following query return the facet counts for `categories`, `tags`, and `custom_attributes.director`: ``` { "facets": [ "categories", "tags", "custom_attributes.director" ] } ``` The response will be like: ``` { "facet_counts": { "facet_fields": { "categories": [ [ "Drama", 20 ], [ "Action", 10 ], ... ], "tags": [ [ "based on novel or book", 5 ], [ "android", 4 ], ... ], "custom_attributes.director": [ [ "Ridley Scott", 26 ], [ "Andrew Abbott", 1 ], ... } } ``` You can also specify `facets` with an object array to configure each facet individually. For example, the following query will return 20 most common facet values for `tags` and `custom_attributes.director` fields, and only the directors whose names start with `Ridley` will be included in the director facet results. ``` { "facets": [ { "field": "tags", "size": 20 }, { "field": "custom_attributes.director", "size": 20, "include": "Ridley.*" } ] } ``` default: [] facet_filters: title: Facet Filters type: object additionalProperties: $ref: '#/components/schemas/Filter' description: >+ Specifies filters to the search results based on users' selections in a faceted search UI. For example, assume you have two facets in your faceted search UI: `genres` and `custom_attributes.director`. When the user selects two options in the `custom_attributes.director` facet, you should send the following query to filter the search results for those two options (i.e. `Ridley Scott` or `Denis Villeneuve`). ``` { "facets": [ { "field": "genres", "size": 5 }, { "field": "custom_attributes.director", "size": 20 } ], "facet_filters": { "custom_attributes.director": { "terms": [ "Ridley Scott", "Denis Villeneuve" ] } }, } ``` While you can use `fq` parameter to achieve the same filtering capability, you should use `facet_filters` to get the correct facet counts. In a typical faceted search UI, the facet counts reflect the search result after applying filters from **all but the current facets**. For example, in the query below, the *directors* facet counts should reflect the search result after applying the filter from the *genres* facet, i.e. `genres:Sci-Fi`. Similarly, *genres* facet counts should reflect the search result after applying the filter from the *directors* facet. `facet_filters` will make the resulting `facet_counts` follow this *all but except itself* convention, which is rather tricky to implement with `fq`. ``` "facets": [ { "field": "genres", "size": 5 }, { "field": "custom_attributes.director", "size": 20 } ], "facet_filters": { "custom_attributes.director": { "terms": [ "Ridley Scott", "Denis Villeneuve" ] } }, } ``` default: {} anchoring_settings: title: Anchoring Settings type: array items: $ref: '#/components/schemas/AnchoringEntry' description: > Promote a product to a position relative to the highest-ranked anchor product. A common use-case is promoting a private-label good by anchoring it to a name-brand counterpart. When the name-brand good (the anchor) appears in a search result, the private-label good also appears in the result (at a specified distance from the anchor product). The `anchoring_settings` object has the following fields: * **product_id** - The `product_id` of the product you want to promote. * **anchor_ids** - The array of `product_ids` that act as the anchors. * **relative_position** *(optional)* - The position that the promoted product will be returned in the search results, relative to the highest-ranked anchor product. For example, setting this parameter to `1` will place the promoted product directly after the anchor product. The default value is `-1`, which will place the promoted product directly before the anchor product. * **start_time** *(optional)* - An ISO-8601 timestamp indicating when to start the product anchoring. Ex: `2022-01-29T00:00:00Z` * **end_time** *(optional)* - An ISO-8601 timestamp indicating when to end the product anchoring. Ex: `2022-05-31T23:59:59Z` For example, if a user searches for "cookies", the API request might look like this: ``` POST v1/search/search { "q":"cookies", "anchoring_settings": [ { "product_id": "private_label_cookies", "anchor_ids": [ "name_brand_cookies_1", "name_brand_cookies_2" ], "relative_position": -1, "start_time": "2022-01-01T00:00:00Z", "end_time": "2022-12-31T23:59:59Z" } } ] } ``` default: [] exclude_fields_from_search: title: Exclude Fields From Search type: array items: title: Exclude Fields From Search type: string enum: - title - subtitle - description - short_description - paragraphs - headers - anchors description: > A list of fields you want to exclude from matching the search keywords. If not specified, all fields will be considered. Curently, only certain fields are supported for exclusion. For example, you might exclude the `description` field to improve search precision if the descriptions often contain misleading information. ```json { exclude_fields_from_search: ["description"] } ``` In this example, the search will match the query against all fields except `description`. enable_partial_match: title: Enable Partial Match type: boolean description: > Enable *partial match* to return products that match only *some* of the keywords in a user's search query. By default, Miso's Search API only returns products that contain *all* the keywords in the search query (i.e. an AND operator over keywords). This strategy usually leads to highly relevant results. However, when we don't have enough search results to return to the users, enabling partial match allows the Search API to relax the criteria and return products that match only some of the keywords. This strategy is particularly useful to prevent users from seeing an empty search result page and abandoning their search. For example, let's consider the query request below: ``` { "query": "Toy story 5", "enable_partial_match": true } ``` Since there is no movie called "Toy story 5", we have zero products to return by default. However, because we set `enable_partial_match` to `true`, we will return other products that partially match the query: ``` { "data": { "products": [ { "title": "Toy Story", "_missing_keywords": ["5"] }, { "title": "Toy story 2", "_missing_keywords": ["5"] }, ... ], "total": 4 } } ``` As you can see from the result above, when we don't have the exact product that the user is looking for, enabling partial match is a helpful strategy to let users know what alternatives are available, and prevent them from seeing an empty search result page. default: false partial_match_mode: title: Partial Match Mode enum: - blended - separated description: > Determine which partial match mode to enable: * **blended** (default): When `partial_match_mode` is `blended`, keyword-matched items and semantically-matched items will be returned in the same, rank-sorted array. * **separated**: When `partial_match_mode` is `separated`, keyword-matched items will be returned in the `products` array and partially-matched or semantically-matched items will be returned in the `partially_matched_products` array. default: blended enable_partial_match_threshold: title: Enable Partial Match Threshold type: integer description: > If `partial_match_mode=separated`, you need to provide a value for `enable_partial_match_threshold`. This parameter, which accepts an integer (*n*), creates a condition for Miso’s Search Engine to only provide partially matched results if there are *n* or fewer exact keyword matches. For example, if we set `enable_partial_match_threshold=3`, partially matched results will *only* be returned when there are three or fewer exact keyword matches. enable_semantic_search: title: Enable Semantic Search type: boolean description: > Enable *semantic search* to return products that are semantically relevant to the search query. Semantic search is a powerful tool that further improves the partial match results. It finds products that might not contain any of the search keywords, but are highly relevant to users' search intent. For example, consider the query: `rubbing alcohol`, which is a household cleaning product. When `enable_semantic_search=true`, even if we do not have any products that match `rubbing alcohol`, Miso is still able to return results like the following: ``` { "data": { "products": [], "total": 0, "partially_matched_products": [ { "title": "Clorox Disinfecting Wipes Multi-Surface Cleaning", "_missing_keywords": ["rubbing", "alcohol"] }, { "title": "Purell Advanced Hand Sanitizer Refreshing Gel", "_missing_keywords": ["rubbing", "alcohol"] }, ... ] } } ``` Note that, these two products from Clorox or Purell do not contain any of the search keywords, Miso's semantic search functionality, however, is still able to identify them as good matches based on their semantic relevancy to the query `rubbing alcohol`. Similarly, consider a single word search query: `aspirin`. Normally, a single-word query will lead to an empty search page if we don't have products containing that word. However, when `enable_semantic_search=true`, even if we do not directly have `aspirin` in the product catalog, Miso is still able to return results that are highly relevant to users' search intent, such as: ``` { "data": { "products": [], "total": 0, "partially_matched_products": [ { "title": "Advil Pain Reliever and Fever Reducer", "_missing_keywords": ["aspirin"] }, { "title": "Tylenol Extra Strength Caplets", "_missing_keywords": ["aspirin"] }, ... ] } } ``` default: false semantic_search_threshold: title: Semantic Search Threshold type: number description: > Determine the threshold for semantic search. Only the products with a semantic similarity score higher than the threshold will be returned. Setting this too low (e.g. < 0.3) will result in less relevant results being returned. default: 0.5 enable_matched_fields: title: Enable Matched Fields type: boolean description: >+ Determine whether to return `_matched_fields` in the search response (default: false). If `enable_matched_fields=true`, each returned product will have an `_matched_fields` array that shows which parts of the product catalog match the search query. For example, the following request will return `_matched_fields`: ``` { "q": "toy story", "enable_matched_fields": true } ``` The response will be like: ``` { "data": { "products": [ { "title": "Toy Story", "_matched_fields": ["title", "metadata"] }, ... ] } } ``` Currently, `_matched_fields` only contain three kinds of fields: * `title` * `description` * `metadata`, including all the fields beyond title or description in the product catalog. default: false query_product_existence: title: Query Product Existence allOf: - $ref: '#/components/schemas/CheckProductExistence' description: >- Additionally check if certain products will be in the search result at all (regardless of `start` and `rows` parameters) personalization_weight: title: Personalization Weight maximum: 5 minimum: 0 type: integer description: Determines how much personalization will affect the search ranking. default: 5 fq: title: Fq type: string description: > Defines a query in Solr syntax that can be used to restrict the superset of products to return, without influencing the overall ranking. `fq` can enable users to drill down to products with specific features based on different product attributes For example, the query below limits the search results to only show products whose size is either `M` or `S` and brand is `Nike`: ``` {"fq": "size:(\"M\" OR \"S\") AND brand:\"Nike\""} ``` You can use `fq` to apply filters against your custom attributes as well. For example, the query below limits the search results to only products whose `designer` attribute is `Calvin Klein` ``` {"fq": "attributes.designer:\"Calvin Klein\""} ``` `fq` can also limit search results by numerical range. For example, the following query limits the results to products that have `rating >= 4`. ``` {"fq": "rating:[4 TO *]"} ``` boost_fq: title: Boost Fq type: string description: > Defines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking, or to specific *boost positions* (See `boost_positions` parameter below.) For example, the query below will promote all the relevant products whose brand is `Nike` to the top of recommendation list: ``` { "boost_fq": "brand:\"Nike\"" } ``` For a slightly more complex example, the query below will promote the Nike products which have also been tagged as `ON SALE` to the top of the ranking: ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"" } ``` It is worth mentioning that, Miso will only boost products that are relevant and have high likelihood to convert, and will not boost a low performance product only because it matches the boosting query. Depending on your boosting rules, in certain cases, you would like to prevent recommendation results from being too monotone due to boosting. With Miso, you have two tools to do so. First, you can specify `boost_positions` to place promoted products at specific positions in the ranking. For example, the query below will place boosted products only at the first and fourth places in the ranking (positions are 0-based), and place the remaining products in their original ranking, skipping these two positions. ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "boost_positions": [0, 3] } ``` The second tool is `diversification`. `diversification` parameter, on a best-effort basis, will try to maintain a minimum distance between products that have the same attributes. For example, the following query will place products made by the same brand apart from each other. ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "diversification": { "brand": {"minimum_distance": 1} } } ``` boost_positions: title: Boost Positions type: array items: type: integer description: > Defines a list of 0-based positions you want to place the boosted products at. For example, the query below will promote products whose brand is `Nike` as the top and second recommendations: ``` { "boost_fq": "brand:\"Nike\"", "boost_positions": [0, 1] } ``` If `boost_positions` is not specified (which is the default behavior), all the boosted products will be ranked higher than the rest of the products. boost_rule_name: title: Boost Rule Name type: string description: >- Name of the boosting rule. Use this to identify a boosting rule in _boosted_rules in the response boost_rules: title: Boost Rules type: array items: $ref: '#/components/schemas/BoostingFilterBase' description: > Define a list of boosting rules that will be applied to the search or recommendation results simultaneously. `boost_rules` parameter is particularly useful when you want to boost more than one sets of products, and promote each of them to different positions. For example, the query below will promote products whose brand is `Nike` to the top and second results, and products whose brand is `Adidas` to the third and fourth results: ``` { "boost_rules": [ { "boost_fq": "brand:\"Nike\"", "boost_positions": [0, 1] }, { "boost_fq": "brand:\"Adidas\"", "boost_positions": [2, 3] } ] } ``` default: [] geo: title: Geo allOf: - $ref: '#/components/schemas/GeoQuery' description: > When set, filter result to include only products within certain geographic range from given point will be returned, or to boost product within the same range. Product should have a field that holds the location of the product, `location` is used by default, but other field can also be used. Distance can be in miles or kilometers. If `distance_unit` is not set, `mile` will be used. For example, to limit results to products within 100 miles of New York city: ``` { "geo": { "filter": [{ "lat": 40.73061, "lon": -73.93524, "distance": 100 }] } } ``` To boost products within 2 kilometers around Alcatraz Island according to `loc` field: ``` { "geo": { "boost": [{ "field": "loc", "lat": 37.82667, "lon": -122.42278, "distance": 2, "distance_unit": "km" }] } } ``` diversification: title: Diversification type: object additionalProperties: $ref: '#/components/schemas/DiversifyField' description: > Defines diversification rules to prevent products with the same attributes (e.g. sneakers made by the same brand or books from the same authors) from showing up too close to each other in the results. For instance, customers who have purchased many of sneakers from Nike may happen to have recommendations or search results where all top-5 entries are sneakers made by Nike. Purely considering accuracy, these recommendations appear excellent since the user clearly appreciates Nike sneakers. However, such results might be considered too "plain" by the user, owing to its lack of diversity. `diversification` parameter allows you to avoid this problem by enforcing a desired *minimum distance* between products. For example, consider a list of four products whose `brand` are *Nike, Nike, Adidas,* and *PUMA* respectively. The query below will make sure there are at least one different product between two Nike products, e.g. the diversified ranking may become *Nike, Adidas, Nike,* and *PUMA* : ``` { "diversification": {"brand": {"minimum_distance": 1}} } ``` You can also increase the minimum_distance to place products further apart. For example, the following query will make sure, for the two Nike products, there are at least *two* other products between them. As a result, the diversified ranking may become *Nike, Adidas, PUMA*, and *Nike*.: ``` { "diversification": {"brand": {"minimum_distance": 2}} } ``` The diversification algorithm reranks the products on a best-effort basis. For example, for the product list described earlier, it is not possible to place two Nike product three places apart from each other. Therefore, the diversified ranking will still remain *Nike, Adidas, PUMA,* and Nike* even if we set `minimum_distance=3`. additionalProperties: false SearchResponse: title: SearchResponse required: - data type: object properties: message: title: Message type: string default: success data: $ref: '#/components/schemas/SearchResponseBody' HTTPValidationError: title: HTTPValidationError type: object properties: detail: title: Detail type: array items: $ref: '#/components/schemas/ValidationError' ProductDetailPageView: title: product_detail_page_view required: - type type: object properties: type: title: Type enum: - product_detail_page_view type: string description: >- Used when a user views the detail page of a product. Viewing a product detail page usually indicates a user is interested in the product to certain degree, especially, when the `duration` of the page view is long. When `duration` of the page view is very short (< 5 seconds), `product_detail_page_view` may indicate neural or negative interest in the product. duration: title: Duration type: number description: > How long (in seconds) the user stayed on this page, or consumed (listened, read, or watched) a product. This field is optional, but it's very important in scenarios where consumption duration matters, including `product_detail_page_view`, `category_page_view`, `watch`, `listen`, and `read`. For example, if a user only views or consumes a product for less than 5 seconds, that user is probably not interested in the product. On the other hand, if a user stays on a page for a while, it usually means they are seriously engaging with or considering the product. When `duration` is absent, we will use the timestamp of the next interaction to infer a rough duration value. Example: ``` {"duration": 61.5} ``` example: 61.5 product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Search: title: search required: - type type: object properties: type: title: Type enum: - search type: string description: > Used to record a search event with the keywords and filters the user used. What a user searches for is a very powerful signal about their interests and what they will eventually buy or consume, so it is important to capture this information with high fidelity. user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` search: title: Search allOf: - $ref: '#/components/schemas/SearchInformation' description: > The search keywords and filters the user uses. This is only required by `search` interaction. additionalProperties: false AddToCart: title: add_to_cart required: - type type: object properties: type: title: Type enum: - add_to_cart type: string description: > Used when a user adds a product into their shopping cart. This is a strong positive signal of the user's interest in the product, and may eventually lead to a purchase. quantities: title: Quantities anyOf: - type: array items: type: number - type: number description: > The quantities of products the user adds to their cart or checks out with. This field should be a list of positive values. Specifically, if `product_ids` is a list of N products, the `quantities` needs to be a list with N numbers as well. If `quantities` are not specified, we will assume the quantity to be 1 for every product. Example: ``` {"quantities": [1, 2]} ``` example: - 1 - 2 product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false RemoveFromCart: title: remove_from_cart required: - type type: object properties: type: title: Type enum: - remove_from_cart type: string description: | Used when a user removes a product from their shopping cart. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Checkout: title: checkout required: - type type: object properties: type: title: Type enum: - checkout type: string description: > Used when a user enters checks out with a set of products. For an eCommerce site, this is the strongest signal of the user's interest and has a high probability of leading to an eventual purchase. revenue: title: Revenue type: number description: > Total revenue associated with the checkout. The revenue should include generally shipping, tax, etc. that you want to include as part of your revenue calculations. example: 23.32 quantities: title: Quantities anyOf: - type: array items: type: number - type: number description: > The quantities of products the user adds to their cart or checks out with. This field should be a list of positive values. Specifically, if `product_ids` is a list of N products, the `quantities` needs to be a list with N numbers as well. If `quantities` are not specified, we will assume the quantity to be 1 for every product. Example: ``` {"quantities": [1, 2]} ``` example: - 1 - 2 product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Refund: title: refund required: - type type: object properties: type: title: Type enum: - refund type: string description: | Used when a user requests a refund of products they bought. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Subscribe: title: subscribe required: - type type: object properties: type: title: Type enum: - subscribe type: string description: > Used when a user subscribes a product, for example to receive alerts when the product comes back in stock or if the price drops. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Unsubscribe: title: unsubscribe required: - type type: object properties: type: title: Type enum: - unsubscribe type: string description: > Used when a user unsubscribes a product, for example to stop receiving alerts when the product comes back in stock or if the price drops. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false AddToCollection: title: add_to_collection required: - type type: object properties: type: title: Type enum: - add_to_collection type: string description: > Used when a user adds a product to their personal collection. This is a strong signal of their interest in the product. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false RemoveFromCollection: title: remove_from_collection required: - type type: object properties: type: title: Type enum: - remove_from_collection type: string description: | Used when a user removes a product from their personal collection. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Read: title: read required: - type type: object properties: type: title: Type enum: - read type: string description: > Used to record when and for how long a user reads a piece of written content. duration: title: Duration type: number description: > How long (in seconds) the user stayed on this page, or consumed (listened, read, or watched) a product. This field is optional, but it's very important in scenarios where consumption duration matters, including `product_detail_page_view`, `category_page_view`, `watch`, `listen`, and `read`. For example, if a user only views or consumes a product for less than 5 seconds, that user is probably not interested in the product. On the other hand, if a user stays on a page for a while, it usually means they are seriously engaging with or considering the product. When `duration` is absent, we will use the timestamp of the next interaction to infer a rough duration value. Example: ``` {"duration": 61.5} ``` example: 61.5 product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Watch: title: watch required: - type type: object properties: type: title: Type enum: - watch type: string description: > Used to record when and for how long a user watches content that is of a video format. duration: title: Duration type: number description: > How long (in seconds) the user stayed on this page, or consumed (listened, read, or watched) a product. This field is optional, but it's very important in scenarios where consumption duration matters, including `product_detail_page_view`, `category_page_view`, `watch`, `listen`, and `read`. For example, if a user only views or consumes a product for less than 5 seconds, that user is probably not interested in the product. On the other hand, if a user stays on a page for a while, it usually means they are seriously engaging with or considering the product. When `duration` is absent, we will use the timestamp of the next interaction to infer a rough duration value. Example: ``` {"duration": 61.5} ``` example: 61.5 product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Listen: title: listen required: - type type: object properties: type: title: Type enum: - listen type: string description: > Used to record when and for how long a user listens to content that is of an audio format. duration: title: Duration type: number description: > How long (in seconds) the user stayed on this page, or consumed (listened, read, or watched) a product. This field is optional, but it's very important in scenarios where consumption duration matters, including `product_detail_page_view`, `category_page_view`, `watch`, `listen`, and `read`. For example, if a user only views or consumes a product for less than 5 seconds, that user is probably not interested in the product. On the other hand, if a user stays on a page for a while, it usually means they are seriously engaging with or considering the product. When `duration` is absent, we will use the timestamp of the next interaction to infer a rough duration value. Example: ``` {"duration": 61.5} ``` example: 61.5 product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Like: title: like required: - type type: object properties: type: title: Type enum: - like type: string description: | Used to record when a user indicates a `like` for a product. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Dislike: title: dislike required: - type type: object properties: type: title: Type enum: - dislike type: string description: > Used when a user indicates a `dislike` for a product or indicates they would like to not be recommended content or products like this in the future. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Share: title: share required: - type type: object properties: type: title: Type enum: - share type: string description: | Used when a user shares a product or piece of content. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Rate: title: rate required: - type type: object properties: type: title: Type enum: - rate type: string description: | Used when a user gives a rating to a product or piece of content. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` rating: title: Rating type: number description: > The rating the user gave in the range of [0, 5]. This field is only required by the `rate` interaction. As a convention in the RecSys community, a rating >= 3.5 is considered positive, a rating <= 2 is negative, and otherwise a rating is neutral. If you use any other rating scale, please normalize it to a [0, 5] scale. example: 5 additionalProperties: false Bookmark: title: bookmark required: - type type: object properties: type: title: Type enum: - bookmark type: string description: | Used when a user bookmarks a product. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Complete: title: complete required: - type type: object properties: type: title: Type enum: - complete type: string description: > Used when a user "complete" a product (e.g. complete a course or a video). product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Feedback: title: feedback required: - type type: object properties: type: title: Type enum: - feedback type: string description: | Used when a user sends feedback on provided results. question_id: title: Question Id maxLength: 512 type: string description: > A unique identifier representing the specific question for which feedback is being provided. example: question_123 result_type: title: Result Type type: string description: > Indicates the type of result the provided feedback is associated with, e.g., an answer or a suggestion. example: answer value: title: Value type: string description: > Specifies the user's perspective on the provided result, with possible values being helpful, not helpful, or unselected if the user has not provided any feedback. example: helpful user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Impression: title: impression required: - type type: object properties: type: title: Type enum: - impression type: string description: >- Used to record when a user saw or was presented with a product or content asset. An impression does not mean a user is interested: for example, if there is an impression for a certain product, but no further interaction occurs with that product, we assume the user is probably not interested in it. For an impression that was generated by Miso's search results or recommendations results, it is important to include the `miso_id` associated with the results so that we know the impression is from Miso product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false ViewableImpression: title: viewable_impression required: - type type: object properties: type: title: Type enum: - viewable_impression type: string description: > When a product or content asset is presented to the user, it is not guarantee that the user will see it. An viewable impression is an impression that is "viewable" by the user. Usually, content asset is considered viewable if more than 50% of its area is visible on screen. You can also use different definition for what is considered viewable. Miso will automatically find the best recommendation as long as the difference between viewable and non-viewable impression is consistant. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Click: title: click required: - type type: object properties: type: title: Type enum: - click type: string description: > Used when user clicked on something, and does not belong to any other interaction type. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Submit: title: submit required: - type type: object properties: type: title: Type enum: - submit type: string description: | Used when a user submits a form or a survey. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false HomePageView: title: home_page_view required: - type type: object properties: type: title: Type enum: - home_page_view type: string description: | Used when a user views your home page. duration: title: Duration type: number description: > How long (in seconds) the user stayed on this page, or consumed (listened, read, or watched) a product. This field is optional, but it's very important in scenarios where consumption duration matters, including `product_detail_page_view`, `category_page_view`, `watch`, `listen`, and `read`. For example, if a user only views or consumes a product for less than 5 seconds, that user is probably not interested in the product. On the other hand, if a user stays on a page for a while, it usually means they are seriously engaging with or considering the product. When `duration` is absent, we will use the timestamp of the next interaction to infer a rough duration value. Example: ``` {"duration": 61.5} ``` example: 61.5 user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false CategoryPageView: title: category_page_view required: - type type: object properties: type: title: Type enum: - category_page_view type: string description: > Used when a user views a category page for a specific “family” or “group” or products or content. This is a strong indicator of what types category of products or content the user is interested in. duration: title: Duration type: number description: > How long (in seconds) the user stayed on this page, or consumed (listened, read, or watched) a product. This field is optional, but it's very important in scenarios where consumption duration matters, including `product_detail_page_view`, `category_page_view`, `watch`, `listen`, and `read`. For example, if a user only views or consumes a product for less than 5 seconds, that user is probably not interested in the product. On the other hand, if a user stays on a page for a while, it usually means they are seriously engaging with or considering the product. When `duration` is absent, we will use the timestamp of the next interaction to infer a rough duration value. Example: ``` {"duration": 61.5} ``` example: 61.5 user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` category: title: Category type: array items: type: string description: > Categories usually fall in a hierarchy, such as *Home & Garden > Kitchen & Dining > Kitchen Tools & Utensils > Sushi Mats* Use this field to specify the full hierarchical list describing the category the user is viewing. The levels should be listed from broad to narrow: `["TOP_LEVEL_CATEGORY", "SUBCATEGORY_1", "SUBCATEGORY_2", ...]`. This field is only used by the category_page_view interaction type, but this data is very useful for determining the user’s interests. Example: ``` [ "Home & Garden", // TOP_LEVEL_CATEGORY "Kitchen & Dining", // SUBCATEGORY_1 "Kitchen Tools & Utensils", // SUBCATEGORY_2 "Sushi Mats" // SUBCATEGORY_3 ] ``` additionalProperties: false PromoPageView: title: promo_page_view required: - type type: object properties: type: title: Type enum: - promo_page_view type: string description: > Used when a user views a specific promotional or curated marketing page about certain products or content. duration: title: Duration type: number description: > How long (in seconds) the user stayed on this page, or consumed (listened, read, or watched) a product. This field is optional, but it's very important in scenarios where consumption duration matters, including `product_detail_page_view`, `category_page_view`, `watch`, `listen`, and `read`. For example, if a user only views or consumes a product for less than 5 seconds, that user is probably not interested in the product. On the other hand, if a user stays on a page for a while, it usually means they are seriously engaging with or considering the product. When `duration` is absent, we will use the timestamp of the next interaction to infer a rough duration value. Example: ``` {"duration": 61.5} ``` example: 61.5 product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false ProductImageView: title: product_image_view required: - type type: object properties: type: title: Type enum: - product_image_view type: string description: > Used when a user views the image of a product (e.g. to enlarge a product photo). product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` additionalProperties: false Custom: title: custom required: - type - custom_action_name type: object properties: type: title: Type enum: - custom type: string description: > Used when you want to record any other kinds of interactions between users and products. product_ids: title: Product Ids type: array items: type: string maxLength: 512 description: > Products or content the user is interacting with. This field is required by almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso. Therefore, it is important to keep this consistent between the two datasets. Example: ``` {"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]} ``` default: [] example: - 123ABC-BLACK product_group_ids: title: Product Group Ids type: array items: type: string maxLength: 512 description: > The product groups the user is interacting with. You only need this field if you model product variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a user is interacting with a *product group* rather than a specific product variant, for example, when the user is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or color (i.e. a product variant) yet. In such situations, the `product_id` is not applicable because we only know the user is interested in this T-shirt (a product group), but don't know which particular product variant the user is interested in. Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`. In the situations where specific `product_ids` are available, for example, when user selected a particular size of the T-Shirt, use `product_ids` instead. Example: ``` {"product_group_ids": ["123ABC"]} ``` example: - 123ABC user_id: title: User Id maxLength: 512 type: string description: >- Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have not signed in, see `anonymous_id`. example: user_1234 anonymous_id: title: Anonymous Id maxLength: 1024 type: string description: >- A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id` is not given, we will default it to `SHA1(:::)`. When a visitor signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it. example: 86D51273AD8BF84217E1567B6CBE7152D7034404 timestamp: title: Timestamp type: string description: > The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we will default to the server's time. If you're importing data from the past, make sure you provide a timestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution. Example: ``` {"timestamp": "2018-11-07T00:25:00.073876Z"} ``` format: date-time miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid example: 123e4567-e89b-12d3-a456-426614174000 context: title: Context allOf: - $ref: '#/components/schemas/WebBasedContext' description: > Dictionary of extra information that provides useful context about an interaction. We use context information to make recommendations tailored not only for each user, but also for their current browsing context. For example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile phone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very different interests than a user who visits your site directly. Context information is also useful for personalization for entirely new visitors, as we can immediately personalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through). Example: ``` {"context": { "campaign": { "name": "spring_sale", "source": "Google", "medium": "cpc", "term": "running+shoes", "content": "textlink" }, "truncated_ip": "1.1.1.0", "locale": "en-US", "region": "US East", "page": { "url": "https://example.com/miso-tshirt-123ABC", "referrer": "https://example.com/", "title": "My Product Page" }, "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)" }, "custom_context": { "other_context_var_1": "value_1", "other_context_var_2": "value_2" } } ``` custom_action_name: title: Custom Action Name type: string description: | The name of the custom interaction that you have defined. additionalProperties: false SpellCheckRequest: title: SpellCheckRequest type: object properties: enable_auto_spelling_correction: title: Enable Auto Spelling Correction type: boolean description: > This parameter controls whether to automatically correct a misspell search query. If set to `true`, when Miso detects spelling errors, the search results will be based on the **corrected** spelling suggested by Miso. You call tell if Miso made any correction to the search query by checking the `spellcheck.auto_spelling_correction` field in the API response. When this field is `true`, the search results are based on the suggested spelling as opposed to the users' original query. You can opt-out the spelling correction by setting this parameter to `false`. In such cases, Miso will still detect spelling errors, but the search results will be always based on users' original spelling. default: true OrderByDefinition: title: OrderByDefinition required: - field type: object properties: field: title: Field type: string description: >+ Name of the field to order by. You can sort by any numeric and boolean fields in your Product catalog, or use one of any special fields: * **_personalization_score**: the score that rates the degree of affinity between a pair of user and product from Miso's personalization algorithm. * **_search_score**: the score that rates the degree of search keyword matches to a product's catalog. * **_boosting_score**: the score that rates the degree a Product is boosted by your boosting query. tie_breaker: title: Tie Breaker allOf: - $ref: '#/components/schemas/TieBreakDefinition' default: type: relative_difference threshold: 0 default_value: title: Default Value type: number description: The default value to use when the scores do not exist for a Product default: 0 geo: title: Geo allOf: - $ref: '#/components/schemas/BaseGeo' description: >- The geo point to compute the `_geo_distance` variable against. This is only required if `_geo_distance` is present in the formula. order: title: Order enum: - desc - asc default: desc FacetDefinition: title: FacetDefinition required: - field type: object properties: field: title: Field type: string description: >+ The field name to create a facet against. For example, the following query will create a facet against the `custom_attributes.director` field, and return the ten most common facet values of this field (for Products that match the search query): ``` { "field": "custom_attributes.director", "size": 10 } ``` alias: title: Alias type: string description: > The `alias` parameter gives a unique name to a facet, especially useful when you have multiple facets on the same field. By default, facet results use the `field` as the key. But with multiple facets on one field, this can get confusing. `alias` solves this: ```json { "field": "custom_attributes.director", "alias": "director_facet", "size": 10 } ``` In the response, you'll see results under the key `director_facet` instead of the field name. size: title: Size type: integer description: > Number of facet values to return. The facet values are sort descendingly by the number of Products that have these values (and match the search query). default: 10 include: title: Include type: string description: > Filter facet values based on a regular expression. For example, the following query will return only the facet values that start with `Steven` (case-sensitive): ``` { "field": "custom_attributes.director", "size": 10, "include": "Steven.*" } ``` You can escape a special character with a preceding backslash `\` or surround it with double quotes. For example, the following query will only return the facet values starting with `St.`: ``` { "field": "custom_attributes.place_name", "size": 10, "include": "\"St.\".*" } ``` Note that, the `include` parameter will only affect the facet values, and will not affect the search result itself. exclude: title: Exclude type: string description: > The `exclude` parameter filters out facet values using a regular expression. For example: ```json { "field": "custom_attributes.director", "size": 10, "exclude": "Steven.*" } ``` This will omit all facet values starting with "Steven" (case-sensitive). To exclude values with special characters, use a backslash `\` or double quotes: ```json { "field": "custom_attributes.place_name", "size": 10, "exclude": "\"St.\".*" } ``` This excludes facet values starting with "St.". Remember, `exclude` only affects facet values, not the search results themselves. ranges: title: Ranges type: array items: $ref: '#/components/schemas/RangeRequireKey' description: > Facet ranges for numeric fields or date-like string fields. For example, the following query groups the products into fours buckets against on their `original_price` ranges, each of which has a user-friendly "key": ``` { "field": "original_price", "ranges": [ {"to": 10, "key": "Less than 10 dollars"}, {"from": 10, "to": 100, "key": "10 to 100 dollars"}, {"from": 100, "to": 1000, "key": "100 to 1,000 dollars"}, {"from": 1000, "key": "More than 1,000 dollars"} ] } ``` For each range object, you need to at least specify one of the `to` or `from` values (or both). `from` is always **inclusive**, and `to` is always **exclusive**. In the response, Miso refers to each bucket by their `key`. For example, the above request will have the following response: ``` { "facet_counts": { "facet_fields": { "original_price": [ [ "Less than 10 dollars", 1987 ], [ "10 to 100 dollars", 109 ], [ "100 to 1,000 dollars", 123 ], [ "More than 1,000 dollars", 5 ] ] } } } ``` queries: title: Queries type: array items: $ref: '#/components/schemas/QueryFilterRequireKey' description: > Facet queries that support facet counts for any arbitrary Lucene queries, each of which is labeled by a user-friendly "key": ``` { "field": "my_custom_facet", "queries": [ { "query": "price: [* TO 10] AND size:"Small"", "key": "Less than 10 dollars / Small size" }, { "query": "price: [10 TO 100] AND size:"Medium"", "key": "10 to 100 dollars / Medium size" }, { "query": "price: [100 TO *] AND size:"Large"", "key": "More than 100 dollars / Large size" } ] } ``` In the response, Miso refers to the query result by their `key`. For example, the above request will have the following response: ``` { "facet_counts": { "facet_fields": { "my_custom_facet": [ [ "Less than 10 dollars / Small size", 1987 ], [ "10 to 100 dollars / Medium size", 109 ], [ "More than 100 dollars / Large size", 123 ] ] } } } ``` Filter: title: Filter type: object properties: terms: title: Terms type: array items: type: string ranges: title: Ranges type: array items: $ref: '#/components/schemas/Range' queries: title: Queries type: array items: $ref: '#/components/schemas/QueryFilter' AnchoringEntry: title: AnchoringEntry required: - product_id - anchor_ids type: object properties: product_id: title: Product Id type: string description: Product to boost anchor_ids: title: Anchor Ids minLength: 1 type: array items: type: string minLength: 1 description: A list of anchor products relative_position: title: Relative Position type: integer description: Relative position to the top anchor product default: -1 start_time: title: Start Time type: string description: When does the anchoring start. Leave it unset to start immediately format: date-time end_time: title: End Time type: string description: When will the anchoring end. Leave it unset to not have an end time format: date-time CheckProductExistence: title: CheckProductExistence required: - product_ids type: object properties: product_ids: title: Product Ids minLength: 1 type: array items: type: string minLength: 1 description: >- A list of product ids to be checked if they will be returned in the search results BoostingFilterBase: title: BoostingFilterBase type: object properties: boost_fq: title: Boost Fq type: string description: > Defines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking, or to specific *boost positions* (See `boost_positions` parameter below.) For example, the query below will promote all the relevant products whose brand is `Nike` to the top of recommendation list: ``` { "boost_fq": "brand:\"Nike\"" } ``` For a slightly more complex example, the query below will promote the Nike products which have also been tagged as `ON SALE` to the top of the ranking: ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"" } ``` It is worth mentioning that, Miso will only boost products that are relevant and have high likelihood to convert, and will not boost a low performance product only because it matches the boosting query. Depending on your boosting rules, in certain cases, you would like to prevent recommendation results from being too monotone due to boosting. With Miso, you have two tools to do so. First, you can specify `boost_positions` to place promoted products at specific positions in the ranking. For example, the query below will place boosted products only at the first and fourth places in the ranking (positions are 0-based), and place the remaining products in their original ranking, skipping these two positions. ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "boost_positions": [0, 3] } ``` The second tool is `diversification`. `diversification` parameter, on a best-effort basis, will try to maintain a minimum distance between products that have the same attributes. For example, the following query will place products made by the same brand apart from each other. ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "diversification": { "brand": {"minimum_distance": 1} } } ``` boost_positions: title: Boost Positions type: array items: type: integer description: > Defines a list of 0-based positions you want to place the boosted products at. For example, the query below will promote products whose brand is `Nike` as the top and second recommendations: ``` { "boost_fq": "brand:\"Nike\"", "boost_positions": [0, 1] } ``` If `boost_positions` is not specified (which is the default behavior), all the boosted products will be ranked higher than the rest of the products. boost_rule_name: title: Boost Rule Name type: string description: >- Name of the boosting rule. Use this to identify a boosting rule in _boosted_rules in the response GeoQuery: title: GeoQuery type: object properties: filter: title: Filter type: array items: $ref: '#/components/schemas/GeoDistanceQuery' description: >- When set, filter result to include only products within certain geographic range from given point. default: [] boost: title: Boost type: array items: $ref: '#/components/schemas/GeoDistanceQueryBoost' description: >- When set, boost products within certain geographic range from given point. default: [] DiversifyField: title: DiversifyField type: object properties: minimum_distance: title: Minimum Distance type: integer description: Minimum distance between two products that have the same value default: 1 always_together: title: Always Together type: boolean description: >- If always_together=true, all the products that have the same value for this field, will be put side-by-side. default: false SearchResponseBody: title: SearchResponseBody required: - products - total - start - spellcheck type: object properties: took: title: Took type: integer description: Number of milliseconds Miso took to retrieve the results. default: 0 miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid default: 00000000-0000-0000-0000-000000000000 example: 123e4567-e89b-12d3-a456-426614174000 products: title: Products type: array items: $ref: '#/components/schemas/PartialMatchedRecord' description: The search results. total: title: Total type: integer description: Total number of search hits. example: 1000 start: title: Start type: integer description: Starting offset of the search results. example: 0 spellcheck: title: Spellcheck allOf: - $ref: '#/components/schemas/SpellCheckResponse' description: >- Spellcheck results. You can use the information in this object to prompt users with the correct spelling. product_existence: title: Product Existence type: object additionalProperties: type: boolean description: Product existence query result partially_matched_products: title: Partially Matched Products type: array items: $ref: '#/components/schemas/PartialMatchedRecord' description: The search results that only partially match the search query. facet_counts: title: Facet Counts allOf: - $ref: '#/components/schemas/FacetCounts' description: Facet counts default: {} custom_assets: title: Custom Assets type: array items: type: object description: Custom JSON assets uploaded in Dojo. default: [] boosting_rules: title: Boosting Rules type: array items: anyOf: - $ref: '#/components/schemas/BoostingFilterBase' - $ref: '#/components/schemas/GeoDistanceQueryBoost' description: Boosting rules that are applied to the search results. default: [] filtering_rule: title: Filtering Rule type: string description: Filter query that is applied to the search results. ValidationError: title: ValidationError required: - loc - msg - type type: object properties: loc: title: Location type: array items: type: string msg: title: Message type: string type: title: Error Type type: string WebBasedContext: title: WebBasedContext type: object properties: campaign: title: Campaign allOf: - $ref: '#/components/schemas/Campaign' description: > The campaign that resulted in the interaction. Campaign dictionary contains standard UTM parameters: `name`, `source`, `medium`, `term`, `content`. We use campaign information to infer users' interests and fine-tune the personalization and search results based on the current user's campaign information. truncated_ip: title: Truncated Ip type: string description: > User's truncated IP address. We use IP address to determine the country of the users. format: ipv4 example: 1.1.1.0 locale: title: Locale type: string description: Locale string of the current session, for example en-US. example: en-US region: title: Region type: string description: > The region/location of the site the user is visiting. This is for sites that serve different regions or markets. You can define your own region keywords, for example, `US East`, `Europe`, `LATM`, etc. example: US East page: title: Page allOf: - $ref: '#/components/schemas/Page' description: >- The current page in the browser. Page dictionary containing referrer, title and url. we will use page view as a pseudo interaction to infer users' interest. user_agent: title: User Agent type: string description: > User agent of the device making the request. We use this to determine if a user is browsing the site on mobile or desktop, and tailor the recommendations and search results accordingly. Example: ``` {"user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"} ``` example: >- Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 custom_context: title: Custom Context type: object additionalProperties: anyOf: - type: boolean - type: integer - type: number - type: string - type: array items: type: number - type: array items: type: string - type: array items: type: object additionalProperties: anyOf: - type: string - type: number - type: integer - type: boolean description: > Dictionary of custom context variables for the current browsing session. You can specify context variables specific to your websites or apps in a `{"KEY":VALUE}` format, where `KEY` must be a string, and `VALUE` can be: * a `bool` * a `string` or an `array of string` * a `number` or an `array of numbers` * an `array of objects` * `null` Miso will take these variables into account when generating recommendations. example: session_variable_1: - value_1 - value_2 SearchInformation: title: SearchInformation type: object properties: keywords: title: Keywords type: string description: > The search keywords user use. Search keywords are strong signals to users' interests. default: '' filters: title: Filters type: object additionalProperties: type: array items: type: string description: > Dictionary of filters users apply to the search results in the following format: `{"FIELD": ["SELECTION_1", "SELECTION_2"]}`. TieBreakDefinition: title: TieBreakDefinition type: object properties: type: title: Type enum: - relative_difference default: relative_difference threshold: title: Threshold type: number default: 0 BaseGeo: title: BaseGeo required: - lat - lon type: object properties: lat: title: Lat maximum: 90 minimum: -90 type: number description: Latitude of the center point, should between 90 and -90 lon: title: Lon maximum: 180 minimum: -180 type: number description: Longitude of the center point, should between 180 and -180 RangeRequireKey: title: RangeRequireKey required: - key type: object properties: to: title: To anyOf: - type: string - type: number description: End of the range (exclusive). from: title: From anyOf: - type: string - type: number description: Start of the range (inclusive). key: title: Key type: string description: User friendly label of the range QueryFilterRequireKey: title: QueryFilterRequireKey required: - query - key type: object properties: query: title: Query type: string description: Query in Lucene syntax key: title: Key type: string description: User friendly label of the query result Range: title: Range type: object properties: to: title: To anyOf: - type: string - type: number description: End of the range (exclusive). from: title: From anyOf: - type: string - type: number description: Start of the range (inclusive). key: title: Key type: string description: User friendly label of the range QueryFilter: title: QueryFilter required: - query type: object properties: query: title: Query type: string description: Query in Lucene syntax key: title: Key type: string description: User friendly label of the query result GeoDistanceQuery: title: GeoDistanceQuery required: - lat - lon - distance type: object properties: lat: title: Lat maximum: 90 minimum: -90 type: number description: Latitude of the center point, should between 90 and -90 lon: title: Lon maximum: 180 minimum: -180 type: number description: Longitude of the center point, should between 180 and -180 field: title: Field type: string description: >- Name of the field in product data that holds geographic coordinate. Defaults to `location` default: location distance: title: Distance type: number description: >- Distance to center point, in kilometer or mile (according to `distance_unit`) distance_unit: title: Distance Unit enum: - km - mile description: Unit of distance(`km` or `mile`). Defaults to `mile` default: mile GeoDistanceQueryBoost: title: GeoDistanceQueryBoost required: - lat - lon - distance type: object properties: lat: title: Lat maximum: 90 minimum: -90 type: number description: Latitude of the center point, should between 90 and -90 lon: title: Lon maximum: 180 minimum: -180 type: number description: Longitude of the center point, should between 180 and -180 field: title: Field type: string description: >- Name of the field in product data that holds geographic coordinate. Defaults to `location` default: location distance: title: Distance type: number description: >- Distance to center point, in kilometer or mile (according to `distance_unit`) distance_unit: title: Distance Unit enum: - km - mile description: Unit of distance(`km` or `mile`). Defaults to `mile` default: mile boost_positions: title: Boost Positions type: array items: type: integer description: |2- Defines a list of 0-based positions you want to place the boosted products at. If `boost_positions` is not specified (which is the default behavior), all the boosted products will be ranked higher than the rest of the products. PartialMatchedRecord: title: PartialMatchedRecord required: - product_id type: object properties: product_id: title: Product Id maxLength: 512 type: string description: |2- The unique identifier for the product. example: 123ABC-S-Black SpellCheckResponse: title: SpellCheckResponse required: - spelling_errors - auto_spelling_correction - original_query - original_query_with_markups - corrected_query - corrected_query_with_markups type: object properties: spelling_errors: title: Spelling Errors type: boolean description: Whether Miso detects any spelling errors. auto_spelling_correction: title: Auto Spelling Correction type: boolean description: >- Whether Miso has automatically corrected the misspelled search query. When this field is `true`, the search result is based on the corrected spelling in the `corrected_query` field instead of users' original search query. original_query: title: Original Query type: string description: Original query string example: what is pythn original_query_with_markups: title: Original Query With Markups type: string description: >- Original query with the spelling errors (if any) surrounded by the <mark> tags example: what is <mark>pythn</mark> corrected_query: title: Corrected Query type: string description: >- The corrected spelling suggested by Miso. If no spelling error is detected, this will be the same as `original_query` example: what is python corrected_query_with_markups: title: Corrected Query With Markups type: string description: >- The corrected spelling suggested by Miso where the revised tokens are surrounded by the <mark> tags. example: what is <mark>python</mark> FacetCounts: title: FacetCounts type: object properties: facet_fields: title: Facet Fields type: object additionalProperties: type: array items: type: array items: anyOf: - type: string - type: integer description: Facet counts of each facet field default: {} Campaign: title: Campaign type: object properties: name: title: Name type: string description: >- Name of the campaign. Identifies a specific product promotion or strategic campaign. (see [UTM parameters](https://en.wikipedia.org/wiki/UTM_parameters)) example: spring_sale source: title: Source type: string description: >- Source of the campaign. Identifies which site sent the traffic. (see [UTM parameters](https://en.wikipedia.org/wiki/UTM_parameters)) example: Google medium: title: Medium type: string description: >- Medium of the campaign that identifies what type of link was used, such as cost per click or email. (see [UTM parameters](https://en.wikipedia.org/wiki/UTM_parameters)) example: cpc term: title: Term type: string description: >- Term of the campaign that identifies search terms. (see [UTM parameters](https://en.wikipedia.org/wiki/UTM_parameters)) example: running+shoes content: title: Content type: string description: >- Content of the campaign that identifies what specifically was clicked to bring the user to the site, such as a banner ad or a text link. It is often used for A/B testing and content-targeted ads. Identifies search terms. (see [UTM parameters](https://en.wikipedia.org/wiki/UTM_parameters)) example: textlink Page: title: Page required: - url type: object properties: url: title: Url type: string description: Url of the page example: https://example.com/miso-tshirt-123ABC referrer: title: Referrer type: string description: Url of the referrer page example: https://example.com/ title: title: Title type: string description: Title of the page example: My Product Page securitySchemes: Secret API Key: type: apiKey description: >+ Your secret API key is used to access every Miso API endpoint. You should secure this key and only use it on a backend server. Never leave this key in your client-side JavaScript code. If the private key is compromised, you can revoke it in [Dojo](https://dojo.askmiso.com/docs/api-browser) and get a new one. Specify your secret key in the `api_key` query parameter. For example: ``` POST /v1/users?api_key=039c501ac8dfcac91c6f05601cee876e1cc07e17 ``` in: query name: api_key ````