Analytics REST API

Overview

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 (e.g., 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 requests per minute per application.

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

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.

See the 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 API key that you’re passing through the X-Algolia-API-Key header 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 the 1000 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.

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

• If the CTR, CR 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 and CR 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.

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "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
{
  "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. The endpoint returns a value for the complete given time range, as well as a value per day.

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "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 didn’t return any results. Limited to the 1000 most frequent ones.

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "searches": [
    {"search": "q1", "count": 2, "withFilterCount": 1},
    {"search": "q0", "count": 1, "withFilterCount": 0},
    // {...}
  ]
}

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

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 API key that you’re passing through the X-Algolia-API-Key header 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/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

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.

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "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

Description:

Returns the rate at which 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 searches and searches without clicks.

The API key that you’re passing through the X-Algolia-API-Key header 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/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

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.

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

• If the CTR, CR 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 and CR 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.

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "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
{
  "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},
    // {...}
  ]
}

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

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.

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

• If the CTR, CR 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 and CR 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.

The API key that you’re passing through the X-Algolia-API-Key header 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},
    // {...}
  ]
}

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
{
  "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},
    // {...}
  ]
}

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

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.

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "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 the 1000 most used filters.

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "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 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}"

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "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 the given search. Limited to the 1000 most used filter attributes.

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "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 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"

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "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 the 1000 most used filters.

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "values": [
    {"attribute": "brand", "operator": ":", "value": "apple", "count": 2}
  ]
}

Path: /2/countries
HTTP Verb: GET

Description:

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

The API key that you’re passing through the X-Algolia-API-Key header 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
{
  "countries": [
    {"country": "US", "count": 2},
    {"country": "UK", "count": 1},
    // {...}
   ]
}

Click Analytics

Quick Reference

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

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.

The API key that you’re passing through the X-Algolia-API-Key header 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/positions
HTTP Verb: GET

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.

The API key that you’re passing through the X-Algolia-API-Key header 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/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

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.

The API key that you’re passing through the X-Algolia-API-Key header 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 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.

The API key that you’re passing through the X-Algolia-API-Key header 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}
  ]
}