Sign in

v1

latestOpenAPI 3.0.22026-08-0426137631.3 KB
Search APIs

Multiple Get API

The Multiple Get API provides a simple and fast interface to retrieve Products by their product ids. For example, the following query will retrieve products whose product_ids are 123ABC-S-Black and 123ABC-S-Blue

{
    "product_ids": ["123ABC-S-Black", "123ABC-S-Blue"]
}

Miso will respond with the complete Products records in the same order as the given product_ids:

{
  "message": "success",
  "data": {
    "products": [
      {
        "_found": true,
        "product_id": "123ABC-S-Black",
        "title": "Product ABC in Black",
        ...
      },
      {
        "_found": true,
        "product_id": "123ABC-S-Blue",
        "title": "Product ABC in Blue",
        ...
      }
    ]
  }
}

You can use the _found field to determine whether a product is found in the Miso database or not. When the given product_id is not found, the _found field in the corresponding Product record will become false.

For example, the following query requests a product_id that does not exist in the Miso database:

{
    "product_ids": ["Product_Not_Exists", "123ABC-S-Black"]
}

Miso will respond:

{
  "message": "success",
  "data": {
    "products": [
      {
        "_found": false,
        "product_id": "Product_Not_Exists"
      },
      {
        "_found": true,
        "product_id": "123ABC-S-Black",
        "title": "Product ABC in Black",
        ...
      }
    ]
  }
}

Finally, like every Miso API, you can use fl to control what Product fields to return. By default, all the Product fields will be returned, but the following query will return only title field of the product (in addition to product_id)

{
    "product_ids": ["123ABC-S-Black", "123ABC-S-Blue"],
    "fl": ["title"]
}
post/v1/search/mget

Request body

engine_idstring

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_idstring

The user who made the query and for whom Miso will personalize the results. For an anonymous visitor, use anonymous_id instead.

anonymous_idstring

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_hashstring

The hash of user_id (or anonymous_id) encrypted by your Secret API Key. user_hash is required to prevent unauthorized API access if you are making API calls with a Publishable API Key.

You should generate the user_hash via HMAC scheme: you encrypt the desired user_id (or anonymous_id) with your Secret API Key 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 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:

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

product_idsstring[] required

List of product_ids to retrieve. Products will be returned in the same order as they are given in this list.

flstring[]

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 (which is the default):

{"fl": ["*"]}

For the lowest latency, use an empty array to retrieve just the product_id field.

{"fl": []}

Response

Successful Response

messagestring

Example response

{
  "data": {
    "miso_id": "123e4567-e89b-12d3-a456-426614174000",
    "products": [
      {
        "product_id": "123ABC-S-Black"
      }
    ]
  }
}