Smart Discovery API reference

Learn how to make a Smart Discovery API request to retrieve Smart Discovery data.

For more information about Smart Discovery, see Feature: Smart Discovery.

Requests

URL

The URL for Smart Discovery API requests is https://<platform_instance>/smartDiscoveryApi?method=strategy, where <platform_instance> is the domain name of your Frosmo Platform instance.

To get the URL for your Frosmo Platform instance:

1. Log in to the Frosmo Control Panel, and select your site.

2. In the header, click your username, and select API Access.

3. In the Smart Discovery section, copy the URL.

   

Authentication

The Smart Discovery API does not require authentication.

Methods

The Smart Discovery API supports the GET HTTP method for retrieving Smart Discovery data.

Syntax

To retrieve Smart Discovery data, make the following GET request:

GET https://<platform_instance>/smartDiscoveryApi?method=strategy&
    origin=<site_origin>&
    strategy=<strategy_id>&
    context=<page_context>&
    cookieId=<local_frosmo_id>

Parameters

Query parameters for Smart Discovery API requests

Parameter	Description	Type	Role	Example
method	Request type. Use the value strategy.	String	Required	method=strategy
origin	Site origin. To find out your site's origin, see Getting your site origin.	String	Required	origin=shop_company_com
strategy	ID of the Smart Discovery strategy whose generated data to retrieve.	String	Required	strategy=home
context	Contextual information about the page where the API request is made. The information allows the API to return the correct Smart Discovery data for the page. The exact information required depends on the page type of the Smart Discovery strategy. The value is a JSON object containing a single page property: the page context object.	Object See Page context object.	Required	# Home page context context={ "page": { "type": "home" } } # Category page context context={ "page": { "type": "category", "category": { "categories": [ "Fashion/Shoes" ] } } }
cookieId	Frosmo ID of the visitor who sees the Smart Discovery. The platform uses the ID to sort the collections in the Smart Discovery based on the visitor's affinities. To get the ID, see Getting a visitor's Frosmo ID. This parameter is required if you want to personalize the Smart Discovery for individual visitors. note Do not set this parameter if the site uses selective profiling and the visitor has opted out.	String	Optional	cookieId=dsr77t.kstzihlx
limit	Maximum number of collections to return in the Smart Discovery data. The API returns the top collections by relevance (as determined by item popularity and the visitor's affinities). The minimum value is 1. There is no maximum value. The default value is 20.	Number	Optional	limit=10
profile	Define the visitor's profiling choice if the site uses selective profiling. The choice determines whether the API returns Smart Discovery data that is personalized for the visitor. The possible values are: opt-in: The visitor has opted in to seeing personalized, targeted content. opt-out: The visitor has opted out of seeing personalized, targeted content. Empty: The visitor has not made their profiling choice. The default value is empty. Each visitor's profiling choice is stored in their context. You can get the choice using the frosmo.easy.profile.get() function. note You must always define this parameter on a site that uses selective profiling. Never define this parameter on a site that does not use selective profiling. How the profiling choice works If you set the value to opt-in or empty, the API returns the Smart Discovery data normally. If you set the value to opt-out, the API returns the baseline Smart Discovery data, meaning the platform does not sort the collections in the data based on the visitor's affinities.	String	Optional	profile=opt-out
debug	Define whether to return debugging information about the request. warning Use the debugging information only for development and testing purposes. Do not use the information in production, since Frosmo does not guarantee that the information structure and content will remain the same. The debugging information consists of: Affinity profile of the visitor specified by the cookieId parameter Additional details about the request, such as issues that did not cause the request to fail but that may indicate a problem The possible values are: false: Do not return debugging information. true: Return debugging information. The default value is false.	Boolean	Optional	debug=true

Page context object

The following table describes the page object of the context parameter value. The page object provides contextual information about the page where the API request is made.

Page context object properties

Property	Description	Type	Role	Example
type	Type of the page where the API request is made. The possible values are: brand: The API request is made on a brand page. category: The API request is made on a category page. home: The API request is made on the site home page. note The value must match the page type of the Smart Discovery strategy.	String	Required	"type": "category"
brand	Contextual information about the brand page where the API request is made. This property is required only if the type property is set to brand.	Brand page context object	Required	"brand": { "name": "Wakita" }
category	Contextual information about the category page where the API request is made. This property is required only if the type property is set to category.	Category page context object	Required	"category": { "categories": [ "Fashion/Shoes" ] }

Brand page context object

The following table describes the brand object of the page context object. The brand object provides contextual information about the brand page where the API request is made.

Brand page context object properties

Property	Description	Type	Role	Example
name	Name of the brand. Smart Discovery uses exact matching to check the brand name against brand-based discoveries generated for the site. For example, if the current brand page is Wakita, the API only returns the discovery whose brand name is exactly "Wakita". The API does not return discoveries for, for example, Wakita Industrial or Wakita Tools. For more information about the returned data, see Responses.	String	Required	"name": "Wakita"

Category page context object

The following table describes the category object of the page context object. The category object provides contextual information about the category page where the API request is made.

Category page context object properties

Property	Description	Type	Role	Example
categories	Names of the categories whose items are shown on the category page where the API request is made. Smart Discovery only uses the first name in the array. Make sure the first name is the category whose Smart Discovery data you want to retrieve. Smart Discovery uses "starts with" partial matching to check the category name against category-based discoveries generated for the site. For example: If the current category page is Fashion, the API returns all discoveries whose category name starts with "Fashion", such as Fashion, Fashion/Shoes, and Fashion/Shoes/Sneakers. If the current category page is Fashion/Shoes, the API returns all discoveries whose category name starts with "Fashion/Shoes", such as Fashion/Shoes and Fashion/Shoes/Sneakers. For more information about the returned data, see Responses.	Array of strings	Required	"categories": [ "Fashion/Shoes" ]

Request examples

Example: Retrieve Smart Discovery data for the home page

GET https://inpref.com/smartDiscoveryApi?method=strategy&
    origin=shop_company_com&
    strategy=home&
    context={
      "page": {
        "type": "home"
      }
    }&
    cookieId=dsr77t.kstzihlx

Example: Retrieve Smart Discovery data for a category page

GET https://inpref.com/smartDiscoveryApi?method=strategy&
    origin=shop_company_com&
    strategy=category&
    context={
      "page": {
        "type": "category",
        "category": {
          "categories": [
            "Fashion/Shoes"
          ]
        }
      }
    }&
    cookieId=dsr77t.kstzihlx

Example: Retrieve Smart Discovery data for a category page with a custom collections limit

GET https://inpref.com/smartDiscoveryApi?method=strategy&
    origin=shop_company_com&
    strategy=category&
    context={
      "page": {
        "type": "category",
        "category": {
          "categories": [
            "Fashion/Shoes"
          ]
        }
      }
    }&
    cookieId=dsr77t.kstzihlx&
    limit=10

Responses

Success

On a success, the Smart Discovery API returns the requested Smart Discovery data in a JSON object. The response status code is 200.

The response object contains the following root properties:

• data: Smart Discovery data as an array of objects, where each object contains the details of a single Smart Discovery. Each object contains the following properties:

  • pageType: Type of the page whose Smart Discovery data was returned.

  • attributeValue: Name of the brand or category whose Smart Discovery data was returned. The name matches the name passed in the corresponding page context object. If pageType is home, the value is empty.

  • items: Smart Discovery data as an array of objects, where each object contains the details of a single Smart Discovery collection. The collections are in descending order of relevance (as determined by item popularity and the visitor's affinities). Use the details to build and render the individual collections in a Smart Discovery web page element.

    note

    For categories:

    • If the category name passed in the category page context object matched a single discovery, the data contains the collections from that discovery.

    • If the category name passed in the category page context object matched multiple discoveries, the data contains the collections from all the discoveries ranked by weight and with duplicate collections removed.

    note

    If two collections have the same image value, the API considers them duplicates and removes the collection with the lower weight (a measure of item popularity).

• debug: Object containing the debugging information. This property is included only when the debug parameter is set to true in the request.

Response structure without debugging information

{
  "data": [{
    "pageType": "<page_type>",
    "attributeValue": "<category_name | empty>",
    "items": [
      {<collection 1 data>},
      {<collection 2 data>},
      ...
      {<collection n data>}
    ]
  }]
}

Response structure with debugging information

{
  "data": [{
    "pageType": "<page_type>",
    "attributeValue": "<category_name | empty>",
    "items": [
      {<collection 1 data>},
      {<collection 2 data>},
      ...
      {<collection n data>}
    ]
  }],
  "debug": {
    <debugging information>
  }
}

Success examples

The following two examples show the same response without and with debugging information.

Example: Response with Smart Discovery data only

{
  "data": [
    {
      "pageType": "home",
      "attributeValue": "",
      "items": [
        {
          "query": "Wakita Drills",
          "title": "Wakita Drills",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-4.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Drills"
          },
          "weight": 59
        },
        {
          "query": "Wakita Woodworking",
          "title": "Wakita Woodworking",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-1.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Woodworking"
          },
          "weight": 57
        },
        {
          "query": "Wakita Saws",
          "title": "Wakita Saws",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-2.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Saws"
          },
          "weight": 50
        },
        {
          "query": "Wakita Large Tools",
          "title": "Wakita Large Tools",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-6.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Large Tools"
          },
          "weight": 49
        },
        {
          "query": "Wakita Plumbing",
          "title": "Wakita Plumbing",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-8.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Plumbing"
          },
          "weight": 48
        },
        {
          "query": "Wakita Wrenches and Pliers",
          "title": "Wakita Wrenches and Pliers",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-5.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Wrenches and Pliers"
          },
          "weight": 42
        },
        {
          "query": "Sawyer Saws",
          "title": "Sawyer Saws",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-3.jpg",
          "affinity": 1280,
          "facets": {
            "brand": "Sawyer",
            "subcategory": "Saws"
          },
          "weight": 40
        },
        {
          "query": "Cakita Drills",
          "title": "Cakita Drills",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-16.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Drills"
          },
          "weight": 37
        },
        {
          "query": "Cakita Woodworking",
          "title": "Cakita Woodworking",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-15.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Woodworking"
          },
          "weight": 35
        },
        {
          "query": "Cakita Compressors",
          "title": "Cakita Compressors",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-14.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Compressors"
          },
          "weight": 31
        },
        {
          "query": "Cakita Large Tools",
          "title": "Cakita Large Tools",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-13.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Large Tools"
          },
          "weight": 25
        },
        {
          "query": "Cakita Wrenches and Pliers",
          "title": "Cakita Wrenches and Pliers",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-9.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Wrenches and Pliers"
          },
          "weight": 23
        },
        {
          "query": "Cakita Kits",
          "title": "Cakita Kits",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-11.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Kits"
          },
          "weight": 19
        },
        {
          "query": "Cakita Chain Saws",
          "title": "Cakita Chain Saws",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-12.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Chain Saws"
          },
          "weight": 14
        },
        {
          "query": "Cakita Plumbing",
          "title": "Cakita Plumbing",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-10.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Plumbing"
          },
          "weight": 9
        },
        {
          "query": "Wrenchy Wrenches and Pliers",
          "title": "Wrenchy Wrenches and Pliers",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-7.jpg",
          "affinity": 0,
          "facets": {
            "brand": "Wrenchy",
            "subcategory": "Wrenches and Pliers"
          },
          "weight": 5
        }
      ]
    }
  ]
}

