🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
API reference / 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:

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) query made by the user. 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 end 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

Verb Path Method

GET

/2/status

Get status

Get status

A

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

Parameter Description
index
type: string
Required

The index name to target.

Example:

A

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

Verb Path Method

GET

/2/searches

Get top searches

GET

/2/searches/count

Get count of searches

GET

/2/searches/noResults

Get top searches with no results

GET

/2/searches/noClicks

Get top searches with no clicks

GET

/2/searches/noResultRate

Get rate of no results

GET

/2/searches/noClickRate

Get rate of no clicks

GET

/2/hits

Get top hits

GET

/2/hits?search=

Get top hits for a search

GET

/2/users/count

Get count of users

GET

/2/filters

Get top filter attributes

GET

/2/filters/noResults?search=

Get top filters for a no result search

GET

/2/filters?search=

Get top filter attributes for a search

GET

/2/filters/{attribute list}?search=

Get top filters for attributes and search

GET

/2/filters/{attribute}

Get top filters for an attribute

GET

/2/countries

Get top countries

Get top searches

A

Path: /2/searches
HTTP Verb: GET

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.

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:

Parameter Description
index
type: string
Required

The index name to target.

clickAnalytics
type: boolean
default: false
Optional

Whether to include the click-through and conversion rates for a search.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

orderBy
type: string
default: "searchCount"
Optional

You can reorder the results by passing one of the following:

  • searchCount
  • clickThroughRate
  • conversionRate
  • averageClickPosition

Note that clickThroughRate, conversionRate and averageClickPosition are only available if the clickAnalytics parameter is set to true.

direction
type: string
default: "desc"
Optional

asc or desc.

limit
type: integer
default: 10
Optional

How many items to fetch.

offset
type: integer
default: 0
Optional

From which position to start retrieving results.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get count of searches

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get top searches with no results

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

limit
type: integer
default: 10
Optional

How many items to fetch.

offset
type: integer
default: 0
Optional

From which position to start retrieving results.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get top searches with no clicks

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

limit
type: integer
default: 10
Optional

How many items to fetch.

offset
type: integer
default: 0
Optional

From which position to start retrieving results.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get rate of no results

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get rate of no clicks

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get top hits

A

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:

Parameter Description
index
type: string
Required

The index name to target.

clickAnalytics
type: boolean
default: false
Optional

Whether to include the click-through and conversion rates for a hit.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

limit
type: integer
default: 10
Optional

How many items to fetch.

offset
type: integer
default: 0
Optional

From which position to start retrieving results.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

A

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:

Parameter Description
index
type: string
Required

The index name to target.

type: string
Required

The query term. Must match the exact user input.

clickAnalytics
type: boolean
default: false
Optional

Whether to include the click-through and conversion rates for a hit.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

limit
type: integer
default: 0
Optional

How many items to fetch.

offset
type: integer
default: 0
Optional

From which position to start retrieving results.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get count of users

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get top filter attributes

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

limit
type: integer
default: 10
Optional

How many items to fetch.

offset
type: integer
default: 0
Optional

From which position to start retrieving results.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

A

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:

Parameter Description
index
type: string
Required

The index name to target.

search
type: string
Required

The query term. Must match the exact user input.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

limit
type: integer
default: 10
Optional

How many items to fetch.

offset
type: integer
default: 0
Optional

From which position to start retrieving results.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

A

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:

Parameter Description
index
type: string
Required

The index name to target.

search
type: string
Required

The query term. Must match the exact user input.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

limit
type: integer
default: 10
Optional

How many items to fetch.

offset
type: integer
default: 0
Optional

From which position to start retrieving results.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

A

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:

Parameter Description
{attribute list}
type: comma-separated list
Required

The exact names of the attributes, separated by commas.

index
type: string
Required

The index name to target.

search
type: string
Required

The query term. Must match the exact user input.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

limit
type: integer
default: 10
Optional

How many items to fetch.

offset
type: integer
default: 0
Optional

From which position to start retrieving results.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get top filters for an attribute

A

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:

Parameter Description
attribute
type: string
Required

The exact name of the attribute.

index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

limit
type: integer
default: 10
Optional

How many items to fetch.

offset
type: integer
default: 0
Optional

From which position to start retrieving results.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get top countries

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

limit
type: integer
default: 10
Optional

How many items to fetch.

offset
type: integer
default: 0
Optional

From which position to start retrieving results.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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 and conversion analytics

Quick reference

Verb Path Method

GET

/2/clicks/averageClickPosition

Get average click position

GET

/2/clicks/positions

Get click positions

GET

/2/clicks/clickThroughRate

Get click-through rate

GET

/2/conversions/conversionRate

Get conversion rate

Get average click position

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get click positions

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get click-through rate

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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

Get conversion rate

A

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:

Parameter Description
index
type: string
Required

The index name to target.

startDate
type: Date, UTC. Inclusive.
default: 7 days ago, 00:00:00am, UTC
Optional

The lower bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

endDate
type: Date, UTC. Inclusive.
default: Today, 23:59:59pm, UTC
Optional

The upper bound timestamp (a date, a string like “2006-01-02”) of the period to analyze.

tags
type: string
Optional

Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded. E.g:

  • “lang:fr OR lang:en”
  • “platform:ios AND lang:en”
  • “(lang:fr OR lang:en) AND platform:android”
  • “device:mobile%20phone” (note the URL encoded)

Example:

A

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}
  ]
}
Did you find this page helpful?