Api reference icon

Analytics REST API

Last updated 02 August 2017

Endpoints

Unlike the Search API, the Analytics API must be reached via https://analytics.algolia.com. The Analytics API allows you to analyze your query logs.

Some analytics queries can take up to several minutes.

Quick Reference

Search Analytics API

Path Verb Method

/1/searches/{comma-separated list of indices}/popular

GET Get Popular Searches

/1/searches/{comma-separated list of indices}/noresults

GET Get Searches with 0 Results

/1/searches/{comma-separated list of indices}/countries

GET Get Popular Countries

/1/searches/{comma-separated list of indices}/hits

GET Get Searches with 0, <5 and <10 Hits

/1/searches/{comma-separated list of indices}/hitswithtypo

GET Get Searches with 0, <5 and <10 Hits Including Typos

/1/searches/{comma-separated list of indices}/ips

GET Get Top IPs

/1/searches/{comma-separated list of indices}/referers

GET Get Top referers

/1/ratelimits/{comma-separated list of indices}/ips

GET Get Top rate limited IPs

Search Analytics API

Path

/1/searches/{comma-separated list of indices}/popular

HTTP Verb GET

Description

This method gets the average indexing time for the servers passed in the URL.

The X-Algolia-API-KEY must be the admin API key.

Parameters

type string
mandatory yes
description

A comma separated list of index name

type integer
mandatory no
default 20
description

The number of popular queries to retrieve. Maximum is 10,000.

type integer
mandatory no
default timestamp("24h ago")
description

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze.

type integer
mandatory no
default timestamp("now")
description

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze

type comma-separated list
mandatory no
description

The list of tags you want to drill into. Those tags can be set using the analyticsTags query parameter.

type string
mandatory no
description

The ISO 3166-1 alpha-2 country code. The country is computed with the ip provided with the client IP address or the X-Forwarded-For value.

type boolean
mandatory no
default false
description

If enabled, returns the most used refinements for each search.

type boolean
mandatory no
default false
description

If enabled, returns the answer using CSV instead of JSON.

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/popular?startAt=${startAt}&endAt=${endAt}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

{
  "lastSearchAt": "2014-10-05T09:00:00.000Z",
  "searchCount": 28043,
  "topSearches": [
    {
      "avgHitCount": 3542,
      "avgHitCountWithoutTypos": 2942,
      "count": 297,
      "query": "castar",
      "topRefinements" : [
        {
            "tag" : "comment",
            "count" : 296
        },
        {
            "tag" : "job",
            "count" : 296
        },
        {
            "count" : 296,
            "tag" : "poll"
        },
        {
            "count" : 296,
            "tag" : "story"
        }
      ]
    },
    {
      "avgHitCount": 617,
      "avgHitCountWithoutTypos": 617,
      "count": 261,
      "query": "spacex"
      "topRefinements" : [
        {
          "count" : 99,
          "tag" : "comment"
        },
        {
          "count" : 99,
          "tag" : "job"
        },
        {
          "tag" : "poll",
          "count" : 99
        },
        {
          "count" : 99,
          "tag" : "story"
        }
      ],
    },
    // [...]
  ]
}

Get Searches with 0 Results

Path

/1/searches/{comma-separated list of indices}/noresults

HTTP Verb GET

Description

Return queries matching 0 records for a set of indices.

The X-Algolia-API-KEY must be the admin API key.

Parameters

indices
type string
mandatory yes
description

A coma separated list of index name

size
type integer
mandatory no
default 20
description

The number of popular queries to retrieve. Maximum is 10,000.

startAt
type integer
mandatory no
default timestamp("24h ago")
description

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze.

endAt
type integer
mandatory no
default timestamp("now")
description

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze

tags
type comma-separated list
mandatory no
description

The list of tags you want to drill into. Those tags can be set using the analyticsTags query parameter.

country
type string
mandatory no
description

The ISO 3166-1 alpha-2 country code. The country is computed with the ip provided with the client IP address or the X-Forwarded-For value.

refinements
type boolean
mandatory no
default false
description

If enabled, returns the most used refinements for each search.

csv
type boolean
mandatory no
default false
description

If enabled, returns the answer using CSV instead of JSON.

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/noresults?startAt=${startAt}&endAt=${endAt}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

{
  "searchCount": 28170,
  "lastSearchAt": "2014-10-05T10:00:00.000Z",
  "topSearchesNoResuls": [
    {
      "query": "journalims",
      "count": 8
    },
    {
      "query": "segate",
      "count": 8
    },
    {
      "query": "ello buddy",
      "count": 7
    },
    {
      "query": "bootstrap angulardashboard",
      "count": 6
    },
    // [...]
  ]
}
Path

