Skip to main content

Autocomplete

Autocomplete Queries​

curl -X GET -H "Content-Type: application/json" \
"https://ac.cnstrc.com/autocomplete/[query]?key=[your API key]" \
"&filters[group_id]=123"
info

The above command returns a 200 Success response on success.

You can try out an autocomplete query on your dataset by typing the following URL into a web browser: https://ac.cnstrc.com/autocomplete/[query]?key=[your API key], replacing [query] with the query you'd like to make, and [your API key] with your API key.

Want to try it right now? You can search for labrador from our demo list of dog breeds here.

When implementing our autocomplete on a website, we recommend most customers use our Javascript (front-end) client. For other uses, please check out the list of SDKs we have.

HTTP Request​

GET https://ac.cnstrc.com/autocomplete/[query]?key=[your API key]

Parameters​

ParameterRequired?Description
queryYesThe URL-encoded autocomplete query.
keyYesThe key for the autocomplete you would like to query.
num_resultsNoThe number of results to return across all sections in the autocomplete (rounded down if num_results isn't divisible by the number of autocomplete sections). The maximum value is 50.
num_results_[section_name]NoThe number of results to return from autocomplete section section_name. section_name is URL encoded, so 3 results from section Dog Breeds would be num_results_Dog%20Breeds=3. A single request can include several of these parameters to specify the number of results to return from multiple sections. The maximum value is 50.
filtersNoA filter to be applied to autocomplete requests, so that only results that have that filter are returned. You can use facets or group_ids as filters. Autosuggest calls allow a maximum of one filter to be applied.
variations_mapn/aMapping configuration to return item variations data in a specific format. It is a JSON string where you can list the only attributes of item variation you need. It's also possible to group variations and aggregate their fields in some way. For example, you can ask for min and max prices across all item variations, return only the first image URL instead of all variation pictures, or get only a list of all possible colors and no other data. The feature can be useful to build item swatches right in your autocomplete results view or reduce response size to speed up render of the results. More details, including the exact schema for this value can be found here

Autocomplete Responses: Overview​

Krestor's autocomplete returns easy-to-process JSON responses.

Response structure: Sections​

Autocomplete responses are returned in discrete sections. Most typically there will be two such sections: Products and Search Suggestions. The purpose of these is as follows:

  • Products These are the items you sell and want to facilitate discovery for. Krestor's autosuggest allows users to jump right to the product they're interested in within milliseconds -- even with millions of catalog items.
  • Search Suggestions These are suggested search terms users can choose to search. Suggested search terms help users discover your catalog and better qualify their search by encouraging more specific, well-formed queries. Customers can generate and maintain Search Suggestions themselves, but most customers rely on Krestor's optimization and suggestion algorithms to generate and optimize the list of search suggestions.

These are the typical sections, but we also support suggesting category page results, store locations, etc. You can work with our Implementation Engineering team to define and optimize other entities you'd like to search within.

{
  "request": {
    ...
  },
  "response": {
    "sections": {
      "Search Suggestions": [
        ...
      ],
      "Products": [
        ...
      ]
    }
  }
}

Response structure: Request object​

Within each autocomplete response JSON, we include data on the submitted request.

Values with a default as well as the autocompleted term will always be returned. Otherwise, only given 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 'https://ac.cnstrc.com/autocomplete/bird%20food?key=[your_key]' we might get the following request info:

{
  "request": {
    "term": "bird food"
  },
  "response": {
    "sections": {
      ...
    }
  }
}

Response structure: Value & matched terms​

All autosuggest responses will include at least two fields:

  • matched_terms This indicates the terms that were matched within each item returned and is useful for implementing highlighting of match values. In the example to the right, imagine the user has typed doge food, Krestor resolves this to the spell corrected dog food and returns the matched terms to permit match highlighting even for misspellings.
  • value This is the primary field searched and displayed to the user and generally corresponds to item_name you provided when adding the item.
{
  "sections": {
    "Search Suggestions": [
      {
        "data": [
          ...
        ],
        "is_slotted": false,
        "labels": {},
        "matched_terms": [
          "dog food"
        ],
        "value": "mccormick's farmstand dog food"
      },
      ...
    ],
    "Products": [
      {
        "data": [
          ...
        ],
        "is_slotted": true,
        "labels": {
          "is_sponsored": true
        },
        "matched_terms": [
          "dog food"
        ],
        "value": "McCormick's Farmstand Small Bites Potato & Duck Formula Dog Food"
      },
      ...
    ]
  }
}

Autocomplete Responses: Search Suggestions​

Search Suggestions and Products response structures are broadly similar, but reviewing them individually is helpful as certain fields are more common or bear different significance depending on their location.

Search Suggestions: Groups​

One of the most important roles of autosuggest is to clarify ambiguous queries. By leveraging Krestor's category suggestions, we can help users clarify their intent. Users often make over-broad searches like shirts which may be men's or women's shirts or juniors shirts.

User types shirt

Autosuggest returns: Shirts in Women's Clothing in Men's Clothing in Juniors' Clothing

Each Search Suggestion is returned with a data array containing Krestor's ordered recommendations for group suggestions.

The contents of this array are configurable, but most often include the following fields:

  • display_name The name you would like displayed for the group in question.
  • group_id An alphanumeric identifier your company uses to uniquely identify the particular group entity.
  • path The hierarchy of group_ids within which the group exists. In the example to the right, 95 would be the parent Clothing category.
{
  "sections": {
    "Search Suggestions": [
      {
        "data": {
          "groups": [
            {
              "display_name": "Women's Clothing",
              "group_id": "394",
              "path": "/95/394/"
            },
            {
              "display_name": "Men's Clothing",
              "group_id": "339",
              "path": "/95/339/"
            },
            {
              "display_name": "Juniors' Clothing",
              "group_id": "455",
              "path": "/95/455/"
            }
          ],
        },
        "is_slotted": false,
        "labels": {},
        "matched_terms": [
          "dog"
        ],
        "value": "Natural Balance Small Bites Potato & Duck Formula Dog Food"
      }
    ],
    "Products": [
      ...
    ]
  }
}

Autocomplete Responses: Products​

Products are typically the main items a company is interested in promoting so typically have the most metadata associated with them.

Products: Common fields​

In addition to always returning value, is_slotted, labels and matched_terms, Krestor can display any data that's been uploaded for the items in question, which is returned in a data object. We'll go over a typical subset below:

Additional Data (may not be present)

  • data.url The URL where the item can be viewed or purchased.
  • data.id An ID that uniquely identifies the item within the company.
  • data.image_url An image of the item in question.
  • data.groups The category(ies) an item belongs to. We'll review these in greater detail below.
  • data.facets The facet(s) an item is associated with. We'll review these in greater detail below.

The autocomplete response format for product data matches the search response format.

System Status​

To check the health of the system that serves /autocomplete requests, you can issue a GET /status/product/autocomplete, as shown below:

Check if the 'autocomplete' system is healthy
curl -X GET "https://ac.cnstrc.com/status/product/autocomplete"

A healthy system will reply with {"message": "OK"}