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:
-
In the header, click your username, and select API Access.
-
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
Parameter | Description | Type | Role | Example |
---|---|---|---|---|
| Request type. Use the value | String | Required |
|
| Site origin. To find out your site's origin, see Getting your site origin. | String | Required |
|
| ID of the Smart Discovery strategy whose generated data to retrieve. | String | Required |
|
| 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 | Object See Page context object. | Required |
|
| 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 |
|
| 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 The default value is | Number | Optional |
|
| 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:
The default value is empty. Each visitor's profiling choice is stored in their context. You can get the choice using the 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 worksIf you set the value to If you set the value to | String | Optional |
|
| 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:
The possible values are:
The default value is | Boolean | Optional |
|
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.
Property | Description | Type | Role | Example |
---|---|---|---|---|
| Type of the page where the API request is made. The possible values are:
note The value must match the page type of the Smart Discovery strategy. | String | Required |
|
| Contextual information about the brand page where the API request is made. This property is required only if the | Required |
| |
| Contextual information about the category page where the API request is made. This property is required only if the | Required |
|
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.
Property | Description | Type | Role | Example |
---|---|---|---|---|
| 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 For more information about the returned data, see Responses. | String | Required |
|
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.
Property | Description | Type | Role | Example |
---|---|---|---|---|
| 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:
For more information about the returned data, see Responses. | Array of strings | Required |
|
Request examples
GET https://inpref.com/smartDiscoveryApi?method=strategy&
origin=shop_company_com&
strategy=home&
context={
"page": {
"type": "home"
}
}&
cookieId=dsr77t.kstzihlx
GET https://inpref.com/smartDiscoveryApi?method=strategy&
origin=shop_company_com&
strategy=category&
context={
"page": {
"type": "category",
"category": {
"categories": [
"Fashion/Shoes"
]
}
}
}&
cookieId=dsr77t.kstzihlx
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. IfpageType
ishome
, 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.noteFor 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.
noteIf two collections have the same
image
value, the API considers them duplicates and removes the collection with the lowerweight
(a measure of item popularity). -
-
-
debug
: Object containing the debugging information. This property is included only when thedebug
parameter is set totrue
in the request.
{
"data": [{
"pageType": "<page_type>",
"attributeValue": "<category_name | empty>",
"items": [
{<collection 1 data>},
{<collection 2 data>},
...
{<collection n data>}
]
}]
}
{
"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.
{
"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
}
]
}
]
}
{
"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.
Error message | Description | Solution |
---|---|---|
| The | Provide the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide |
| The | Provide the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide a valid site origin as the value of the To find out your site's origin, see Getting your site origin. |
| The | Provide the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide a valid Smart Discovery strategy ID as the value of the |
| The | Provide the |
| The | Provide the |
| The value of the | Provide a valid JSON object as the value of the |
| The value of the | Provide a non-empty value for the |
| The value of the | Provide a value that conforms to the following rules:
|
| The value of the | Provide a non-empty value for the |
| The value of the | If you want to define a maximum number of collections to return, set the If you do not want to define a maximum number of collections to return, omit the |
| The value of the | If you want to define the visitor's profiling choice, set the If you do not want to define the visitor's profiling choice, set the |