/1/searches/{comma-separated list of indices}/countries

HTTP Verb GET

Description

Return popular countries for a set of indices.

The X-Algolia-API-KEY must be the admin API key.

Parameters

type string
mandatory yes
description

A coma separated list of index name

type integer
mandatory no
default 20
description

The number of popular queries to retrieve. Maximum is 10,000.

type integer
mandatory no
default timestamp("24h ago")
description

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze.

type integer
mandatory no
default timestamp("now")
description

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze

type boolean
mandatory no
default false
description

If enabled, returns the answer using CSV instead of JSON.

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/countries?startAt=${startAt}&endAt=${endAt}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

{
   "searchCount" : 15753,
   "lastSearchAt" : "2015-02-11T14:00:00.000Z",
   "countryCount" : {
      "DE" : 914,
      "US" : 8101,
      "GB" : 932,
      // [...]
   }
}

Get Searches with 0, <5 and <10 Hits

Path

/1/searches/{comma-separated list of indices}/hits

HTTP Verb GET

Description

Return searches matching 0, <5 and <10 records for a set of indices.

The X-Algolia-API-KEY must be the admin API key.

Parameters

indices
type string
mandatory yes
description

A coma separated list of index name

size
type integer
mandatory no
default 20
description

The number of popular queries to retrieve. Maximum is 10,000.

startAt
type integer
mandatory no
default timestamp("24h ago")
description

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze.

endAt
type integer
mandatory no
default timestamp("now")
description

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze

tags
type comma-separated list
mandatory no
description

The list of tags you want to drill into. Those tags can be set using the analyticsTags query parameter.

country
type string
mandatory no
description

The ISO 3166-1 alpha-2 country code. The country is computed with the ip provided with the client IP address or the X-Forwarded-For value.

csv
type boolean
mandatory no
default false
description

If enabled, returns the answer using CSV instead of JSON.

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/hits?startAt=${startAt}&endAt=${endAt}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

{
   "searchCount" : 15731,
   "lastSearchAt" : "2015-02-11T14:00:00.000Z",
   "topSearchesLowHitsWithoutTypos" : {
      "0 hit" : [
         {
            "query" : "calendar node",
            "refinements" : {
               "key" : "tag",
               "value" : "story"
            },
            "avgHitCount" : 1,
            "count" : 2
         },
         // [...]
      ],
      "< 5 hits" : [
         {
            "query" : "voltera",
            "refinements" : {
               "key" : "tag",
               "value" : "story"
            },
            "avgHitCount" : 3,
            "count" : 18
         },
         // [...]
      ],
      "< 10 hits" : [
         {
            "query" : "voltera",
            "refinements" : {
               "value" : "story",
               "key" : "tag"
            },
            "avgHitCount" : 3,
            "count" : 25
         },
         // [...]
      ]
   }
}

Get Searches with 0, <5 and <10 Hits Including Typos

Path

/1/searches/{comma-separated list of indices}/hitswithtypo

HTTP Verb GET

Description

Return searches matching 0, <5 and <10 records for a set of indices.

The X-Algolia-API-KEY must be the admin API key.

Parameters

indices
type string
mandatory yes
description

A coma separated list of index name

size
type integer
mandatory no
default 20
description

The number of popular queries to retrieve. Maximum is 10,000.

startAt
type integer
mandatory no
default timestamp("24h ago")
description

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze.

endAt
type integer
mandatory no
default timestamp("now")
description

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze

tags
type comma-separated list
mandatory no
description

The list of tags you want to drill into. Those tags can be set using the analyticsTags query parameter.

country
type string
mandatory no
description

The ISO 3166-1 alpha-2 country code. The country is computed with the ip provided with the client IP address or the X-Forwarded-For value.

csv
type boolean
mandatory no
default false
description

If enabled, returns the answer using CSV instead of JSON.

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/hitswithtypo?startAt=${startAt}&endAt=${endAt}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

