Analytics API

Access to the Analytics REST API is available as part of the Premium plan or as the Enterprise add-on to other pricing plans.

The Analytics API and A/B test 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. View your analytics region.

The following domains are available:

• United States: https://analytics.us.algolia.com
• Europe (Germany): https://analytics.de.algolia.com

Note: https://analytics.algolia.com is an alias of https://analytics.us.algolia.com.

Authentication

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

• X-Algolia-Application-Id: the application ID.
• X-Algolia-API-Key: the authentication token.

Optionally, those parameters (case sensitive) are also accepted as URL parameters.

The X-Algolia-API-Key needs to have the analytics ACL.

To fetch click analytics metrics, you also need to have click analytics enabled on your account.

Errors

In case of errors (for example, authentication, validation, or rate limit errors), the API returns a payload in the following format:

1
2
3
4
{
  "status": 4xx,
  "message": "The error message"
}

Rate limiting

When making calls to the Analytics API, you are limited to 100 API calls per minute per app.

The following headers provide information about your current limit:

• X-RateLimit-Limit: The number of request allowed in a 60-second time period.
• X-RateLimit-Remaining: The number of requests remaining in the current time period.
• X-RateLimit-Reset: Unix timestamp of the next time period.

Query aggregation

Algolia’s search engine accepts queries at each keystroke. To ensure you have relevant analytics data, however, the series of keystrokes is aggregated to keep only the latest (final) user query That’s called “prefix” aggregation.

See the analytics implementation overview for more information about query aggregation.

Production usage

The Analytics API comes without a SLA.

You shouldn’t use this API for building user-facing experiences directly. Any production systems relying on this API should be implemented to be fault-tolerant.

See also Rate limiting.

Status of analytics

Quick reference

Path: /2/status
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns the latest update time of the analytics API for a given index. If the index has been recently created, or no search has been performed yet the updated time will be null.

Note: The Analytics API is updated every 5 minutes.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/status?index=${index name}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
{
   "updatedAt": "2018-12-01T00:10:00Z"
}

Search analytics

Quick reference

Path: /2/searches
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns top searches. Limited to the 1,000 most frequent ones. For each search, also returns the average number of hits returned.

If you set the clickAnalytics parameter to true, each search will also contain:

• the tracked searches count,
• the click count,
• the click-through rate (CTR),
• the conversion count,
• the conversion rate (CR),
• the average click position.

You can also order the results using orderBy and direction.

Tracked searches are searches for which the engine returned a queryID, so searches where you’ve set the clickAnalytics search parameter to true. This is different than the “count” attribute of the response, which includes tracked searches and searches where you didn’t enable the clickAnalytics search parameter.

If you set the revenueAnalytics parameter to true, the response will contain the above metrics, as well as:

• the add-to-cart count,
• the add-to-cart rate (ATCR),
• the purchase count,
• the purchase rate,
• a currencies map with revenue information on each currency.

It’s important to distinguish between 0% rates, and null values:

• If the CTR, CR, ATCR, and Purchase Rate and the average are all null, it means that Algolia didn’t receive any queries with the clickAnalytics search parameter set to true.
• If the CTR, CR, ATCR, and Purchase Rate are 0, it means Algolia didn’t receive any click and conversion events for the queries with the clickAnalytics search parameter set to true. The average is null until Algolia receives at least one event.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/searches?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "searches": [
    {
      "search": "q1",
      "count": 2,
      "nbHits": 1
    },
    {
      "search": "q0",
      "count": 1,
      "nbHits": 1
    },
    // {...}
  ]
}

With the clickAnalytics parameter set to true:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/searches?clickAnalytics=true&orderBy=clickThroughRate&direction=desc&index=${index name}&startDate=${startDate}&endDate=${endDate}"

Response:

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
{
  "searches": [
    {
      "search": "q0",
      "count": 3,
      "nbHits": 10,
      "clickThroughRate": 3,
      "averageClickPosition": 1,
      "conversionRate": 0.5,
      "trackedSearchCount": 2,
      "clickCount": 2,
      "conversionCount": 1
    },
    {
      "search": "q1",
      "count": 1,
      "nbHits": 10,
      "clickThroughRate": 2,
      "averageClickPosition": null,
      "conversionRate": null,
      "trackedSearchCount": 0,
      "clickCount": 0,
      "conversionCount": 0
    },
    // {...}
  ]
}

