API reference / Query Suggestions API

Mar. 01, 2023

Query Suggestions API

The Query Suggestions API allows you to change the configuration of your Query Suggestions index. The API calls don’t modify the data in the index.

Since Query Suggestions usually only require a one-time setup, it’s recommended that you use the dashboard instead of this API. The dashboard gives you the same detailed access as the API but walks you through the configuration steps in an organized way. Any updates are usually minor in scope and easier to manage from the dashboard.

Guides Query Suggestions with InstantSearch

Query Suggestions with the Autocomplete library

Domain

Reach the Query Suggestions API from a region-specific domain that matches the region where your analytics data is stored and processed. It’s one of:

United States: https://query-suggestions.us.algolia.com
Europe: https://query-suggestions.eu.algolia.com

Request format

The API requires the application ID and API key to be passed in the following HTTP headers:

X-Algolia-Application-Id: the application ID.
X-Algolia-API-Key: the admin API key for a given application ID.

Response format

The response format for all requests is a JSON object.

Whether a request succeeded is indicated by the HTTP status code:

200 indicates success
400, 401, 403, 404, 422, or 500 indicates failure. The JSON response body contains a message you can inspect for debugging purposes.

Query Suggestions

Quick reference

Verb	Path	Method
POST	/1/configs	Create a configuration
PUT	/1/configs/`{indexName}`	Update a configuration
DELETE	/1/configs/`{indexName}`	Delete a configuration
GET	/1/configs/`{indexName}`	Get a single configuration
GET	/1/configs/`{indexName}`/status	Get configuration status
GET	/1/configs	Get all configurations
GET	/1/logs/`{indexName}`	Get a log file

Create a configuration

Path: /1/configs
HTTP Verb: POST

Description:

Create a configuration of a Query Suggestions index. There’s a limit of 100 configurations per application.

Parameters:

