Search API reference

Learn how to make a Search API request to run a search query and retrieve the search results with Frosmo Search.

Requests

URL

The URL for Search API requests is https://<platform_instance>/search, 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 Search API section, copy the URL.

   

Authentication

The Search API does not require authentication.

Methods

The Search API supports the GET HTTP method for running search queries and retrieving the search results.

Syntax

To run a search query and retrieve the search results, make the following GET request:

GET https://<platform_instance>/search?origin=<site_origin>&
    q=<search_query>&
    filter=<filter_query>&
    sortBy=<list_of_sort_fields>

Parameters

Query parameters for search API requests

Parameter	Description	Type	Role	Example
origin	Site origin. To find out your site's origin, see Getting your site origin.	String	Required	origin=shop_company_com
cookieId	Frosmo ID of the visitor who triggered the search query and for whom you want to personalize the search results. The platform uses the ID to sort the search results based on the visitor's affinities. To get the ID, see Getting a visitor's Frosmo ID. note This parameter is required if the results are sorted by affinity. Sorting by affinity can be defined using the sortBy parameter, or it can be defined as a default in the site's basic search setup.	String	Optional	cookieId=dsr77t.kstzihlx
page	Search results page to return. This is the number of the page. If the total number of search results exceeds the perPage value, the API automatically paginates the results into multiple pages. To get all the results, you need to make a separate API request for each page. Page numbering starts at 1. The default is 1. note The number of results returned for a single page depends on the value of the perPage parameter. Usage If you need to get more results than fits on the first page, make multiple requests as follows: Make a single request for each page. Include the page parameter in each requst. Increment the page value by one for each request, starting with 1. Check the found property in the response to determine the total number of results that you need to paginate over. For example, if your search query matches 600 results, and your page size is 250, the results are spread over three pages (250 + 250 + 100) and you therefore need to make there requests, for pages 1, 2, and 3.	Number	Optional	page=1
perPage	Number of results to return. note This value is both per search results page and per request since a single API request returns the results from a single page. The maximum number of results depends on the includeFields parameter: If includeFields is empty or undefined, the maximum is 2000. If includeFields is defined with a non-empty value, the maximum is 250. If you need to get more results than the maximum, make multiple requests where you incrementally paginate over the results using the page parameter. The default is 10.	Number	Optional	perPage=100
q	Search term. The search returns all items that have an attribute whose value matches the search term. The match can be exact, partial, approximate ("fuzzy"), or synonym-based. The match ignores case. note The attributes that the search checks for matches depend on the target attributes defined for the site. Usage The basic syntax is: q=search_term If you omit this parameter, the search returns all items. tip To apply filtering on all items, omit q and use only filter.	String	Optional	# Search by a single word q=boots # Search by a phrase q=leather boots
filter	Filter for refining the search results based on the value of an item attribute. The API applies the filter on the results returned by the search term (q). note The attributes that you can use for filtering depend on the site's basic search setup. Usage The basic syntax is: filter=attribute_name:target_value # Example filter=brand:Lumberland The filter returns all items that have an attribute whose value matches the target value. The match can be exact or partial. The match ignores case. For example, brand:Frosmo returns items whose brand is Frosmo, Frosmo Search, or any other string that contains Frosmo, in whatever case. note To filter by item ID, use _id: filter=_id:121212 The value can be a single word or phrase. If the value contains one or more commas or other reserved characters, wrap the value in backtick characters (`) to denote a string literal. # Example filter=brand:Lumberland filter=brand:The South Face filter=brand:`Hello, Fashion` The filter supports the following use cases: Match a single value Match multiple values Match an exact value Match by negation Match numeric values Match in arrays Match multiple conditions Match a single value To filter by a single value, define the value as is: attribute:value Examples brand:Lumberland brand:The South Face Match multiple values To filter by multiple values, define the values as an array: attribute:[value_1,value_2,value_3] The filter returns all items that have an attribute whose value matches one of the target values. The match can be exact or partial. The match ignores case. Examples brand:[Lumberland,Stiffla] brand:[Lumberland,Stiffla,The South Face,`Hello, Fashion`] Match an exact value To filter by an exact value, use the equality operator (=): # Match a single exact value attribute:=value # Match any one of a set of exact values attribute:=[value_1,value_2,value_3] Examples # Match a single exact value brand:=Lumberland brand:=The South Face # Match any one of a set of exact values brand:=[Lumberland,The South Face] brand:=[Lumberland,The South Face,`Hello, Fashion`] Match by negation To filter by NOT matching a value, use the inequality operator (!=): # Do not match a single value attribute:!=value # Do not match any one of a set of values attribute:!=[value_1,value_2,value_3] Examples # Do not match a single value brand:!=Stiffla # Do not match any one of a set of values brand:!=[Stiffla,The South Face] brand:!=[Stiffla,The South Face,`Hello, Fashion`] note Negative filtering is only valid for faceted attributes. Faceting is defined in the site's basic search setup. Match numeric values To filter by numeric values, use a standard comparison operator (=, >, <, >=, <=) or the range operator ([min..max]): # Match an exact value attribute:=value # Match greater or lesser values attribute:>value attribute:<value attribute:>=value attribute:<=value # Match any value in a number range attribute:[min_value..max_value] You can also combine the range operator with multiple values to match any value in a number range or an exact numeric value: attribute:[min_value..max_value,value_1,value_2] Examples # Match greater values price:>100 # Match any value in a number range price:[100..1000] # Match any value in a number range or an exact value price:[100..1000,2000] Match in arrays To filter by a value in an array attribute, use the equality operator (=) with a single value or multiple values: # Match a single value in an array array_attribute:=value # Match any one of a set of values in an array array_attribute:=[value_1,value_2,value_3] The filter returns all items that have an array attribute with a value that matches the defined value or one of the defined values. The match can be exact or partial. The match ignores case. Examples # Match a single value in an array categories:=Boots # Match any one of a set of values in an array categories:=[Boots,Shoes,Sneakers] note Array filtering is only valid for array attributes. Match multiple conditions To filter by multiple conditions, use the && parameter (logical AND) and/or the || parameter (logical OR). Use parentheses to customize the order of precedence. # All conditions must be met attribute_1:value&&attribute_2:value&&attribute_3:value # Any one condition must be met attribute_1:value||attribute_2:value||attribute_3:value # First condition AND either of the other two conditions must be met attribute_1:value&&(attribute_2:value||attribute_3:value) You can use all the value operators described above to define the different conditions. Examples brand:Lumberland&&price:>100 brand:[Lumberland,Stiffla]&&price:[100..1000] (brand:Lumberland||brand:`Hello, Fashion`)&&price:>100	String	Optional	See the use case examples in the parameter description.
sortBy	List of fields and their respective sort orders for sorting the search results. The default sorting rules depend on the site's basic search setup. If you define the sortBy parameter, the API ignores the default rules and uses the logic you define in the parameter. For more information about how the platform sorts search results, see Feature: Search. Usage The basic syntax is: # Sort by one field sortBy=field_name:sort_order # Sort by multiple fields sortBy=field_name_1:sort_order,field_name_2:sort_order You can define up to three fields to sort by. Separate multiple fields with a comma. By default, you can use the following fields for sorting search results. text_match: Text match score. frosmo_affinity: Measure of visitor affinity. The higher the value, the higher the affinity score and the greater the visitor's affinity for the item. If you use this field, you must define a cookieId. frosmo_boost: Total combined boosting score. The score includes the boosting defined for the item in the Frosmo Control Panel and any custom boosting defined in the basic search setup. note The API automatically adds frosmo_boost:desc at the end of the sortBy value if the value contains one or two fields and if neither field is frosmo_boost. Boosting example 1 # Original request sortBy=text_match:desc # Actual request sortBy=text_match:desc,frosmo_boost:desc Boosting example 2 # Original request sortBy=text_match:desc,frosmo_affinity:desc # Actual request sortBy=text_match:desc,frosmo_affinity:desc,frosmo_boost:desc Boosting example 3 # Original request sortBy=text_match:desc,frosmo_affinity:desc,price:asc # Actual request sortBy=text_match:desc,frosmo_affinity:desc,price:asc Boosting example 4 # Original request sortBy=frosmo_boost:desc # Actual request sortBy=frosmo_boost:desc note If the frosmo_boost field is not included in the request, either explicitly or automatically, the API ignores boosting that impacts an item's boosting score, including boosting rules that target all searches. frosmo_conversions: Total number of conversions during the past month. The more conversions, the more popular the item. The platform adds this field only to the most popular items whose conversion count exceeds a threshold value. frosmo_views: Total number of views during the past month. The more views, the more popular the item. The platform adds this field only to the most popular items whose view count exceeds a threshold value. <item_attribute_name>: Item attribute. You can sort by any numeric attribute indexed by the search engine. You can also sort by any indexed string or string array attribute for which sorting is enabled. The indexed and sortable attributes are defined in the basic search setup. note To sort by item ID, use _id: sortBy=_id:asc The possible sort order values are: asc: Sort in ascending order. desc: Sort in descending order. The following example sorts the search results first by affinity, then by text match score, and finally by total item boosting score (as the API automatically adds frosmo_boost:desc at the end). Example sortBy=frosmo_affinity:desc,text_match:desc How the sorting works The API uses the sorting fields as tiebreakers: If multiple items have the same value for the first field, the API sorts the items based on the second field. If you have not defined a second field, the API sorts the items in descending order by text match score. If the items have the same text match score, the API sorts the items randomly. If the items have the same value for the second field, the API sorts the items based on the third field. If you have not defined a third field, the API sorts the items in descending order by text match score. If the items have the same text match score, the API sorts the items randomly. If the items have the same value for the third field, the API sorts the items randomly.	String	Optional	# Sort by text match score sortBy=text_match:desc # Sort by text match score and low price sortBy=text_match:desc,price:asc # Sort by popularity (most converted and viewed) sortBy=frosmo_conversions:desc,frosmo_views:desc # Sort by visitor affinity sortBy=frosmo_affinity:desc
includeFields	List of item attributes whose data to include in the search results. The API returns the attribute data by item in the documents array of a successful response. note If you define this field, the perPage parameter is limited to a maximum value of 250. note To include IDs in the item data, use _id: includeFields=_id info The API always returns matching item IDs in the ids array of a successful response regardless of whether or how you define includeFields. Usage The basic syntax is: includeFields=attribute_name_1,...,attribute_name_n You can return any item attribute indexed by the search engine. The indexed attributes are defined in the site's basic search setup. You can return multiple attributes, up to all the attributes indexed for the site. Separate multiple attributes with a comma. If you omit this parameter, the search returns only item IDs.	String	Optional	# Return one attribute includeFields=name # Return multiple attributes includeFields=name,brand,price

