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 functions depending on the scope: 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

Engine Type	Supported?
Crawler based Engine	YES
API based Engine	YES

Read more about Crawler based Engines and API based Engines within the API Overview.

Searches

Returns the number of searches that occurred on a given day.

You can find the number of search for an Engine or for a DocumentType.

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

start_date
optional: The first day from which to capture searches. Defaults to 2 weeks.
end_date
optional: The last date from which to capture searches. Defaults to current date.

Searches, Engine

GET /api/v1/engines/{engine_id}/analytics/searches.json

Example - Get the number of searches conducted each day for a month for the bookstore Engine.

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

Searches, DocumentType

GET /api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/searches.json

Example - Get the number of searches for the default two weeks for the books DocumentType within the bookstore Engine.

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

Autoselects

How often a document was clicked or selected from within an autocomplete dropdown menu. You can capture autoselects across an Engine or for a DocumentType.

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

start_date
optional: The first day from which to capture autoselects. Defaults to 2 weeks.
end_date
optional: The last date from which to capture autoselects. Defaults to current date.

Autoselects, Engine

GET /api/v1/engines/{engine_id}/analytics/autoselects.json

Example - Get the number of autoselects conducted each day for a month for the bookstore Engine.

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

Autoselects, DocumentType

GET /api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/autoselects.json

Example - Get the number of autoselects for the default two weeks for the books DocumentType within the bookstore Engine.

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

Clicks

A click occurs when a visitor clicks an item within a search result. 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.

start_date
optional: The first day from which to capture clicks. Defaults to 2 weeks.
end_date
optional: The last date from which to capture clicks. Defaults to current date.

Clicks, Engine

GET /api/v1/engines/{engine_id}/analytics/clicks.json

Example - Get the number of clicks conducted each day for a month for the bookstore Engine.

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

Clicks, DocumentType

GET /api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/clicks.json

Example - Get the number of clicks for the default two weeks for the books DocumentType within the bookstore Engine.

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

Top queries

Returns a paginated list of the queries that have been submitted to an Engine or DocumentType.The result is an array of [ "query", query_count ] arrays in descending order, by query count.

The total maximum number of queries you are allowed to page through is 1000.

Note: Thetop_queries_in_range API call is deprecated. Replace with top_queries.

start_date
optional: The first day from which to capture top queries. Defaults to 2 weeks.
end_date
optional: The last date from which to capture top queries. Defaults to current date.
page
optional: Page number for pagination, defaults at 1. Maximum number of pages is 50.
per_page
optional: Number of items per page, defaults to 20. Maximum number of results per page is 100.

Top queries, Engine

GET /api/v1/engines/{engine_id}/analytics/top_queries.json

Example - Get the top 10 queries submitted to the bookstore Engine in the month of January.

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": "2018-01-01",
        "end_date": "2018-01-31"
      }'

Example Response

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

Top queries, DocumentType

GET /api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/top_queries.json

Example - Get the top 10 queries for the default 2 weeks for the books DocumentTpye within the bookstore Engine.

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

Example Response

[
  ["most popular query", 132],
  ["second most popular query", 31],
  ["third most popular query", 55]
]

Top no result queries

Returns a paginated list of the queries with no results that have been submitted to a given Engine or DocumentType. The result is an array of [ "query", query_count ] arrays in descending order, by query count.

The total maximum number of queries you are allowed to page through is 1000.

start_date
optional: The first day from which to capture analytics. Defaults to 2 weeks.
end_date
optional: The last date from which to capture analytics. Defaults to current date.
page
optional: Page number, defaults at 1. Maximum number of pages is 50.
per_page
optional: Number of items per page, defaults to 20. Maximum number of results per page is 100.

Top no result queries, Engine

GET /api/v1/engines/{engine_id}/analytics/top_no_result_queries.json

Example - Requesting for the top no result queries between 2013-01-01 and 2013-01-31 within the bookstore Engine.

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

Example Response

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

Top no result queries, DocumentType

GET /api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/top_no_result_queries.json

Example - Requesting for the top no result queries for the books DocumentType within the bookstore Engine for the default 2 week time period.

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

Example Response

[
  ["most popular query", 55],
  ["second most popular query", 24],
  ["third most popular query", 11]
]

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.

id
required: The external_id or id of the document clicked by the user.
q
required: The query that lead to the clicked document.

GET /api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/log_clickthrough.json

POST /api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/log_clickthrough.json

Example - Record a clickthrough to book "1234" for the query "Gatsby".

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!

Site Search

Guides

Site Search API

API Reference

Resources

Analytics

Searches

Searches, Engine

Searches, DocumentType

Autoselects

Autoselects, Engine

Autoselects, DocumentType

Clicks

Clicks, Engine

Clicks, DocumentType

Top queries

Top queries, Engine

Top queries, DocumentType

Top no result queries

Top no result queries, Engine

Top no result queries, DocumentType

Clickthroughs