Analytics

The Analytics endpoints allow you to extract and record analytics information from your Engines. The endpoints provide the same analytics details that are available in the Site Search dashboard.

Each endpoint has two different forms depending on the scope for which the data is returned: one which applies to the Engine and one which applies to a specific DocumentType.

In case of invalid or missing parameters, the API will return an HTTP 400 code and a JSON message explaining the validation error.

The following analytical capabilities are available to you:

• Searches
• Autoselects
• Clicks
• Top Queries
• Top Queries with No Results
• Clickthroughs

Searches

This endpoint returns the number of searches that occurred on a given day. You can send queries against an Engine, or for a DocumentType.

Note: The maximum time range between the start and end dates is 30 days.

Options

curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/analytics/searches.json' \
-H 'Content-Type: application/json' \
-d '{
      "auth_token": "YOUR_API_KEY",
      "start_date": "2012-05-03",
      "end_date": "2012-06-03"
    }'

By default, the return period is two weeks:

curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/analytics/searches.json' \
-H 'Content-Type: application/json' \
-d '{
      "auth_token": "YOUR_API_KEY"
    }'

Autoselects

An autoselect is how often a document was clicked or selected from within an autocomplete dropdown menu. This endpoint returns the number of autoselects that occurred on a given day. You can send queries against an Engine, or for a DocumentType.

Note: The maximum time range between the start and end dates is 30 days.

curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/analytics/autoselects.json' \
-H 'Content-Type: application/json' \
-d '{
      "auth_token": "YOUR_API_KEY",
      "start_date": "2012-05-03",
      "end_date": "2012-06-03"
    }'

By default, the return period is two weeks:

curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/analytics/autoselects.json' \
-H 'Content-Type: application/json' \
-d '{
      "auth_token": "YOUR_API_KEY"
    }'

Clicks

A clickthrough occurs when a visitor clicks an item within a search result. This endpoint returns the number of clickthroughs. You can send queries against an Engine, or for a DocumentType.

Note: The maximum time range between the start and end date is 30 days.

curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/analytics/clicks.json' \
-H 'Content-Type: application/json' \
-d '{
      "auth_token": "YOUR_API_KEY",
      "start_date": "2012-05-03",
      "end_date": "2012-06-03"
    }'

By default, the return period is two weeks:

curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/analytics/clicks.json' \
-H 'Content-Type: application/json' \
-d '{
      "auth_token": "YOUR_API_KEY"
    }'

Top queries

This endpoint returns a paginated list of the queries that have been submitted to a given Engine in a given time period, between the start_date and end_date. The result is an array of [ "query", query_count ] arrays in descending order, by query count. You can send queries against an Engine, or for a DocumentType.

DEPRECATION: Thetop_queries_in_range API call is now deprecated and should be replaced with top_queries if needed.

curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/analytics/top_queries.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "start_date": "2013-01-01",
        "end_date": "2013-01-31"
      }'

[
  ["most popular query", 101],
  ["second most popular query", 92],
  ["third most popular query", 72]
]

Please note, that the total maximum number of queries you are allowed to page through is 1000.

Top no-result queries

This endpoint returns a paginated list of the queries with no results that have been submitted to a given Engine in a given time period, between the start_date and end_date. The result is an array of [ "query", query_count ] arrays in descending order, by query count. You can send queries against an Engine, or for a DocumentType.

Options

Please note, that the total maximum numner of queries you are allowed to page through is 1000.

curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/analytics/top_no_result_queries.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "auth_token": "YOUR_API_KEY",
        "start_date": "2013-01-01",
        "end_date": "2013-01-31"
      }'

[
  ["most popular query", 101],
  ["second most popular query", 92],
  ["third most popular query", 72]
]

Clickthroughs

This endpoint allows you to record a clickthrough for a particular result. Note that our JavaScript libraries do this by default, but you can implement these endpoints if you are using another client.

Options

curl -X POST 'https://api.swiftype.com/api/v1/engines/bookstore/document_types/book/analytics/log_clickthrough.json' \
 -H 'Content-Type: application/json' \
 -d '{
       "auth_token": "YOUR_API_KEY",
       "id": "1234",
       "q": "Gatsby"
     }'

Stuck? Looking for help? Contact Support!