With the revenueAnalytics parameter set to true:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/searches?revenueAnalytics=true&orderBy=clickThroughRate&direction=desc&index=${index name}&startDate=${startDate}&endDate=${endDate}"

Response:

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
{
  "searches": [
    {
      "search": "q0",
      "count": 3,
      "nbHits": 10,
      "clickThroughRate": 3,
      "averageClickPosition": 1,
      "conversionRate": 0.5,
      "purchaseRate": 0.5,
      "addToCartRate": 0.5,
      "trackedSearchCount": 2,
      "clickCount": 2,
      "conversionCount": 1,
      "purchaseCount": 1,
      "addToCartCount": 1, 
      "currencies": {
        "USD": {
          "currency": "USD",
          "revenue": 1201.3
        }
      }
    },
    {
      "search": "q1",
      "count": 1,
      "nbHits": 10,
      "clickThroughRate": 2,
      "averageClickPosition": null,
      "conversionRate": null,
      "purchaseRate": null,
      "addToCartRate": null,
      "trackedSearchCount": 0,
      "clickCount": 0,
      "conversionCount": 0,
      "purchaseCount": 0,
      "addToCartCount": 0
    },
    // {...}
  ]
}

Path: /2/searches/count
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns the number of total searches across the given time range. The endpoint returns a value for the complete given time range, as well as a value per day.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/searches/count?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
8
9
{
  "count": 3,
  "dates": [
    {"date": "2017-01-01", "count": 1},
    {"date": "2017-01-02", "count": 0},
    {"date": "2017-01-03", "count": 2},
    // {...}
  ]
}

Path: /2/searches/noResults
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns top searches that didn’t return any results. Limited to the 1000 most frequent ones.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/searches/noResults?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
{
  "searches": [
    {"search": "q1", "count": 2, "withFilterCount": 1},
    {"search": "q0", "count": 1, "withFilterCount": 0},
    // {...}
  ]
}

Path: /2/searches/noClicks
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns top searches that didn’t lead to any clicks. Limited to the 1000 most frequent ones. For each search, also returns the average number of found hits.

The count attribute in the response only includes tracked searches. Tracked searches are searches for which the engine returned a queryID, so searches where you’ve set the clickAnalytics search parameter to true.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/searches/noClicks?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
{
  "searches": [
    {"search": "q1", "count": 2, "nbHits": 12},
    {"search": "q0", "count": 1, "nbHits": 3},
    // {...}
  ]
}

Path: /2/searches/noResultRate
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns the rate at which searches didn’t return any results. The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of searches and searches without results used to compute the rates.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/searches/noResultRate?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
8
9
10
11
{
  "rate": 0.42857142857142855,
  "count": 14,
  "noResultCount": 6,
  "dates": [
    {"date": "2017-01-01", "rate": 0.5,"count": 10, "noResultCount": 5},
    {"date": "2017-01-02", "rate": 0, "count": 0, "noResultCount": 0},
    {"date": "2017-01-03", "rate": 0.25, "count": 4, "noResultCount": 1},
    // {...}
  ]
}

Path: /2/searches/noClickRate
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns the rate at which tracked searches didn’t lead to any clicks. The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of tracked searches and tracked searches without clicks.

The count attribute in the response only includes tracked searches. Tracked searches are searches for which the engine returned a queryID, so searches where you’ve set the clickAnalytics search parameter to true.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/searches/noClickRate?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
8
9
10
11
{
  "rate": 0.42857142857142855,
  "count": 14,
  "noClickCount": 6,
  "dates": [
    {"date": "2017-01-01", "rate": 0.5,"count": 10, "noClickCount": 5},
    {"date": "2017-01-02", "rate": 0, "count": 0, "noClickCount": 0},
    {"date": "2017-01-03", "rate": 0.25, "count": 4, "noClickCount": 1},
    // {...}
  ]
}

Path: /2/hits
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns top hits. Limited to the 1000 most frequent ones.

If you set the clickAnalytics parameter to true, each hit will also contain:

• the tracked searches count,
• the click count,
• the click-through rate (CTR),
• the conversion count,
• the conversion rate (CR).

Tracked searches are searches for which the engine returned a queryID, so searches where you’ve set the clickAnalytics search parameter to true. This is different than the “count” attribute of the response, which includes tracked searches and searches where you didn’t enable the clickAnalytics search parameter.

If you set the revenueAnalytics parameter to true, the response will contain the above metrics, as well as:

