Product / Content Upload API

The unique identifier for this product. The Id can be in any format you use in your product database (e.g. the product's SKU, UPC, or UUID or serial number). We will use this Id to track how users interact with products and content in the Interactions records you upload to Miso. It is important to keep the Id consistent between two datasets. For products that have multiple variants, you should have a unique product_id for each variant, and use product_group_id to group them together.

For example, for a T-shirt with SKU 123ABC that comes in 4 sizes: S, M, L, XL, we should create four different products:

{ 
  "product_id": "123ABC-S",
  "product_group_id" "123ABC"
}
{ 
  "product_id": "123ABC-M",
  "product_group_id" "123ABC"
}
{ 
  "product_id": "123ABC-L",
  "product_group_id" "123ABC"
}
{ 
  "product_id": "123ABC-XL",
  "product_group_id" "123ABC"
}

• Constraints
  • Can't contain ,
  • Can't start with _
  • Length <= 512

The product_group_id is used to prevent the same product (but a different variant) from showing multiple times in the search or recommendation results. When one product has multiple variants (for example, different sizes, colors, or materials), you should assign a unique product_id to each variant, but assign the same product_group_id to all of them. If product_group_id is not given, we default to the value of product_id.

The parent_id is used to declare a parent-child relationship between two "Products". Such relationships are common in marketplaces and content media sites with user generated contents. For example, an E-commerce marketplace (such as E-bay or Amazon) may have "Shops" (as parents) and "Merchandises" (as children), and a social streaming site, such as YouTube, may have "Channel" (as parents) and "Video" (as children). In these sites, both entities can be modeled as "Products", and can both be returned in Search and Recommendation APIs.

Declaring the parent-child relationships allows Miso to automatically propagate interactions from one product to the other. For example, when a user "watch" a Video, Miso will propagate this signal to the Channel which publishes this Video, even if users do not directly interact with the Channel page. Such implicit interactions are particularly useful when making recommendations for Channel because it gives Miso much more information about users' interests to different Channels than solely relying on users' direct interactions with the them, which happens less often.

parent_id needs to be a non-empty string referring to the product_id of the parent product. The parent product can be uploaded in a separate batch, and does not need to exist before its children products.

The implicit interactions will only exist during Miso's training process, and will not show up in the Interaction dataset.

The type of product. This is for sites that have more than one type of product or content that they want their users to interact with. If your site has only one type of product, you can leave this field out. A classic example is travel sites, which have both hotel and flight sales. It is also useful for sites that let users interact with products as well as product bundles. For example, on YouTube, each video is a product that users can watch, while each channel, containing multiple videos, is also a product that users can subscribe to.

For model quality, it is preferable to model all these distinct product types in the same data set, so that a user's interests for one type of product can inform their interests in another type of products. The type field helps Miso make these distinctions.

The title of the product. During a search, Miso will put predictive weight behind the title, because it is often the main way users identify a product.

The description text of the product. Miso assumes description contains longer textual content than other string-based fields. For example, term frequency matters more here than in a field like the title. Miso’s semantic understanding can extract a lot of valuable information from having a product description that is plain-spoken and detailed.

The short_description text of the product. Miso assumes short_description contains a shorter version or a summary of the description field.

The language of the product description and content in two-letter ISO 639-1 code. For example, English = en, Chinese = zh. Miso will use this field to determine the proper way to index the product description. If this field is not specified, we will determine the language automatically.

We also use the language field to determine users’ interests in content of different languages. This is particularly important for content media sites that have different languages of content.

• Constraints:
  • Two-letter ISO 639-1 code. For example, English = en, Chinese = zh.

The time when the product was first created or became available on your site as an ISO-8601 date or datetime string.

The time when the product was published as an ISO-8601 date or datetime string.

The time when the product was updated as an ISO-8601 date or datetime string.

Url to the product detail page. This is for displaying the product in your Dojo Sandboxes and is not used for Engine training. It is optional, but strongly recommended for a better Sandbox experience.

The URL of the cover image of the product. This is for displaying the product in your Dojo Sandboxes and is not used for Engine training. It is optional, but strongly recommended for a better Sandbox experience.

The (original) price of the product. We only use this number to calculate the amount of discount, and use that to profile user behaviors.

• Constraints:
  • Need to be a number, but no constraint on the range of the number

The sale price of the product.

• Constraints:
  • Need to be a number, but no constraint on the range of the number

The margin of the product. Note that for our margin optimization algorithm to work, the margin you specify here does not need to be the actual dollar amount, but it needs to be something in proportion to that.

• Constraints:
  • Need to be a number, but no constraint on the range of the number

The size of the product. For example, for an eCommerce site that sells T-shirts, each T-shirt might come in several different sizes. In this case, we recommend that you should create one product entry for each size variant. When Miso generate search or recommendation results, we use the product_group_id to remove different variants of the same product, and only show the variant that the user is most likely to buy.

The color of the products. Similarly to size, when color of the products matters, it is recommended to create one product for each color variant of a product. When Miso generate search or recommendation results, we use the product_group_id to remove variants of the same product, and only show the variant that the user is most likely to buy.

The material of the products. Similarly to size and color, if material of the product matters and there are multiple material variants, we should create one product for each material variant. When Miso generates search or recommendation results, we use the product_group_id to remove variants of the same product, and only show the variant that the user is most likely to buy.

The condition of the product. By default, we assume condition= NEW

The brand of the product.

The availability of the product. Miso mainly uses availability to filter OUT_OF_STOCK items out of its recommendations. As a default, we assume the product is IN_STOCK.

The overall rating of the product in the range of [0, 5]. If you use a different rating scale, please convert it to the range of [0, 5].

The HTML content of the product. Miso will search against this field and apply semantic understanding in a way that is similar to the description field, but with HTML tags removed.

The subtitle of the product (usually for contents).

Whether to enable question answering capability against the html field.