Product / Content Read API

Authorizations

api_key

string

query

required

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 and get a new one.

Specify your secret key in the api_key query parameter. For example:

POST /v1/users?api_key=039c501ac8dfcac91c6f05601cee876e1cc07e17

Path Parameters

product_id

string

required

Maximum string length: 512

Response

Successful Response

message

string

required

data

ProductRecord · object

required

Show child attributes

data.product_id

string

required

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

Required string length: 1 - 512

Example:

"123ABC-S-Black"

data.product_group_id

string

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.

Example:

"123ABC"

data.parent_id

string

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.

Example:

"Nike_Shop_123"

The product_id or product_group_id of other products that are related to this Product

data.type

string

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.

Example:

"clothes"

data.title

string

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.

Example:

"Japanese Shiba Inu Dog Eating Miso Soup T-Shirt"

data.description

string

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.

Example:

"This cute Shiba inu dog eating Miso soup is perfect for those who love Japanese culture."

data.short_description

string

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

Example:

"Cute Shiba Inu Dog Eating Miso Soup T-Shirt"

data.language

string

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.

Minimum string length: 2

Example:

"en"

data.created_at

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

data.published_at

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

data.updated_at

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

data.categories

string[][]

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)

Example:

[
  [
    "Clothing, Shoes & Jewelry",
    "Women",
    "T-Shirts"
  ],
  ["Novelty", "Tops & Tees", "T-Shirts"]
]

data.tags

string[]

The tags that have been associated with the product.

For example:

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

Example:

["cute", "anime", "dogs", "t-shirt"]

data.url

string<uri>

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.

Required string length: 1 - 65536

Example:

"https://example.com/miso-tshirt-123ABC"

data.cover_image

string<uri>

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.

Required string length: 1 - 65536

Example:

"https://example.com/miso-tshirt-123ABC.jpg"

data.original_price

number

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

Example:

20

data.sale_price

number

The sale price of the product.

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

Example:

15

data.margin

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

Example:

15

data.size

string

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.

Example:

"S"

data.color

string

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.

Example:

"Black"

data.material

string

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.

Example:

"Cotton"

data.condition

enum<string>

default:NEW

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

Available options:

NEW,

USED,

REFURBISHED

data.brand

string

The brand of the product.

Example:

"Miso Corp."

data.authors

string[]

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

Example:

["Andy Hsieh"]

data.publishers

string[]

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

Example:

["O'Reilly Media"]

data.collections

string[]

The collection(s) the product belongs to.

Example:

[
  "Anime T-Shirt Collection",
  "Superhero T-Shirt Collection"
]

data.availability

enum<string>

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.

Available options:

IN_STOCK,

OUT_OF_STOCK,

PRE_ORDER

data.location

LocationInformation · object

LocationInformation · object[]
LocationInformation · object

Show child attributes

data.location.lat

number

required

Example:

40.74844

data.location.lon

number

required

Example:

-73.985664

data.rating

number

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

Example:

5

data.html

string

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.

data.subtitle

string

The subtitle of the product (usually for contents).

data.headers

string[]

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

data.paragraphs

string[]

The text paragraphs in the content. This usually corresponds to <p> tags in HTML. This field need to be an array of strings

data.anchors

string[]

The anchor texts paragraphs in the content. This usually corresponds to <a> tags in HTML. This field need to be an array of strings

data.children

ChildrenObject · object[]

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.

Show child attributes

data.children.id

string

required

data.children.url

string

data.children.title

string

data.children.description

string

data.children.html

string

data.children.headers

string[]

data.children.custom_attributes

Custom Attributes · object

Show child attributes

data.children.custom_attributes.{key}

data.enable_question_answering

boolean

default:false

Whether to enable question answering capability against the html field.

data.custom_attributes

Custom Attributes · object

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.

Show child attributes

data.custom_attributes.{key}

Example:

{
  "cast": ["Robin Williams", "Jonathan Hyde"],
  "director": "Joe Johnston",
  "genres": ["Adventure", "Fantasy", "Family"],
  "popularity": 7.439,
  "adult": false
}

API Documentation

Experiment APIs

Data APIs

Response Format

Example Response

Example Error Response

Authorizations

Path Parameters

Response