• the add-to-cart count,
• the add-to-cart rate (ATCR),
• the purchase count,
• the purchase rate,
• a currencies map with revenue information on each currency.

It’s important to distinguish between 0% rates, and null values:

• If the CTR, CR, ATCR, and Purchase Rate and the average are all null, it means that Algolia didn’t receive any queries with the clickAnalytics search parameter set to true.
• If the CTR, CR, ATCR, and Purchase Rate are 0, it means Algolia didn’t receive any click and conversion events for the queries with the clickAnalytics search parameter set to true. The average is null until Algolia receives at least one event.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/hits?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "hits": [
    {
      "hit": "hit1",
      "count": 2
    },
    {
      "hit": "hit0",
      "count": 1
    },
    // {...}
  ]
}

With the clickAnalytics parameter set to true:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/hits?clickAnalytics=true&index=${index name}&startDate=${startDate}&endDate=${endDate}"

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "hits": [
    {
      "hit": "hit1",
      "count": 2,
      "clickThroughRate": 1,
      "conversionRate": 0.5,
      "trackedSearchCount": 2,
      "clickCount": 2,
      "conversionCount": 1
    },
    {
      "hit": "hit0",
      "count": 1,
      "clickThroughRate": null,
      "conversionRate": null,
      "trackedSearchCount": 0,
      "clickCount": 0,
      "conversionCount": 0
    },
    // {...}
  ]
}

With the revenueAnalytics parameter set to true:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/hits?revenueAnalytics=true&index=${index name}&startDate=${startDate}&endDate=${endDate}"

Response:

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
{
  "hits": [
    {
      "hit": "hit1",
      "count": 2,
      "clickThroughRate": 1,
      "conversionRate": 0.5,
      "purchaseRate": 0.5,
      "addToCartRate": 0.5,
      "trackedSearchCount": 2,
      "clickCount": 2,
      "conversionCount": 1,
      "purchaseCount": 1,
      "addToCartCount": 1,
      "currencies": {
        "USD": {
          "currency": "USD",
          "revenue": 1201.3
        }
      }
    },
    {
      "hit": "hit0",
      "count": 1,
      "clickThroughRate": null,
      "conversionRate": null,
      "purchaseRate": null,
      "addToCartRate": null,
      "trackedSearchCount": 0,
      "clickCount": 0,
      "conversionCount": 0,
      "purchaseCount": 0,
      "addToCartCount": 0
    },
    // {...}
  ]
}

Path: /2/hits?search=
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns top hits for the given search. Limited to the 1000 most frequent ones.

If you set the clickAnalytics parameter to true, each hit will also contain:

• the tracked searches count,
• the click count,
• the click-through rate (CTR),
• the conversion count,
• the conversion rate (CR).

Tracked searches are searches for which the engine returned a queryID, so searches where you’ve set the clickAnalytics search parameter to true. This is different than the “count” attribute of the response, which includes tracked searches and searches where you didn’t enable the clickAnalytics search parameter.

If you set the revenueAnalytics parameter to true, the response will contain the above metrics, as well as:

• the add-to-cart count,
• the add-to-cart rate (ATCR),
• the purchase count,
• the purchase rate,
• a currencies map with revenue information on each currency.

It’s important to distinguish between 0% rates, and null values:

• If the CTR, CR, ATCR, and Purchase Rate and the average are all null, it means that Algolia didn’t receive any queries with the clickAnalytics search parameter set to true.
• If the CTR, CR, ATCR, and Purchase Rate are 0, it means Algolia didn’t receive any click and conversion events for the queries with the clickAnalytics search parameter set to true. The average is null until Algolia receives at least one event.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/hits?search=${query term}&index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "hits": [
    {
      "hit": "hit1",
      "count": 2
    },
    {
      "hit": "hit0",
      "count": 1
    },
    // {...}
  ]
}

With the clickAnalytics parameter set to true:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/hits?clickAnalytics=true&search=${query term}&index=${index name}&startDate=${startDate}&endDate=${endDate}"

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "hits": [
    {
      "hit": "hit1",
      "count": 2,
      "clickThroughRate": 1,
      "conversionRate": 0.5,
      "trackedSearchCount": 2,
      "clickCount": 2,
      "conversionCount": 1
    },
    {
      "hit": "hit0",
      "count": 1,
      "clickThroughRate": null,
      "conversionRate": null,
      "trackedSearchCount": 0,
      "clickCount": 0,
      "conversionCount": 0
    },
    // {...}
  ]
}

