Skip to main content

Searchability Configuration

The searchabilities API endpoints allow customers to customize the product data that are searched by Krestor, such as by making a brand or color facet searchable.

Scope

Merchants can configure the searchability statuses of each field of their product catalog.

Additional information​

Searchability configurations are refreshed during ingestion of product updates. Searchability configurations for fields which no longer exist in the catalog will be maintained in the event a field was removed from the feed momentarily by mistake. We support ingestion of nested searchabilities too and they are defined in the metadata fields of each product like so:

{
  "facet": {
    "color": "red"
  }
}

facet.color would be a generated searchable configuration in this case.

Creating new searchabilities​

When new searchability configurations are defined based on a field being added to the catalog, they are disabled by default (i.e. their exact_searchable and fuzzy_searchable fields will be set to false).

When retrieved using the retrieve searchabilities endpoint, date of creation for the searchability configuration (when the field was first added to the catalog or the searchability configuration was created manually) will be reflected in the created_at field. On the other hand, updated_at field will reflect the date when searchability configuration was last modified.

Updates to search results​

When new searchability configurations are created or updated, they will only take effect when the search index is updated.

Searchability concepts​

  • Exact searchable Only queries with the same spelling and/or stemming as the value(s) in the field should be considered a match.
  • Fuzzy searchable Queries with misspelling or different stemming compared to the value(s) in the field should be considered a match.

Retrieve searchabilities​

This endpoint is used to retrieve all searchability configurations or configurations with a given name. If no searchability name is provided, all field searchability configurations will be returned. Otherwise, only the searchability configuration with the given name will be returned.

Retrieve searchabilities
curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v1/searchabilities?key=[your API key]"

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" "https://ac.cnstrc.com/v1/searchabilities/size?key=[your API key]"
info

The above command returns a 200 Success response on success.

HTTP Request​

GET https://ac.cnstrc.com/v1/searchabilities?key=[your API key]

GET https://ac.cnstrc.com/v1/searchabilities/[name]?key=[your API key]

GET https://ac.cnstrc.com/v1/searchabilities?key=[your API key]&filters[exact_searchable]=true

GET https://ac.cnstrc.com/v1/searchabilities?key=[your API key]&searchable=true&sort_by=[sort_by]&sort_order=[sort_order]

Response format​

{
  "searchabilities": [
    {
      "name": "on_sale",
      "fuzzy_searchable": true,
      "exact_searchable": false,
      "type": "string",
      "displayable": true,
      "hidden": false,
      "created_at": "2019-04-12T18:15:30",
      "updated_at": "2019-04-12T18:15:30"
    },
    {
      "name": "keywords",
      "fuzzy_searchable": false,
      "exact_searchable": true,
      "type": "string",
      "displayable": false,
      "hidden": false,
      "created_at": "2020-04-12T18:15:30",
      "updated_at": "2020-04-12T18:15:30"
    }
  ],
  "total_count": 2
}

Query Parameters​

ParameterRequired?Description
nameNoName of searchability field.
pageNoThe page number of the results. Defaults to 1. Can't be used together with 'offset'
offsetNoThe number of results to skip from the beginning. Can't be used together with 'page'
num_results_per_pageNoThe number of searchability configurations to return. Defaults to 100.
filtersNoFilters the results based on name, exact_searchable or fuzzy_searchable.
searchableNoRetrieves only results which are either exact_searchable or fuzzy_searchable.
sort_byNoThe criteria by which searchability configurations should be sorted. Defaults to no sorting. Valid criteria is name.
sort_orderNoEither descending or ascending. The sort order by which searchability configurations should be sorted. Only valid in conjunction with sort_by.

Patch searchabilities​

Patching searchabilities will only change the searchability configurations that are specified in the request.

curl -X PATCH -H "Content-Type: application/json" \
  -d '{
        "searchabilities": [
          {
              "name": "style_id",
              "exact_searchable": "true"
          },
          {
              "name": "keywords",
              "fuzzy_searchable": "true"
          },
        ]
      }' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/searchabilities?key=[your index key]&section=Products"
info

The above command returns a 204 Success response on success. For simplicity sake, a 204 Success response will be returned even if the item already exists.

HTTP Request​

PATCH https://ac.cnstrc.com/v1/searchabilities?key=[your index key]&section=[section]

URL Parameters​

ParameterRequired?Description
sectionYesThe index section for which you'd like to patch searchability configurations (typically Products).

JSON Specifications​

Example JSON
{
  "searchabilities": [
    {
      "name": "keywords",
      "fuzzy_searchable": true,
      "exact_searchable": false,
      "displayable": false
      "hidden": false
    }
  ]
}

Parameters​

ParameterRequired?Description
displayableNoSpecifies whether the field is displayable in the response within the results array.
hiddenNoHides the field by default in the response but makes it available to retrieve via fmt_options[hidden_fields] parameter
exact_searchableNoTerms can be exact searchable (either exact_searchable or fuzzy_searchable fields can be true, but not both).
fuzzy_searchableNoTerms can be fuzzy searchable (either exact_searchable or fuzzy_searchable fields can be true, but not both).
nameYesName of searchability field.

Patch single searchability​

Patching a searchability will only change the searchability configuration for the field specified in the url.

curl -X PUT -H "Content-Type: application/json" \
  -d '{
        "displayable": "true",
        "hidden": "false",
        "exact_searchable": "true",
        "fuzzy_searchable": "false"
    }' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/searchabilities/keywords?key=[your index key]&section=Products"
info

The above command returns a 200 Success response on success.

HTTP Request​

PATCH https://ac.cnstrc.com/v1/searchabilities/[name]?key=[your index key]&section=[section]

URL Parameters​

ParameterRequired?Description
sectionYesThe index section for which you'd like to patch searchability configuration (typically Products).
nameYesName of searchability field.

JSON Specifications​

Example JSON
{
  "displayable": true,
  "hidden": false,
  "fuzzy_searchable": true,
  "exact_searchable": false
}

Parameters​

ParameterRequired?Description
displayableNoSpecifies whether the field is displayable in the response within the results array.
hiddenNoHides the field by default in the response but makes it available to retrieve via fmt_options[hidden_fields] parameter
exact_searchableNoTerms can be exact searchable (either exact_searchable or fuzzy_searchable fields can be true, but not both).
fuzzy_searchableNoTerms can be fuzzy searchable (either exact_searchable or fuzzy_searchable fields can be true, but not both).