Api reference icon

Analytics REST API

Last updated 27 June 2017

Introduction

Endpoint

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

Some analytics queries can take up to several minutes.

Searches

  • Path: https://analytics.algolia.com/1/searches/{comma-separated list of indices}/popular
  • HTTP Verb: GET
  • Description: Return popular queries for a set of indices.

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

The endpoint has several parameters:

Name

Type

Description

size

integer

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

startAt

integer

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("24h ago").

endAt

integer

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("now").

tags

comma-separated list

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

country

string

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. Optional.

refinements

boolean

If enabled, returns the most used refinements for each search. (default=false)

csv

boolean

If enabled, returns the answer using CSV instead of JSON. (default=false)

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

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error

Get Searches with 0 Results

  • Path: https://analytics.algolia.com/1/searches/{comma-separated list of indices}/noresults
  • HTTP Verb: GET
  • Description: Return queries matching 0 records for a set of indices.

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

The endpoint has several parameters:

Name

Type

Description

size

integer

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

startAt

integer

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("24h ago").

endAt

integer

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("now").

tags

comma-separated list

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

country

string

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. Optional.

refinements

boolean

If enabled, returns the most used refinements for each search. (default=false)

csv

boolean

If enabled, returns the answer using CSV. (default=false)

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

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error

  • Path: https://analytics.algolia.com/1/searches/{comma-separated list of indices}/countries
  • HTTP Verb: GET
  • Description: Return popular countries for a set of indices.

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

The endpoint has several parameters:

Name

Type

Description

size

integer

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

startAt

integer

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("24h ago").

endAt

integer

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("now").

tags

comma-separated list

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

csv

boolean

If enabled, returns the answer using CSV. (default=false)

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

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error

Get Searches with 0, <5 and <10 Hits

  • Path: https://analytics.algolia.com/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.

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

The endpoint has several parameters:

Name

Type

Description

size

integer

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

startAt

integer

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("24h ago").

endAt

integer

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("now").

tags

comma-separated list

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

country

string

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. Optional.

csv

boolean

If enabled, returns the answer using CSV. (default=false)

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

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error

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

  • Path: https://analytics.algolia.com/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.

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

The endpoint has several parameters:

Name

Type

Description

size

integer

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

startAt

integer

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("24h ago").

endAt

integer

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("now").

tags

comma-separated list

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

country

string

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. Optional.

csv

boolean

If enabled, returns the answer using CSV. (default=false)

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

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error

Get Top IPs

  • Path: https://analytics.algolia.com/1/searches/{comma-separated list of indices}/ips
  • HTTP Verb: GET
  • Description: Return the top IP addresses for a set of indices.

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

The endpoint has several parameters:

Name

Type

Description

size

integer

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

startAt

integer

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("24h ago").

endAt

integer

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("now").

tags

comma-separated list

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

country

string

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. Optional.

csv

boolean

If enabled, returns the answer using CSV. (default=false)

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

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error

Get Top referers

  • Path: https://analytics.algolia.com/1/searches/{comma-separated list of indices}/referers
  • HTTP Verb: GET
  • Description: Return the top referer for a set of indices.

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

The endpoint has several parameters:

Name

Type

Description

size

integer

The number of referers to retrieve. Optional. Default is 100. Maximum is 10,000.

startAt

integer

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("24h ago").

endAt

integer

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("now").

tags

comma-separated list

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

country

string

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. Optional.

csv

boolean

If enabled, returns the answer using CSV. (default=false)

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

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error

Rate limits

Get Top rate limited IPs

  • Path: https://analytics.algolia.com/1/ratelimits/{comma-separated list of indices}/ips
  • HTTP Verb: GET
  • Description: Return the top rate limited IP addresses for a set of indices.

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

The endpoint has several parameters:

Name

Type

Description

size

integer

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

startAt

integer

The lower bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("24h ago").

endAt

integer

The upper bound timestamp (UNIX timestamp, in seconds) of the period to analyze. Optional. Default is timestamp("now").

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

Errors:

Error Code

Reason

403

Invalid credentials

500

Internal error

© Algolia - Privacy Policy