ProductRecord

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 anchor texts paragraphs in the content. This usually corresponds to <a> tags in HTML. This field need to be an array of strings

The author(s) of the product or content asset. This field needs to be an array of strings.

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 brand of the product.

In Miso, you describe a product or content category as a hierarchical list of strings from broad to narrow, called a category. (See the category_page_view interaction.)

Use the categories field of products to specify the hierarchical category or categories that the product belongs to. A product may belong to only a single category, or multiple.

For example, a product could be in both:

• Toys & Games > Toys > Dolls, Playsets & Toy Figures > Stuffed Animals, and
• Arts & Entertainment > Hobbies & Creative Arts > Collectibles.

This field should be a list of a list of strings, where category levels go from broad to narrow, such as:

{"categories":
    [
        // the first category the product belongs to
        ["TOYS & GAMES", "TOYS", "DOLLS, PLAYSETS & TOY FIGURES", "STUFFED ANIMALS"],
        // the second category the product belongs to
        ["ARTS & ENTERTAINMENT", "HOBBIES & CREATIVE ARTS", "COLLECTIBLES"]
    ]
}

If your product taxonomy has only one single level, that is not an issue:

{"categories":
    [
        // the first category the product belongs to
        ["Toys"],
        // the second category the product belongs to
        ["Collectibles"]
    ]
}

The categories are optional, but very important for profiling the products and tracking users' preferences. (See also the category_page_view interaction)

Children objects of the product, such as chapters of a book, or sections of a podcast. Children are only useful for long-form contents, and are only used for snippet extraction purpose.

The collection(s) the product belongs to.

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 condition of the product. By default, we assume condition= NEW

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 time when the product was first created or became available on your site as an ISO-8601 date or datetime string.

Dictionary of custom attributes for the product. You can specify attributes specific to your business 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

For example, a video streaming site using Miso may have the movie Jumanji with the following custom attributes:

{
  "custom_attributes": {
    "cast": [
      "Robin Williams", "Jonathan Hyde", ...
    ],
    "director": "Joe Johnston",
    "genres": [
      "Adventure", "Fantasy", "Family"
    ],
    "filming_locations": [
       {"country": "USA", "state": "New Hampshire", "city": "Keene"},
       {"country": "Canada", "state": "British Columbia", "city": "Vancouver"}
    ],
    "popularity": 7.439,
    "adult": false
  }
}

The custom attribute types need to be consistent across every record in the dataset. For instance, in the example above, the cast attribute needs to be a string or an array of string or null for every record in the dataset that specify cast attribute.

Similarly, the popularity attribute needs to be a number, an array of numbers, or null for every record in the dataset that specifies the popularity attribute. If you try to insert a record with an incompatible data type, the insertion for that record will fail.

The description text of the product. Use it when you do not have HTML; otherwise prefer html, which also carries the structure of the document.

Miso assumes description holds longer text than the other string fields. For example, term frequency matters more here than in a field such as the title. A plain-spoken, detailed description gives Miso's semantic understanding more to work with.

Whether to enable question answering capability against the html field.

The headers in the content. This usually corresponds to <h1>, <h2>, <h3> ... tags in HTML. This field need to be an array of strings

The HTML content of the product, and the preferred field for the body text.

Miso searches this field and applies semantic understanding to it, in the same way as description. It also reads the tags to understand the structure of the document — where a heading starts a section, what belongs to one paragraph, and what is a list or a table. That structure helps Miso find the passage that answers a question.

Send html when you have it. Send description when plain text is all you hold. There is no need to send the same body in both.

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 location information of the product (e.g. for hotels or restaurants). We support geolocation filtering and sorting when creating search and recommendation results if location information is given.

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 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 (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 text paragraphs in the content. This usually corresponds to <p> tags in HTML. This field need to be an array of strings

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 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 time when the product was published as an ISO-8601 date or datetime string.

The publisher(s) of the product or content asset. This field needs to be an array of strings.

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 product_id or product_group_id of other products that are related to this Product

The sale price of the product.

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

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

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 subtitle of the product (usually for contents).

The tags that have been associated with the product.

For example:

{"tags": ["TAG_1", "TAG_2", ...]}

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 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 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.