API reference / Query Suggestions API

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:

Request format

To authenticate your API requests, add these headers:

  • X-Algolia-Application-Id: the ID of your Algolia application
  • X-Algolia-API-Key: an API key

You can find your application ID and manage your API keys in the Algolia dashboard.

ACL

For creating, updating, or deleting Query Suggestions configurations, the X-Algolia-API-Key needs to have the editSettings ACL.

For getting and listing Query Suggestions configurations, getting a configuration status, and getting a log file, X-Algolia-API-Key needs to have the settings ACL.

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

A

Path: /1/configs
HTTP Verb: POST
Required API Key: any key with the settings ACL

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: 5
Optional

Minimum number of hits (e.g., matching records in the source index) to generate a suggestions. The minimum value is 1.
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:

A

Copy 
1
2
3
4
5
6
7
8
9
10
11

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 
1
2
3
4

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

Update a configuration

A

Path: /1/configs/{indexName}
HTTP Verb: PUT
Required API Key: any key with the editSettings ACL

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: 5
Optional

Minimum number of hits (e.g., matching records in the source index) to generate a suggestions. The minimum value is 1.
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:

A

Copy 
1
2
3
4
5
6
7
8
9
10
11

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 
1
2
3
4

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

Delete a configuration

A

Path: /1/configs/{indexName}
HTTP Verb: DELETE
Required API Key: any key with the editSettings ACL

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:

A

Copy 
1
2
3
4
5

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 
1
2
3
4

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

Get a single configuration

A

Path: /1/configs/{indexName}
HTTP Verb: GET
Required API Key: any key with the settings ACL

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:

A

Copy 
1
2
3
4
5

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 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "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

A

Path: /1/configs/{indexName}/status
HTTP Verb: GET
Required API Key: any key with the settings ACL

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:

A

Copy 
1
2
3
4
5

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 
1
2
3
4
5

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

Get all configurations

A

Path: /1/configs
HTTP Verb: GET
Required API Key: any key with the settings ACL

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:

A

Copy 
1
2
3
4
5

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 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

[
  {
    "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

A

Path: /1/logs/{indexName}
HTTP Verb: GET
Required API Key: any key with the settings ACL

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:

A

Copy 
1
2
3
4
5

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 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

[
  {
    "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?