Search Queries

curl -X GET -H "Content-Type: application/json" \
"[query]?key=[your API key]"
search the dog breed data set for "sheep", show 2 results per page and the 3rd page of results.
curl -X GET -H "Content-Type: application/json" \
search for figs, but only return results within the cookies category.
curl -X GET -H "Content-Type: application/json" \
search cashmere dog sweaters, but show the cheapest ones first
curl -X GET -H "Content-Type: application/json" \
pass additional user segments to take into account in redirect rule evaluation
curl -X GET -H "Content-Type: application/json" \
"[query]?key=[your API key]&us=<user-segment#1>&us=<user-segment#2>"

The above command returns a 200 Success response on success.

HTTP Request#

GET[query]?key=[your API key]&filters[group_id]=123&filters[Color]=Brown&filters[Color]=White&filters[Price]=100-200&fmt_options[groups_start]=current&fmt_options[groups_max_depth]=1

page1The page number of the results
num_results_per_page20The number of results per page to return
numresults_per_page[section]n/aThe number of results per page for a given section (when a dataset has multiple sections). Results from sections that were not included in the request will not be returned at all.
filters[filter_name]=filter_valuen/aAny number of criteria by which you'd like to narrow the result set. This might be by color, size, or category (group) an item belongs to. Facets (uploaded through the Add an Item API) and group ids can be used as filters. Filters with the same key are ORed together, while filters with different keys are ANDed together by default. If filter_value has the form <min>-<max>, it's interpreted as a range (e.g: filters[Price]=100-200 will match all items with Price from 100 to 200).
fmt_options[groups_start]currentEither current or top. Specifies the top-level group that should be returned in the response. If a group_id is provided in filters and the value for this option is current, we'll return groups starting from the currently selected one. If the value is top, we will always start returning groups from the root category in the hierarchy, regardless of which one is selected
fmt_options[groups_max_depth]1Maximum depth of the group hierarchy that should be included in the response.
sort_byrelevanceThe criteria by which search results should be sorted. The default value relevance sorts by's relevance & personalization algorithms and is reserved. Please reach out to to define alternate sort criteria.
sort_orderdescendingEither descending or ascending. The sort order by which search results should be sorted. Only valid in conjunction with sort_by.
usNoneUser segment is a client context value (such as platform, location, etc.) that is used to evaluate redirect or refined tag rules. You can supply multiple segments by passing multiple us arguments.