Search Results

Constructor.io's search engine returns easy-to-process JSON responses, including both data on what was requested and the response for your query.

The response format is as follows:

Result structure overview#

{
"request": {
...
}
"response": {
"facets": [
...
],
"groups": [
...
],
"sort_options": [
...
],
"results": [
...
],
"total_num_results": 454
}
}

Sections

Constructor.io defaults to provide search results only for the Products section of a customer's search index.

Groups, facets, sort_options, results

Within each result section, there are four arrays returned, and a summary of the total count of results within that section total_num_results.

The four groups are described below:

  • facets Summary of all the facets associated with the items returned by the search query.
  • groups Summary of all the groups associated with the items returned by the search query, information about these groups and the count of items within each group.
  • sort_options Available options for determining the order of items in the results array.
  • results The actual results Constructor.io returned for the search query.

Search: Request object#

To simplify the interpretation of results and pairing a given request with the relevant response, the search endpoint will 'parrot back' the request that was understood by the search service in the request object.

Values with a default (ie. page, num_results_per_page, section) will always be returned. Otherwise, only the provided parameters will be returned within the request data.

We intentionally omit the following parameters from the response request object for privacy reasons: key, c, i, ui, s, _dt

Example: For the query '/search/food?key=[your API key]&num_results_per_page=75&filter['animal_type']=bird' we might get the following request info:

{
"request": {
"page": 1,
"num_results_per_page": 75,
"term": "food",
"section": "Products",
"sort_by": "relevance",
"sort_order": "descending",
"fmt_options": {
"groups_max_depth": 1,
"groups_start": "current"
},
"filters": {
"animal_type": ["bird"]
},
"filter_match_types": {
"animal_type": "any"
}
},
"response": {
"facets": [
...
],
"groups": [
...
],
"sort_options": [
...
],
"results": [
...
]
}
}