Request examples

Example: Retrieve items that match a search term

GET https://inpref.com/search?origin=shop_company_com&
    q=boots

Example: Retrieve items that match a search term and a filter

GET https://inpref.com/search?origin=shop_company_com&
    q=boots&
    filter=brand:Lumberland

Example: Retrieve items that match a filter

GET https://inpref.com/search?origin=shop_company_com&
    filter=brand:Lumberland||type:shoes

Example: Retrieve items that match a search term and sort by affinity

GET https://inpref.com/search?origin=shop_company_com&
    cookieId=dsr77t.kstzihlx&
    q=boots&
    sortBy=frosmo_affinity:desc

Example: Retrieve items that match a search term, and include name and brand in the response

GET https://inpref.com/search?origin=shop_company_com&
    q=boots&
    includeFields=name,brand

Example: Retrieve paginated results at maximum page size

# Page 1
GET https://inpref.com/search?origin=shop_company_com&
    page=1&
    perPage=2000&
    q=boots

# Page 2
GET https://inpref.com/search?origin=shop_company_com&
    page=2&
    perPage=2000&
    q=boots

# Page 3
GET https://inpref.com/search?origin=shop_company_com&
    page=3&
    perPage=2000&
    q=boots

# ...

Responses

Success

On a success, the Search API returns the search results in a JSON object. The response status code is 200.

