API Reference / REST API / Query Suggestions REST API
Nov. 28, 2019

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.

The Query Suggestions REST API is only available to Enterprise customers.

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

PUT

/configs/{indexName}

Create or update a configuration

DELETE

/configs/{indexName}

Delete a configuration

GET

/configs/{indexName}

Get a single configuration

GET

/configs/{indexName}/status

Get configuration status

GET

/configs

Get all configurations

GET

/logs/{indexName}

Get a log file

Create or update a configuration

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

Description:
Create or update the configuration of a Query Suggestion index.

You should use this when you want to create a new configuration, or update some or all the configuration settings for a Query Suggestion index.

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

List of languages used for plural normalization (e.g., us, nl).

exclude
type: list
Optional

List of words and patterns that will be excluded from the query suggestions.

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 (i.e., matching records) to generate a suggestions.

minLetters
type: integer
default: no minimum
Optional

Minumum number of letters as part of the suggestion.

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:

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:

1
2
3
4
{
  "status": 200,
  "message": "Success"
}

Delete a configuration

Path: /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:

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:

1
2
3
4
{
  "status": 200,
  "message": "Success"
}

Get a single configuration

Path: /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:

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "indexName": "product_query_suggestions",
  "sourceIndices": [{
    "indexName": "product",
    "replicas": false,
    "analyticsTags": [],
    "facets": [],
    "minHit": 4,
    "minLetters: 5,
    "generate": [["brand"], ["brand", "category"]],
    "external": []
  }],
  "exclude": [""],
  "languages": ["us", "nl"]
}

Get configuration status

Path: /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:

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:

1
2
3
4
5
{
  "indexName": "product_qs",
  "isRunning": true,
  "lastBuiltAt": "2019-02-27T15:03:57.790Z"
}

Get all configurations

Path: /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:

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[
  {
    "indexName": "product_query_suggestions",
    "sourceIndices": [{
      "indexName": "product",
      "replicas": false,
      "analyticsTags": [],
      "facets": [],
      "minHit": 4,
      "minLetters: 5,
      "generate": [["brand"], ["brand", "category"]],
      "external": []
    }],
    "exclude": [""],
    "languages": ["us", "nl"]
  }
]

Get a log file

Path: /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:

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.
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?