API Reference / REST API / Query Suggestions REST API
Jun. 10, 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.

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:

Note: https://query-suggestions.algolia.com is an alias of https://query-suggestions.us.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 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}/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 single 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.

Errors:

  • 401: Unauthorized
  • 500: Internal Error

Example:

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

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:

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

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

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:

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

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

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