The response object contains the following properties:

• found: Total number of matching items. This can be greater than perPage.

• ids: Array of matching item IDs.

• documents: Array of matching items. Each item is an object that contains the item attributes defined in the includeFields parameter. If the includeFields parameter is empty or undefined, the array is empty.

The results (ids and documents) are sorted using the logic defined in the sortBy parameter or, if the parameter is empty or undefined, using the default sorting rules defined in the site's basic search setup. The number of results is limited by perPage.

Request (example)

GET https://inpref.com/search?origin=shop_company_com&
    q=boots&
    includeFields=:_id,name

Response (example)

{
    "found": 283,
    "ids": [
        "58585",
        "13277",
        "31981",
        ...
    ],
    "documents": [
        {
            "_id": "58585",
            "name": "Casual Engineer Boots"
        },
        {
            "_id": "13277",
            "name": "Comfort Logger Boots"
        },
        {
            "_id": "31981",
            "name": "Lace-up Leather Boots"
        },
        ...
    ]
}

Error

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

Search API error messages

Error message	Description	Solution
parameter 'origin' is missing	The origin query parameter is missing from the request URL or its value is empty.	Make sure the origin query parameter is properly defined.
forbidden	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.
non integer query parameter 'perPage'	The value of the perPage query parameter is not an integer.	Provide a positive integer as the value for the perPage query parameter.
parameter 'perPage' must be >= 1 parameter 'perPage' must be <= 2000	The value of the perPage query parameter is outside the allowed integer range.	Provide a positive integer that respects the minimum and maximum values for the perPage query parameter.
Could not find a filter field named `<attribute_name>` in the schema.	<attribute_name> is not a valid attribute for filtering the search results.	Provide the name of an attribute that can be used for filtering the search results. Make sure the name is correctly spelled. note The attributes that you can use for filtering depend on the site's basic search setup.
Parameter `sort_by` is malformed.	The value of the sortBy query parameter is invalid.	Make sure the value of the sortBy query parameter follows the correct syntax.
Could not find a field named `<field_name>` in the schema for sorting.	<field_name> is not a valid field for sorting the search results.	Provide the name of field that can be used for sorting the search results. Make sure the name is correctly spelled.
Order for field `<field_name>` should be either ASC or DESC.	The sort order value for the <field_name> field is invalid.	Use one of the allowed sort order values: <field_name>:asc: Sort in ascending order. <field_name>:desc: Sort in descending order.