Parameter	Description
`indexName`	type: string Required Index name to target.
`sourceIndices`	type: list of sourceIndex Required List of source indices used to generate a Query Suggestions index. [ { "indexName": "indexName", // optional "analyticsTags": [...], "facets": [...], "minHits": 3, "minLetters": 3, "generate": [...], "external": [...], }, ... ]
`languages`	type: list Optional Deduplicate singular and plural suggestions. For example, let’s say your index contains English content, and that two suggestions “shoe” and “shoes” end up in your Query Suggestions index. If the English language is configured, only the most popular of those two suggestions would remain.
`exclude`	type: list Optional List of words and patterns to exclude from the Query Suggestions index.
`allowSpecialCharacters`	type: boolean default: false Optional Allow suggestion containing special characters and diacritics.

sourceIndex

Parameter	Description
`indexName`	type: string Required Source index name.
`analyticsTags`	type: list of strings default: [] Optional List of analytics tags to filter the popular searches per tag.
`facets`	type: list of objects default: [] Optional List of facets to define as categories for the query suggestions. [ { "attribute": "attributeName", "amount": 2 }, [...] ]
`minHits`	type: integer default: no minimum Optional Minimum number of hits (e.g., matching records in the source index) to generate a suggestions.
`minLetters`	type: integer default: no minimum Optional Minimum number of required letters for a suggestion to remain.
`generate`	type: list default: [] Optional List of facet attributes used to generate Query Suggestions. The resulting suggestions are every combination of the facets in the nested list (e.g., `(facetA and facetB) and facetC`). [ ["facetA", "facetB"], ["facetC"] ]
`external`	type: list default: [] Optional List of external indices to use to generate custom Query Suggestions.

Errors:

400: BadRequest
401: Unauthorized
403: StatusForbidden
422: StatusUnprocessableEntity
500: Internal Error

Example:

Copy
curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --compressed \
     -d '{
        "indexName": "product_qs",
        "sourceIndices": [{
          "indexName": "product"
        }]
      }' \
    "https://query-suggestions.us.algolia.com/1/configs"

When the query is successful, the HTTP response is a 200 OK and returns a success message:

Copy
{
  "status": 200,
  "message": "Success"
}

Update a configuration

Path: /1/configs/{indexName}
HTTP Verb: PUT

Description:

Update the configuration of a Query Suggestions index.

This endpoint used to let you create new Query Suggestions configurations. This is now deprecated in favor of the POST /configs endpoint.

Parameters:

Parameter	Description
`indexName`	type: string Required Index name to target.
`sourceIndices`	type: list of sourceIndex Required List of source indices to use to generate query suggestions. [ { "indexName": "indexName", // optional "analyticsTags": [...], "facets": [...], "minHits": 3, "minLetters": 3, "generate": [...], "external": [...], }, ... ]
`languages`	type: list Optional Deduplicate singular and plural suggestions. For example, let’s say your index contains English content, and that two suggestions “shoe” and “shoes” end up in your Query Suggestions index. If the English language is configured, only the most popular of those two suggestions would remain.
`exclude`	type: list Optional List of words and patterns that will be excluded from the query suggestions.
`allowSpecialCharacters`	type: boolean default: false Optional Allow suggestion containing special characters and diacritics.

sourceIndex

Parameter	Description
`indexName`	type: string Required Source index name.
`analyticsTags`	type: list of strings default: [] Optional List of analytics tags to filter the popular searches per tag.
`facets`	type: list of objects default: [] Optional List of facets to define as categories for the query suggestions. [ { "attribute": "attributeName", "amount": 2 }, [...] ]
`minHits`	type: integer default: no minimum Optional Minimum number of hits (e.g., matching records in the source index) to generate a suggestions.
`minLetters`	type: integer default: no minimum Optional Minimum number of required letters for a suggestion to remain.
`generate`	type: list default: [] Optional List of facet attributes used to generate query suggestions. The resulting suggestions will be every combination of the facets in the nested list (e.g., `(facetA and facetB) and facetC`). [ ["facetA", "facetB"], ["facetC"] ]
`external`	type: list default: [] Optional List of external indices to use to generate custom query suggestions.

Errors:

401: Unauthorized
500: Internal Error

Example:

Copy
curl -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --compressed \
     -d '{
        "indexName": "product_qs",
        "sourceIndices": [{
          "indexName": "product"
        }]
      }' \
    "https://query-suggestions.us.algolia.com/1/configs/product_qs"

When the query is successful, the HTTP response is a 200 OK and returns a success message:

Copy
{
  "status": 200,
  "message": "Success"
}

Delete a configuration

Path: /1/configs/{indexName}
HTTP Verb: DELETE

Description:

Delete a configuration of a Query Suggestion’s index.

By deleting a configuraton, you stop all updates to the underlying query suggestion index.

Note that when doing this, the underlying index does not change - existing suggestions remain untouched.

Parameters:

Parameter	Description
`indexName`	type: string Required Index name to target.

Errors:

401: Unauthorized
500: Internal Error

Example:

Copy
curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --compressed \
    "https://query-suggestions.us.algolia.com/1/configs/product_qs"

When the query is successful, the HTTP response is a 200 OK and returns a success message:

Copy
{
  "status": 200,
  "message": "Success"
}

Get a single configuration

Path: /1/configs/{indexName}
HTTP Verb: GET

Description:

Get the configuration of a single Query Suggestions index.

Parameters:

Parameter	Description
`indexName`	type: string Required Index name to target.

Errors:

400: Bad Method
401: Unauthorized
404: Not Found
500: Internal Error

Example:

Copy
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --compressed \
    "https://query-suggestions.us.algolia.com/1/configs/product_query_suggestions"

When the query is successful, the HTTP response is a 200 OK and returns the full configuration settings for the targeted Query Suggestions index:

Copy
{
  "indexName": "product_query_suggestions",
  "sourceIndices": [{
    "indexName": "product",
    "replicas": false,
    "analyticsTags": [],
    "facets": [],
    "minHit": 4,
    "minLetters": 5,
    "generate": [["brand"], ["brand", "category"]],
    "external": []
  }],
  "exclude": [""],
  "languages": ["us", "nl"],
  "allowSpecialCharacters": false
}

Get configuration status

Path: /1/configs/{indexName}/status
HTTP Verb: GET

Description:

Get the status of a Query Suggestion’s index.

The status includes whether the Query Suggestions index is currently in the process of being built, and the last build time.

Parameters:

Parameter	Description
`indexName`	type: string Required Index name to target.

Errors:

401: Unauthorized
500: Internal Error

Example:

Copy
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --compressed \
    "https://query-suggestions.us.algolia.com/1/configs/product_qs/status"

When the query is successful, the HTTP response is a 200 OK and returns the current status:

Copy
{
  "indexName": "product_qs",
  "isRunning": true,
  "lastBuiltAt": "2019-02-27T15:03:57.790Z"
}

Get all configurations

Path: /1/configs
HTTP Verb: GET

Description:

Get all the configurations of Query Suggestions.

For each index, you get a block of JSON with a list of its configuration settings.

Errors:

401: Unauthorized
422: Unprocessable Entity
500: Internal Error

Example:

Copy
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --compressed \
    "https://query-suggestions.us.algolia.com/1/configs"

When the query is successful, the HTTP response is a 200 OK and returns the full configuration settings for each Query Suggestion index:

Copy
[
  {
    "indexName": "product_query_suggestions",
    "sourceIndices": [{
      "indexName": "product",
      "replicas": false,
      "analyticsTags": [],
      "facets": [],
      "minHit": 4,
      "minLetters": 5,
      "generate": [["brand"], ["brand", "category"]],
      "external": []
    }],
    "exclude": [""],
    "languages": ["us", "nl"]
    "allowSpecialCharacters": false
  }
]

Get a log file

Path: /1/logs/{indexName}
HTTP Verb: GET

Description:

Get the log file of the last build of a single Query Suggestion index.

Parameters:

Parameter	Description
`indexName`	type: string Required Index name to target.

Errors:

401: Unauthorized
404: Not Found
500: Internal Error

Example:

Copy
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     --compressed \
    "https://query-suggestions.us.algolia.com/1/logs/product_qs"

When the query is successful, the HTTP response is a 200 OK and returns a content of the log file in JSON Lines format. Each line contains the following attributes:

timestamp - date and time of creation of the record
level - type of the record, can be one of three values (INFO, SKIP or ERROR)
message - detailed description of what happened
contextLevel - indicates the hierarchy of the records. For example, a record with contextLevel=1 belongs to a preceding record with contextLevel=0.

Copy
[
  {
    "timestamp": "2019-05-01T00:00:00Z",
    "level": "INFO",
    "message": "info with params",
    "contextLevel": 0
  },
  {
    "timestamp": "2019-05-01T00:00:00Z",
    "level": "ERROR",
    "message": "error with params",
    "contextLevel": 0
  },
  {
    "timestamp": "2019-05-01T00:00:00Z",
    "level": "SKIP",
    "message": "skip with params",
    "contextLevel": 0
  },
  {
    "timestamp": "2019-05-01T00:00:00Z",
    "level": "INFO",
    "message": "start context 1",
    "contextLevel": 0
  },
  {
    "timestamp": "2019-05-01T00:00:00Z",
    "level": "INFO",
    "message": "info context 1",
    "contextLevel": 1
  },
  {
    "timestamp": "2019-05-01T00:00:00Z",
    "level": "INFO",
    "message": "start context 2",
    "contextLevel": 1
  },
  {
    "timestamp": "2019-05-01T00:00:00Z",
    "level": "INFO",
    "message": "info context 2",
    "contextLevel": 2
  }
]

Did you find this page helpful?