With the revenueAnalytics parameter set to true:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/hits?revenueAnalytics=true&search=${query term}&index=${index name}&startDate=${startDate}&endDate=${endDate}"

Response:

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
{
  "hits": [
    {
      "hit": "hit1",
      "count": 2,
      "clickThroughRate": 1,
      "conversionRate": 0.5,
      "purchaseRate": 0.5,
      "addToCartRate": 0.5,
      "trackedSearchCount": 2,
      "clickCount": 2,
      "conversionCount": 1,
      "purchaseCount": 1,
      "addToCartCount": 1,
      "currencies": {
        "USD": {
          "currency": "USD",
          "revenue": 1201.3
        }
      }
    },
    {
      "hit": "hit0",
      "count": 1,
      "clickThroughRate": null,
      "conversionRate": null,
      "purchaseRate": null,
      "addToCartRate": null,
      "trackedSearchCount": 0,
      "clickCount": 0,
      "conversionCount": 0,
      "purchaseCount": 0,
      "addToCartCount": 0
    },
    // {...}
  ]
}

Path: /2/users/count
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns the distinct count of users across the given time range. The endpoint returns a value for the complete given time range, as well as a value per day.

Note that the total value is not the sum of all the daily values since it’s a distinct count.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/users/count?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
8
9
{
  "count": 3,
  "dates": [
    {"date": "2017-01-01", "count": 1},
    {"date": "2017-01-02", "count": 0},
    {"date": "2017-01-03", "count": 2},
    // {...}
  ]
}

Path: /2/filters
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns top filter attributes. Limited to the 1000 most used filters.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/filters?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
{
  "attributes": [
    {"attribute": "brand", "count": 2},
    {"attribute": "_tags", "count": 1},
    // {...}
  ]
}

Path: /2/filters/noResults?search=
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns top filters for the given no result search. Limited to the 1000 most used filters.

For example:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/filters/noResults?search=$(query term)&index=${index name}&startDate=${startDate}&endDate=${endDate}"

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/filters/noResults?search=$(query term)&index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "values": [
    {
      "count": 3,
      "values": [
        {"attribute": "brand", "operator": ":", "value": "apple"},
        {"attribute": "price", "operator": ">", "value":"100"}
      ]
    },
    {
      "count": 1,
      "values": [
        {"attribute": "brand", "operator": ":", "value": "apple"}
      ]
    },
    // {...}
  ]
}

Path: /2/filters?search=
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns top filter attributes for the given search. Limited to the 1000 most used filter attributes.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/filters?search=$(query term)&index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
{
  "attributes": [
    {"attribute": "brand", "count": 2},
    {"attribute": "_tags", "count": 1},
    // {...}
  ]
}

Path: /2/filters/{attribute list}?search=
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns top filters for the given attributes and search. Limited to the 1000 most used ones.

Several attributes can be given by separating them with a comma.

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/filters/brand,price?index=MyIndex&startDate=2018-01-01&search=MySearch"

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/filters/${attribute list}?search=$(query term)&index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
{
  "values": [
    {"attribute": "brand", "operator": ":", "value": "apple", "count": 2},
    {"attribute": "_tags", "operator": ":", "value": "comment", "count": 1},
    // {...}
  ]
}

Path: /2/filters/{attribute}
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns top filters for the given attribute. Limited to the 1000 most used filters.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/filters/${attribute}?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
{
  "values": [
    {"attribute": "brand", "operator": ":", "value": "apple", "count": 2}
  ]
}

Path: /2/countries
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns top countries. Limited to the 1000 most frequent ones.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/countries?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
{
  "countries": [
    {"country": "US", "count": 2},
    {"country": "UK", "count": 1},
    // {...}
   ]
}

Click, conversion, and revenue analytics

Quick reference

Path: /2/clicks/averageClickPosition
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns the average click position. The endpoint returns a value for the complete given time range, as well as a value per day.

An average of null means Algolia didn’t receive any click events for the queries with the clickAnalytics search parameter set to true. The average is null until Algolia receives at least one click event.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/clicks/averageClickPosition?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
8
9
{
  "average": 1.6666666666666667,
  "clickCount": 3,
  "dates": [
    {"date": "2017-01-01", "average": 1, "clickCount": 1},
    {"date": "2017-01-02", "average": null, "clickCount": 0},
    {"date": "2017-01-03", "average": 2, "clickCount": 2}
  ]
}

