Analytics REST API

Overview

Algolia collects Search Analytics for every customer, offering a detailed view of their end-users’ search activities. All customers can view this data on the Algolia Dashboard. However, to fetch it programmatically, using the Algolia Analytics API, you’ll need to be on an Enterprise plan.

At this time, click analytics are only available on Enterprise plans. They can be viewed either in the Dashboard or programmatically via the Analytics API. If you signed up for your plan with an Account Executive, please refer to your service order for your analytics features.

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.

Validation Error

In case of error, the API returns a payload in the following format:

1
2
3
4
{
  “status”: 123,
  “message”: ”The error message”
}

Rate Limiting

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

Query Aggregation

Our search engine is designed to accept queries at each keystroke. In order to have relevant analytics data, however, we aggregate the series of keystrokes to keep only the latest (final) query made by the end user.

That’s what we mean by “prefix” aggregation.

Go to our Analytics Implementation overview for more information about Query Aggregation.

Status of Analytics

Quick Reference

Path: /2/status
HTTP Verb: GET

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

Note: The Analytics API is updated every 5 minutes.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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

Description:
Returns top searches. Limited to top 1000. For each search, also returns the average number of hits returned.

If clickAnalytics=true, then for each search, also returns:

• the click through rate,
• the conversion rate,
• the average click position.

You can also order the results using orderBy and direction.

Distinguishing no data vs 0% CTR, 0% CR, no average

• You have click analytics enabled but no queries were received with clickAnalytics=true
  • in that case CTR, CR and average will be null.
• You have click analytics enabled, we received queries with clickAnalytics=true
• CTR and CR are 0 until we receive click/conversion events
• average will stay null until we receive a click event

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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
{
  "searches":
  [
    {"search": "q1", "count": 2, "nbHits": 1},
    {"search": "q0", "count": 1, "nbHits": 1},
    // {...}
  ]
}

If you set clickAnalytics=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
{
  "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},
    // {...}
  ]
}

Path: /2/searches/count
HTTP Verb: GET

Description:
Returns the number of searches across the given time range. A value is returned for the whole range. Additionally, values for each day are returned.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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

Description:
Returns top searches that did not return any results. Limited to top 1000.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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
8
{
  "searches":
  [
    {"search": "q1", "count": 2, "withFilterCount": 1},
    {"search": "q0", "count": 1, "withFilterCount": 0},
    // {...}
  ]
}

Path: /2/searches/noResultRate
HTTP Verb: GET

Description:
Returns the rate at which searches did not return any results. A value is returned for the whole range. Values per days are also returned. Additionally, the search count and the count of searches without results, used to compute the rates, are returned as well.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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
12
{
  "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/hits
HTTP Verb: GET

Description:
Returns top hits. Limited to top 1000.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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
{
  "hits":
  [
    {"hit": "hit1", "count": 2},
    {"hit": "hit0", "count": 1},
    // {...}
]
}

Path: /2/hits?search=
HTTP Verb: GET

Description:
Returns top hits for the given search. Limited to top 1000.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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
{"hits":
  [
    {"hit": "hit1", "count": 2},
    {"hit": "hit0", "count": 1},
    // {...}
  ]
}

Path: /2/users/count
HTTP Verb: GET

Description:
Returns count of distinct user across the given time range. A value is returned for the whole range. Additionally, values per days are also returned.

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

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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

Description:
Returns top filter attributes. Limited to top 1000.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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
8
{
  "attributes":
  [
    {"attribute": "brand", "count": 2},
    {"attribute": "_tags", "count": 1},
    // {...}
  ]
}

Path: /2/filters/noResults?search=
HTTP Verb: GET

Description:
Returns top filters for the given no result search. Limited to top 1000.

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?index=MyIndex&startDate=2018-01-01&search=MySearch"

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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

Description:
Returns top filter attributes for a given search. Limited to top 1000.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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
8
{
  "attributes":
  [
    {"attribute": "brand", "count": 2},
    {"attribute": "_tags", "count": 1},
    // {...}
  ]
}

Path: /2/filters/{attribute list}?search=
HTTP Verb: GET

Description:
Returns top filters for the given attributes and search. Limited to top 1000.

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

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/brand,price?index=MyIndex&startDate=2018-01-01&search=MySearch"

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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
8
{
  "values":
  [
    {"attribute": "brand", "operator": ":", "value": "apple", "count": 2},
    {"attribute": "_tags", "operator": ":", "value": "comment", "count": 1},
    // {...}
]
}

Path: /2/filters/{attribute}
HTTP Verb: GET

Description:
Returns top filters for the given attribute. Limited to top 1000.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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
6
{
  "values":
  [
    {"attribute": "brand", "operator": ":", "value": "apple", "count": 2}
  ]
}

Path: /2/countries
HTTP Verb: GET

Description:
Returns list of top countries, ordered by count.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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
8
{
  "countries":
  [
    {"country": "US", "count": 2},
    {"country": "UK", "count": 1},
    // {...}
   ]
}

Click Analytics

Quick Reference

Path: /2/clicks/averageClickPosition
HTTP Verb: GET

Description:
Returns average click position for the given time range. An average will be returned for the whole range as well as daily averages.

If you have click analytics enabled but no queries were received with clickAnalytics=true:

• average will be null.

If you have click analytics enabled, and we received queries with clickAnalytics=true:

• average will stay null until we receive a click event.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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/clickThroughRate
HTTP Verb: GET

Description:
Returns click through rate for the given time range. A rate will be returned for the whole range as well as daily rates.

Additionally, the click count as well as the number of searches used to compute the rate are returned.

If you have click analytics enabled but no queries were received with clickAnalytics=true:

• CTR will be null.

If you have click analytics enabled, and we received queries with clickAnalytics=true:

• CTR is 0 until we receive a click event.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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

Description:
Returns conversion rate for the given time range. A rate will be returned for the whole range as well as daily rates.

Additionally, the conversion count as well as the number of searches used to compute the rate are returned.

If you have click analytics enabled but no queries were received with clickAnalytics=true:

• CT will be null.

If you have click analytics enabled, and we received queries with clickAnalytics=true:

• CR is 0 until we receive a click event.

The X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

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}
  ]
}