Example: Response with Smart Discovery data and debugging information

{
  "data": [
    {
      "pageType": "home",
      "attributeValue": "",
      "items": [
        {
          "query": "Wakita Drills",
          "title": "Wakita Drills",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-4.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Drills"
          },
          "weight": 59
        },
        {
          "query": "Wakita Woodworking",
          "title": "Wakita Woodworking",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-1.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Woodworking"
          },
          "weight": 57
        },
        {
          "query": "Wakita Saws",
          "title": "Wakita Saws",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-2.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Saws"
          },
          "weight": 50
        },
        {
          "query": "Wakita Large Tools",
          "title": "Wakita Large Tools",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-6.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Large Tools"
          },
          "weight": 49
        },
        {
          "query": "Wakita Plumbing",
          "title": "Wakita Plumbing",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-8.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Plumbing"
          },
          "weight": 48
        },
        {
          "query": "Wakita Wrenches and Pliers",
          "title": "Wakita Wrenches and Pliers",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-5.jpg",
          "affinity": 6880,
          "facets": {
            "brand": "Wakita",
            "subcategory": "Wrenches and Pliers"
          },
          "weight": 42
        },
        {
          "query": "Sawyer Saws",
          "title": "Sawyer Saws",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-3.jpg",
          "affinity": 1280,
          "facets": {
            "brand": "Sawyer",
            "subcategory": "Saws"
          },
          "weight": 40
        },
        {
          "query": "Cakita Drills",
          "title": "Cakita Drills",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-16.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Drills"
          },
          "weight": 37
        },
        {
          "query": "Cakita Woodworking",
          "title": "Cakita Woodworking",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-15.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Woodworking"
          },
          "weight": 35
        },
        {
          "query": "Cakita Compressors",
          "title": "Cakita Compressors",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-14.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Compressors"
          },
          "weight": 31
        },
        {
          "query": "Cakita Large Tools",
          "title": "Cakita Large Tools",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-13.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Large Tools"
          },
          "weight": 25
        },
        {
          "query": "Cakita Wrenches and Pliers",
          "title": "Cakita Wrenches and Pliers",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-9.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Wrenches and Pliers"
          },
          "weight": 23
        },
        {
          "query": "Cakita Kits",
          "title": "Cakita Kits",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-11.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Kits"
          },
          "weight": 19
        },
        {
          "query": "Cakita Chain Saws",
          "title": "Cakita Chain Saws",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-12.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Chain Saws"
          },
          "weight": 14
        },
        {
          "query": "Cakita Plumbing",
          "title": "Cakita Plumbing",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-10.jpg",
          "affinity": 480,
          "facets": {
            "brand": "Cakita",
            "subcategory": "Plumbing"
          },
          "weight": 9
        },
        {
          "query": "Wrenchy Wrenches and Pliers",
          "title": "Wrenchy Wrenches and Pliers",
          "image": "https://sales-retail-bp.docker-box.inpref.com/images/products/product-7.jpg",
          "affinity": 0,
          "facets": {
            "brand": "Wrenchy",
            "subcategory": "Wrenches and Pliers"
          },
          "weight": 5
        }
      ]
    }
  ],
  "debug": {
    "affinity": {
      "applied": true,
      "userScores": {
        "scores": {
          "brand": {
            "cakita": 480,
            "sawyer": 1280,
            "wakita": 6880
          },
          "category": {
            "other/plumbing": 480,
            "power tools/drills": 3200,
            "power tools/saws": 2560,
            "power tools/woodworking": 2400
          },
          "manufacturer": {
            "cakita": 480,
            "sawyer": 1280,
            "wakita": 6880
          },
          "type": {
            "other/plumbing": 480,
            "power tools/drills": 3200,
            "power tools/saws": 2560,
            "power tools/woodworking": 2400
          }
        },
        "created_at": "2023-06-12T14:52:48+02:00",
        "updated_at": "2023-06-12T20:19:26+02:00"
      },
      "details": [

      ]
    }
  }
}