Path: /2/clicks/positions
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns the distribution of clicks per range of positions. The ranges respect the following pattern:

• Positions from 1 to 10 included are displayed in separated groups.
• Positions from 11 to 20 included are grouped together.
• Positions from 21 and up are grouped together.

If the groups all have a count of 0, it means Algolia didn’t receive any click events for the queries with the clickAnalytics search parameter set to true. The count is 0 until Algolia receives at least one click event.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/clicks/positions?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object (truncated for readability):

1
2
3
4
5
6
7
8
9
10
{
  "positions": [
    {"position": [1,1], "clickCount": 6},
    {"position": [2,2], "clickCount": 2},
    ...
    {"position": [10,10], "clickCount": 5},
    {"position": [11,20], "clickCount": 3},
    {"position": [21,-1], "clickCount": 2}
  ]
}

Path: /2/clicks/clickThroughRate
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns a click-through rate (CTR). The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of clicks and searches used to compute the rates.

Tracked searches are searches for which the engine returned a queryID, so searches where you’ve set the clickAnalytics search parameter to true. This is different than the “count” attribute of the response, which includes tracked searches and searches where you didn’t enable the clickAnalytics search parameter.

It’s important to make the distinction between a 0% CTR and a null value:

• If the CTR is null, it means that Algolia didn’t receive any queries with the clickAnalytics search parameter set to true.
• If the CTR is 0, it means Algolia didn’t receive any click events for the queries with the clickAnalytics search parameter set to true.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/clicks/clickThroughRate?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
8
9
10
{
  "rate": 0.42857142857142855,
  "trackedSearchCount": 14,
  "clickCount": 6,
  "dates": [
    {"date": "2017-01-01", "rate": 0.5, "trackedSearchCount": 10, "clickCount": 5},
    {"date": "2017-01-02", "rate": null, "trackedSearchCount": 0, "clickCount": 0},
    {"date": "2017-01-03", "rate": 0.25, "trackedSearchCount": 4, "clickCount": 1}
  ]
}

Path: /2/conversions/conversionRate
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Returns a conversion rate (CR). The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of conversion and searches used to compute the rates.

Tracked searches are searches for which the engine returned a queryID, so searches where you’ve set the clickAnalytics search parameter to true. This is different than the “count” attribute of the response, which includes tracked searches and searches where you didn’t enable the clickAnalytics search parameter.

It’s important to make the distinction between a 0% CR and a null value:

• If the CR is null, it means that Algolia didn’t receive any queries with the clickAnalytics search parameter set to true.
• If the CR is 0, it means Algolia didn’t receive any conversion events for the queries with the clickAnalytics search parameter set to true.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/conversions/conversionRate?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

1
2
3
4
5
6
7
8
9
10
{
  "rate": 0.42857142857142855,
  "trackedSearchCount": 14,
   "conversionCount": 6,
   "dates": [
     {"date": "2017-01-01", "rate": 0.5, "trackedSearchCount": 10, "conversionCount": 5},
     {"date": "2017-01-02", "rate": null, "trackedSearchCount": 0, "conversionCount": 0},
     {"date": "2017-01-03", "rate": 0.25, "trackedSearchCount": 4, "conversionCount": 1}
  ]
}

Path: /2/conversions/addToCartRate
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Return an add-to-cart rate.

Add-to-cart rate is based on conversion events that have eventSubType set to addToCart, and the total number of tracked searches within the specified timeframe. The rates are computed as the number of add-to-cart conversion events divided by the number of tracked searches.

This endpoint returns the add-to-cart rate, the number of searches associated with an add-to-cart conversion event and the total number of tracked searches in the requested analysis period, as well as daily values for those metrics. The default analysis period is the last seven days.

Tracked searches are searches for which the engine returned a queryID, so searches where you’ve set the clickAnalytics search parameter to true. This is different than the “count” attribute of the response, which includes tracked searches and searches where you didn’t enable the clickAnalytics search parameter.

• The add-to-cart rate is null, if Algolia didn’t receive any queries with the clickAnalytics search parameter set to true.
• The add-to-cart rate is 0, if Algolia didn’t receive any add-to-cart events for the queries with the clickAnalytics search parameter set to true.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/conversions/addToCartRate?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

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
{
  "rate": 0.42857142857142855,
  "trackedSearchCount": 14,
  "addToCartCount": 6,
  "dates": [
    {
      "date": "2017-01-01",
      "rate": 0.5,
      "trackedSearchCount": 10,
      "addToCartCount": 5
    },
    {
      "date": "2017-01-02",
      "rate": null,
      "trackedSearchCount": 0,
      "addToCartCount": 0
    },
    {
      "date": "2017-01-03",
      "rate": 0.25,
      "trackedSearchCount": 4,
      "addToCartCount": 1
    }
  ]
}

