Learn how to make a Smart Discovery API request to retrieve the data for a Smart Discovery:
For more information about Smart Discovery, see Feature: Smart Discovery.
Requests
URL
The URL for Smart Discovery API requests is https://<platform_instance>/recoApi/v2?method=smartDiscovery, where <platform_instance> is the domain name of your Frosmo Platform instance.
To get the URL for your Frosmo Platform instance:
- Log in to the Frosmo Control Panel, and select your site.
- 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>/recoApi/v2?method=smartDiscovery&
origin=<site_origin>&
pageType=<page_type>&
context=<page_context>&
cookieId=<local_frosmo_id>
Parameters
Table: Query parameters for Smart Discovery API requests
| Parameter | Description | Type | Role | Example |
|---|---|---|---|---|
method | Request type. Use the value | String | Required | method=smartDiscovery |
origin | Site origin. To find out your site's origin, see Getting your site origin. | String | Required | origin=shop_company_com |
pageType | Type of the page for which to retrieve the Smart Discovery data. The possible values are:
| String | Required | pageType=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. The value is a JSON object containing a single | 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 | Local Frosmo ID of the visitor who sees the Smart Discovery. The platform uses the ID to sort the suggestions in the Smart Discovery data based on the visitor's affinities. | String | Required | cookieId=dsr77t.kstzihlx |
limit | Maximum number of suggestions to return in the Smart Discovery data. The API returns the top suggestions by relevance (as determined by item popularity and the visitor's affinities). The minimum value is The default value is | 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:
The default value is empty. Each visitor's profiling choice is stored in their context. You can get the choice using the 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 | profile=opt-out |
debug | Define whether to return debugging information about the request. 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 | 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.
Table: Page context object properties
| Property | Description | Type | Role | Example |
|---|---|---|---|---|
type | Type of the page where the API request is made. The possible values are:
The value must match the | String | Required | "type": "category" |
category | Contextual information about the category page where the API request is made. This property is required only if the | Category page context object | Required | "category": {
"categories": [
"Fashion/Shoes"
]
}
|
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.
Table: 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:
For more information about the returned data, see Responses. | Array of strings | Required | "categories": [ "Fashion/Shoes" ] |
Request examples
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: Array of objects with a single object containing the following properties:pageType: Type of the page whose Smart Discovery data was returned.attributeValue: Name of the category whose Smart Discovery data was returned. The name matches the category name passed in the category page context object. IfpageTypeishome, the value is empty.items: Smart Discovery data as an array of objects, where each object contains the details of a single Smart Discovery suggestion. The suggestions 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 suggestions in a Smart Discovery web page element.For categories:
- If the category name passed in the category page context object matched a single discovery, the data contains the suggestions from that discovery.
- If the category name passed in the category page context object matched multiple discoveries, the data contains the suggestions from all the discoveries ranked by weight and with duplicate suggestions removed.
If two suggestions have the same
imagevalue, the API considers them duplicates and removes the suggestion with the lowerweight(a measure of item popularity).
debug: Object containing the debugging information. This property is included only when thedebugparameter is set totruein the request.
{
"data": [{
"pageType": "<page_type>",
"attributeValue": "<category_name | empty>",
"items": [
{<suggestion 1 data>},
{<suggestion 2 data>},
...
{<suggestion n data>}
]
}]
}
{
"data": [{
"pageType": "<page_type>",
"attributeValue": "<category_name | empty>",
"items": [
{<suggestion 1 data>},
{<suggestion 2 data>},
...
{<suggestion n data>}
]
}],
"debug": {
<debugging information>
}
}
Success examples
The following two examples show the same response without and with debugging information.
Error
On an error, the Smart Discovery API returns the response status code 400 and an error message.
Table: 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 smartDiscovery 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 To find out your site's origin, see Getting your site origin. |
parameter 'pageType' invalid, expected either 'category' or 'home' | The pageType query parameter is missing from the request URL or the value of the parameter is invalid or missing. | Provide the
|
parameter 'context' invalid: missing category value | The context query parameter is missing from the request URL or the value of the categories property is missing. | Provide the context query parameter, and make sure the categories property contains the name of a category. |
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. |
