API Reference / REST API / Query Suggestions REST API

Query Suggestions REST API

Overview

The Query Suggestions API gives you direct access to the configuration that lies behind your Query Suggestions index. These API calls do not touch your Query Suggestions index: their whole purpose and impact is on the configuration of the indices, not the indices themselves.

For most customers, we suggest using our dashboard instead of this API. The dashboard not only gives you the same level of detailed access as the API, but it is also designed to walk you through the configuration steps in a logical and organized way. Query Suggestions usually only requires a one-time setup, then runs on its own. Updates are small, therefore easier to manage from the dashboard.

Domain

The Query Suggestions API can be reached from multiple domains, each specific to a region. You should use the domain that matches the region where your analytics data is stored and processed. You can use one of the following domains:

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 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. A 2xx status code indicates success, whereas a 4xx or 5xx status code indicates failure. When a request fails, the response body is still JSON, but always contains the field message which 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

Description:

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

Parameters:

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

De-duplicate 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

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:

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

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:

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

De-duplicate 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

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:

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

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:

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

Description:

Get the configuration of a single Query Suggestions index.

Parameters:

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

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:

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

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

Description:

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

Parameters:

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?