17 Sep 2018

Analytics REST API

Overview

The Analytics API endpoints are reached via https://analytics.algolia.com.

The Click Analytics API endpoints are reached via https://insights.algolia.io.

Note: Each endpoint targets only a single index.

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

Click Analytics are only available to Business and Enterprise customers. They can be viewed either in the Dashboard or programmatically via the Analytics API.

Common Parameters

Every endpoint accepts the following set of parameters:

  • X-Algolia-Application-Id: The appID. Can also be passed through HTTP headers.
  • X-Algolia-API-Key: Auth token. Can also be passed through HTTP headers.
  • index: Index name to target.
  • startDate and endDate: Time periods you wish to analyse. Optional.
  • limit and offset: How many items to fetch (defaults to 10) and from which position (defaults to 0). Optional.

ACL

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

Validation Error

In case of error, both the analytics and click analytics API will return a payload in the following format:

{
  “status”: 123,
  “message”:”The error message”
}

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.

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 top 1000. For each search, also returns the average number of hits returned.

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

  • the average number of hits returned,
  • the click through rate,
  • the conversion rate,
  • the average click position.

You can also order the results using orderBy and direction.

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

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

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

Parameters:

clickAnalytics
type: boolean
Optional
default: false

True or False. See above.

orderBy
type: string
Optional
default: "searchCount"

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
Optional
default: "desc"

asc or desc.

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

{
  "searches":
  [
    {"search": "q1", "count": 2, "nbHits": 1},
    {"search": "q0", "count": 1, "nbHits": 1},
    // {...}
  ]
}

If you set clickAnalytics=true:

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:

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

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

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

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

Parameters:

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

{
  "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 top 1000.

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

Parameters:

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

{
  "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 X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

Parameters:

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

{
  "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 X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

Parameters:

index
type: string
Required

Index name to target

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

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

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

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

Example:

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:

{
  "hits":
  [
    {"hit": "hit1", "count": 2},
    {"hit": "hit0", "count": 1},
    // {...}
]
}

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

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

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

Parameters:

type: string
Required

The Query Term. Requires exact matching: needs to match exactly as input.

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

{"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 X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

Parameters:

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

{
  "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 top 1000.

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

Parameters:

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

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

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

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

Parameters:

search
type: string
Required

The Query Term. Requires exact matching: needs to match exactly as input.

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

{
  "values":
  [
    {
      "count": 3,
      "values": [
        {"attribute": "brand", "operator": ":", "value": "apple"},
        {"attribute": "price", "operator": ">", "value":"100"}
      ]
    },
    {
      "count": 1,
      "values": [
        {"attribute": "brand", "operator": ":", "value": "apple"}
      ]
    }
    // {...}
  ]
}

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

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

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

Parameters:

search
type: string
Required

The Query Term. Requires exact matching: needs to match exactly as input.

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

{
  "attributes":
  [
    {"attribute": "brand", "count": 2},
    {"attribute": "_tags", "count": 1},
    // {...}
  ]
}

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

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

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

For example:

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

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

Parameters:

{attribute list}
type: comma-separated list
Required

The exact names of the attributes, separated by commas.

search
type: string
Required

The Query Term. Requires exact matching: needs to match exactly as input.

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

{
  "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 top 1000.

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

Parameters:

attribute
type: string
Required

The exact name of the attribute.

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

{
  "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 X-Algolia-API-KEY is an api key that needs to have the analytics ACL.

Parameters:

index
type: string
Required

Index name to target.

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

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

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

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

Example:

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:

{
  "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/clickThroughRate

Get Click Through Rate

GET

/2/conversions/conversionRate

Get Conversion Rate

POST

/1/searches/click

Post Click Event

POST

/1/searches/conversion

Post Conversion Event

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 but no queries were received with clickAnalytics=true:

  • average will be null.

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

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

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

Parameters:

index
type: string
Required

Index name to target

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

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

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

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

Example:

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:

{
  "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 Through Rate

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

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

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

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

  • CTR will be null.

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

  • CTR is 0 until we receive a click event.

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

Parameters:

index
type: string
Required

Index name to target

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

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

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

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

Example:

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:

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

Path: /2/conversions/conversionRate
HTTP Verb: GET

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

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

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

  • CT will be null.

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

  • CR is 0 until we receive a click event.

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

Parameters:

index
type: string
Required

Index name to target

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

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

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

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

Example:

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:

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

Post Click Event

Path: /1/searches/click
HTTP Verb: POST

Description:
Use this to post the click event.

Parameters:

timestamp
type: int
Optional

Milliseconds since epoch. Default is now() (UTC).

queryID
type: string
Required

As provided by the search endpoint response.

objectID
type: string
Required

The hit to attribute the click to.

position
type: uint
Required

Absolute position of the result. Must be > 0.

Example:

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     -H "Content-Type: application/json" \
     -d '{
        "timestamp": 1500469127592,
        "queryID": "a48a30e835094323b4cc101156f530bd",
        "objectID": "1234",
        "position": 1 }' \
    "https://insights.algolia.io/1/searches/click"

Post Conversion Event

Path: /1/searches/conversion
HTTP Verb: POST

Description:
Use this to post the conversion event.

Parameters:

timestamp
type: int
Optional

Milliseconds since epoch. Default is now() (UTC).

queryID
type: string
Required

As provided by the search endpoint response.

objectID
type: string
Required

The hit to attribute the click to.

Example:

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
     -H "Content-Type: application/json" \
     -d '{
        "timestamp": 1500469127592,
        "queryID": "a48a30e835094323b4cc101156f530bd",
        "objectID": "1234" }' \
    "https://insights.algolia.io/1/searches/conversion"
© Algolia - Privacy Policy