Error

On an error, the Smart Discovery API returns the response status code 400 and an error message.

Smart Discovery API error messages

Error message	Description	Solution
parameter 'method' missing	The method query parameter is missing from the request URL.	Provide the method query parameter.
parameter 'method' contains an empty value	The value of the method query parameter is missing.	Provide a non-empty value for the method query parameter.
parameter 'method' invalid	The value of the method query parameter is invalid.	Provide strategy as the value of the method query parameter.
parameter 'origin' missing	The origin query parameter is missing from the request URL.	Provide the origin query parameter.
parameter 'origin' contains an empty value	The value of the origin query parameter is missing.	Provide a non-empty value for the origin query parameter.
parameter 'origin' invalid	The value of the origin query parameter is invalid.	Provide a valid site origin as the value of the origin query parameter. To find out your site's origin, see Getting your site origin.
parameter 'strategy' missing	The strategy query parameter is missing from the request URL.	Provide the strategy query parameter.
parameter 'strategy' contains an empty value	The value of the strategy query parameter is missing.	Provide a non-empty value for the strategy query parameter.
invalid strategy parameter '<value>'	The value of the strategy query parameter is invalid.	Provide a valid Smart Discovery strategy ID as the value of the strategy query parameter.
parameter 'context' invalid: missing brand name	The context query parameter is missing from the request URL, or the brand.name context property is missing or has an empty value.	Provide the context query parameter, and make sure the brand.name context property is defined.
parameter 'context' invalid: missing category value	The context query parameter is missing from the request URL, or the category.categories context property is missing or has an empty value.	Provide the context query parameter, and make sure the category.categories context property is defined.
parameter 'context' contains invalid JSON: failed to parse	The value of the context query parameter is not a valid JSON object.	Provide a valid JSON object as the value of the context query parameter.
parameter 'cookieId' contains an empty value	The value of the cookieId query parameter is missing.	Provide a non-empty value for the cookieId query parameter.
parameter 'cookieId' has invalid format	The value of the cookieId query parameter has an invalid format.	Provide a value that conforms to the following rules: The length of the value is 1-24 characters. The value contains only the following ASCII characters (in any combination): Letters: A to Z (upper case) and a to z (lower case) Numbers: 0 to 9 Special characters: . (period), _ (underscore), + (plus sign), - (hyphen)
parameter 'limit' contains an empty value	The value of the limit query parameter is missing.	Provide a non-empty value for the limit query parameter.
parameter 'limit' invalid, expected number greater than 0"	The value of the limit query parameter is invalid.	If you want to define a maximum number of collections to return, set the limit query parameter to a positive integer. If you do not want to define a maximum number of collections to return, omit the limit query parameter from the request URL.
parameter 'profile' invalid, expected either '', 'opt-in' or 'opt-out'	The value of the profile query parameter is invalid.	If you want to define the visitor's profiling choice, set the profile query parameter to opt-in or opt-out. If you do not want to define the visitor's profiling choice, set the profile query parameter to an empty value, or omit the parameter from the request URL.