API Reference / REST API / Analytics REST API

Analytics REST API

The Analytics API is only available on Premium plans and plans including our Enterprise add-on.

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:

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.

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

Status of Analytics

Quick Reference

Verb Path Method

GET

/2/status

Get Status

Get Status

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:

index
type: string
Required

The index name to target.

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/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/noResultRate

Get Rate of No Results

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

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 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 API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

clickAnalytics
type: boolean
default: false
Optional

True or False. See above.

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 clickAnalytics=true.

direction
type: string
default: "desc"
Optional

asc or desc.

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:

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

Tracked searches are searches considered for click analytics purposes, meaning queries that were sent with clickAnalytics=true, therefore having a queryID in the response.

It is sometimes important to make the distinction between tracked searches and just searches, because when computing metrics like CTR, only queries that can effectively be clicked, should be accounted for.

For instance, you might only use click analytics on your desktop site, so only queries issued there should be counted when computing a click or conversion rate.

trackedSearchesCount is always equal or lower to your number of searches.

Get Count of Searches

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 API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

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:

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

Get Top Searches with no Results

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

Description:

Returns top searches that did not return any results. Limited to the 1000 most frequent.

The API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

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:

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

Get Rate of No Results

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 API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

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:

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

Get Top Hits

Path: /2/hits
HTTP Verb: GET

Description:

Returns top hits. Limited to top 1000.

The API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

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:

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

type: string
Required

The query term. Must match the exact user input.

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

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

Get Count of Users

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 API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

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:

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

Get Top Filter Attributes

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:

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:

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

search
type: string
Required

The query term. Must match the exact user input.

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:

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

search
type: string
Required

The query term. Must match the exact user input.

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:

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 the 1000 most used ones.

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 API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

{attribute list}
type: comma-separated list
Required

The exact names of the attributes, separated by commas.

search
type: string
Required

The query term. Must match the exact user input.

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:

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

Get Top Filters for an Attribute

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:

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:

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

Get Top Countries

Path: /2/countries
HTTP Verb: GET

Description:

Returns list of top countries, ordered by count.

The API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

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:

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

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

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 in your plan but you haven’t implemented it yet, average will be null.

When you implement Click Analytics and start sending queries, average will remain null until you send a click event.

The API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

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:

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

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

Description:

Returns the distribution of clicks per range of positions for the given time range and index. 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 upper are grouped together.

If you have Click Analytics enabled in your plan but you haven’t implemented it yet, count will be 0 for each position range.

When you implement Click Analytics and start sending queries, count will remain at 0 for each position until you send a click event.

The API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

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:

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

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

Description:

Returns click-through rate (CTR) 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 in your plan but you haven’t implemented it yet, CTR will be null.

When you implement Click Analytics and start sending queries, CTR will be 0 until you send a click event.

The API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

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:

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

Tracked searches are searches considered for click analytics purposes, meaning queries that were sent with clickAnalytics=true, therefore having a queryID in the response.

It is sometimes important to make the distinction between tracked searches and just searches, because when computing metrics like CTR, only queries that can effectively be clicked, should be accounted for.

For instance, you might only use click analytics on your desktop site, so only queries issued there should be counted when computing a click or conversion rate.

trackedSearchesCount is always equal or lower to your number of searches.

Get Conversion Rate

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 in your plan but you haven’t implemented it yet, conversion rate will be null.

When you implement Click Analytics and start sending queries, conversion rate will be 0 until you send a click event.

The API key that you’re passing through the X-Algolia-API-Key header needs to have the analytics ACL.

Parameters:

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:

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

Tracked searches are searches considered for click analytics purposes, meaning queries that were sent with clickAnalytics=true, therefore having a queryID in the response.

It is sometimes important to make the distinction between tracked searches and just searches, because when computing metrics like CTR, only queries that can effectively be clicked, should be accounted for.

For instance, you might only use click analytics on your desktop site, so only queries issued there should be counted when computing a click or conversion rate.

trackedSearchesCount is always equal or lower to your number of searches.

Did you find this page helpful?