{
   "searchCount" : 15748,
   "lastSearchAt" : "2015-02-11T14:00:00.000Z",
   "topSearchesLowHits" : {
      "0 hit" : [
         {
            "query" : "calendar node",
            "refinements" : [
               {
                  "value" : "story",
                  "key" : "tag"
               }
            ],
            "avgHitCount" : 1,
            "count" : 2
         },
         // [...]
      ],
      "< 5 hits" : [
         {
            "query" : "occupy gpl",
            "refinements" : [
               {
                  "value" : "story",
                  "key" : "tag"
               }
            ],
            "avgHitCount" : 4,
            "count" : 3
         },
         // [...]
      ],
      "< 10 hits" : [
         {
            "query" : "jeb bush",
            "refinements" : [
               {
                  "value" : "story",
                  "key" : "tag"
               }
            ],
            "avgHitCount" : 3,
            "count" : 9
         },
         // [...]
      ]
   }
}

Get Top IPs

Path

/1/searches/{comma-separated list of indices}/ips

HTTP Verb GET

Description

Return the top IP addresses for a set of indices.

The X-Algolia-API-KEY must be the admin API key.

Parameters

indices
type string
mandatory yes
description

A coma separated list of index name

size
type integer
mandatory no
default 20
description

The number of popular queries to retrieve. Maximum is 10,000.

startAt
type integer
mandatory no
default timestamp("24h ago")
description

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze.

endAt
type integer
mandatory no
default timestamp("now")
description

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze

tags
type comma-separated list
mandatory no
description

The list of tags you want to drill into. Those tags can be set using the analyticsTags query parameter.

country
type string
mandatory no
description

The ISO 3166-1 alpha-2 country code. The country is computed with the ip provided with the client IP address or the X-Forwarded-For value.

csv
type boolean
mandatory no
default false
description

If enabled, returns the answer using CSV instead of JSON.

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/ips?startAt=${startAt}&endAt=${endAt}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

{
   "searchCount" : 16168,
   "userCount" : 4737,
   "lastSearchAt" : "2015-02-11T15:00:00.000Z",
   "topIPs" : [
      {
         "ip" : "19.44.30.155",
         "count" : 211
      },
      {
         "count" : 39,
         "ip" : "78.198.213.24"
      },
      {
         "ip" : "26.52.27.103",
         "count" : 33
      }
   ]
}

Get Top referers

Path

/1/searches/{comma-separated list of indices}/referers

HTTP Verb GET

Description

Return the top referer for a set of indices.

The X-Algolia-API-KEY must be the admin API key.

Parameters

indices
type string
mandatory yes
description

A coma separated list of index name

size
type integer
mandatory no
default 20
description

The number of popular queries to retrieve. Maximum is 10,000.

startAt
type integer
mandatory no
default timestamp("24h ago")
description

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze.

endAt
type integer
mandatory no
default timestamp("now")
description

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze

tags
type comma-separated list
mandatory no
description

The list of tags you want to drill into. Those tags can be set using the analyticsTags query parameter.

country
type string
mandatory no
description

The ISO 3166-1 alpha-2 country code. The country is computed with the ip provided with the client IP address or the X-Forwarded-For value.

csv
type boolean
mandatory no
default false
description

If enabled, returns the answer using CSV instead of JSON.

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://analytics.algolia.com/1/searches/${index}/referer?startAt=${startAt}&endAt=${endAt}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

{
   "searchCount" : 16168,
   "userCount" : 4737,
   "lastSearchAt" : "2015-02-11T15:00:00.000Z",
   "referer" : {
               "algolia.com" : "1000"
   }
}

Get Top rate limited IPs

Path

/1/ratelimits/{comma-separated list of indices}/ips

HTTP Verb GET

Description

Return the top rate limited IP addresses for a set of indices.

The X-Algolia-API-KEY must be the admin API key.

Parameters

indices
type string
mandatory yes
description

A coma separated list of index name

size
type integer
mandatory no
default 20
description

The number of IPs to retrieve. Maximum is 10,000.

startAt
type integer
mandatory no
default timestamp("24h ago")
description

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze.

endAt
type integer
mandatory no
default timestamp("now")
description

The upper bound timestamp (UNIX timestamp, in seconds) 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/1/ratelimits/${index}/ips?startAt=${startAt}&endAt=${endAt}"

When the query is successful, the HTTP response is a 200 OK and returns the following JSON object:

{
   "searchCount" : 16168,
   "userRateLimitedCount" : 4737,
   "lastSearchAt" : "2015-02-11T15:00:00.000Z",
   "topRateLimitedIPs" : [
      {
         "ip" : "19.44.30.155",
         "count" : 211
      },
      {
         "ip" : "78.198.213.24",
         "count" : 39
      },
      {
         "ip" : "26.52.27.103",
         "count" : 33
      }
   ]
}
© Algolia - Privacy Policy