Path: /2/conversions/purchaseRate
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Return a purchase rate.

Purchase rate is based on conversion events that have eventSubType set to purchase, and the total number of tracked searches within the specified timeframe. The rates are computed as the number of purchase conversion events divided by the number of tracked searches.

This endpoint returns the purchase rate, the number of searches associated with a purchase conversion event and the total number of tracked searches in the requested analysis period, as well as daily values for those metrics. The default analysis period is the last seven days.

Tracked searches are searches for which the engine returned a queryID, so searches where you’ve set the clickAnalytics search parameter to true. This is different than the “count” attribute of the response, which includes tracked searches and searches where you didn’t enable the clickAnalytics search parameter.

• The purchase rate is null if Algolia didn’t receive any queries with the clickAnalytics search parameter set to true.
• The purchase rate is 0 if Algolia didn’t receive any conversion events for the queries with the clickAnalytics search parameter set to true.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/conversions/purchaseRate?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

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
{
  "rate": 0.42857142857142855,
  "trackedSearchCount": 14,
  "purchaseCount": 6,
  "dates": [
    {
      "date": "2017-01-01",
      "rate": 0.5,
      "trackedSearchCount": 10,
      "purchaseCount": 5
    },
    {
      "date": "2017-01-02",
      "rate": null,
      "trackedSearchCount": 0,
      "purchaseCount": 0
    },
    {
      "date": "2017-01-03",
      "rate": 0.25,
      "trackedSearchCount": 4,
      "purchaseCount": 1
    }
  ]
}

Path: /2/conversions/revenue
HTTP Verb: GET
Required API Key: any key with the analytics ACL

Description:

Return revenue data. This endpoint returns a currencies object with total metrics for the requested analysis period, as well as objects for each day. The default analysis period is the last seven days. Each currencies object has attributes for the revenue made in that currency, the number of transactions, and the average order value (AOV).

The currencies object looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "USD": {
    "currency": "USD",
    "revenue": 100,
    "transactionCount": 1,
    "averageOrderValue": 100
  },
  "EUR": {
    "currency": "EUR",
    "revenue": 200,
    "transactionCount": 2,
    "averageOrderValue": 100
  }
}

Revenue is based on conversion events that have eventSubtype set to purchase. The revenue is calculated as the price multiplied by quantity for each object in the objectData array of the event.

Parameters:

1
2
3
4
curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/2/conversions/revenue?index=${index name}&startDate=${startDate}&endDate=${endDate}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
{
  "currencies": {
    "EUR": {
      "currency": "EUR",
      "averageOrderValue": 163.3726912568306,
      "revenue": 119588.81,
      "transactionCount": 732
    },
    "USD": {
      "currency": "USD",
      "averageOrderValue": 175.64251046025106,
      "revenue": 125935.68,
      "transactionCount": 717
    }
  },
  "dates": [
    {
      "date": "2023-09-29",
      "currencies": {
        "EUR": {
          "currency": "EUR",
          "averageOrderValue": 162.3255,
          "revenue": 9739.53,
          "transactionCount": 60
        },
        "USD": {
          "currency": "USD",
          "averageOrderValue": 194.10152542372882,
          "revenue": 11451.99,
          "transactionCount": 59
        }
      }
    },
    {
      "date": "2023-09-30",
      "currencies": {
        "EUR": {
          "currency": "EUR",
          "averageOrderValue": 164.85879310344828,
          "revenue": 28685.43,
          "transactionCount": 174
        },
        "USD": {
          "currency": "USD",
          "averageOrderValue": 166.5888622754491,
          "revenue": 27820.34,
          "transactionCount": 167
        }
      }
    },
    {
      "date": "2023-10-01",
      "currencies": {
        "EUR": {
          "currency": "EUR",
          "averageOrderValue": 170.565,
          "revenue": 17738.76,
          "transactionCount": 104
        },
        "USD": {
          "currency": "USD",
          "averageOrderValue": 168.87460317460318,
          "revenue": 21278.2,
          "transactionCount": 126
        }
      }
    },
    // {...}
  ]
}