Analytics

Extract and record analytics information from your Engines.

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 for an Engine or for a DocumentType.

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

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

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.

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

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 selected or clicked from an autocomplete dropdown menu.

Autoselects, Recording

Record an autoselect.

GET /api/v1/public/analytics/pas.json

engine_key
required: Your public Engine Key. Found within the dashboard.
doc_id
optional: The id of the document which the user selected from the autocomplete dropdown.
q
optional: The autocomplete query which lead to the click.

Example - Capture an autoselect on a public search query.

curl -X GET 'https://api.swiftype.com/api/v1/public/analytics/pas.json' \
    -H 'Content-Type: application/json' \
    -d '{
          "engine_key": "5jZG1gmmCTFYbSSDjpqq",
          "doc_id": "1234",
          "q": "Gatsby"
        }'

Autoselects, Analytics

Retrieve autoselect data by Engine or DocumentType.

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

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

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.

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

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

Returns the number of clicks a search received by Engine or for a DocumentType.

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

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

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.

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

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.

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

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

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.

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

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

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

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

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.

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

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

In some cases, a search may have zero results due to filters or other restrictions included within the search query. For example, the following query looks for "meetup" in the title field only. An engine may have documents that match "meetup" but not within the title field. In this case, the query is included in those with zero results.

Example - Search query with zero results due to restriction on search_fields.

curl -X GET 'https://search-api.swiftype.com/api/v1/public/engines/search.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "engine_key": "YOUR_ENGINE_KEY",
        "q": "meetup",
        "search_fields":{
          "page": ["title"]
        }
      }'

Clickthroughs

Record a clickthrough for a particular result.

Note: The JavaScript libraries do this by default, but you can implement these endpoints if you are using another client.

Clickthroughs, Public API

GET /api/v1/public/analytics/pc.json

engine_key
required: Your public Engine Key. Found within your dashboard.
doc_id
required: The id of the document clicked by the user. It must be passed in as a string to the doc_id parameter.
q
required: The query that lead to the clicked document.
t
optional: The time that the clickthrough took place. Passed in as Unix Time.

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

curl -X GET 'https://api.swiftype.com/api/v1/public/analytics/pc.json' \
  -H 'Content-Type: application/json' \
  -d '{
        "engine_key": "5jZG1gmmCTFYbSSDjpqq",
        "doc_id": "5c616afeb5b9e1796444e440",
        "q": "Gatsby",
        "t": 1551989483812
      }'

Clickthroughs, Private API

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

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

auth_token
required: Your private API Key. Found within your dashboard.
id
required: The id of the document clicked by the user. It must be passed in as a string to the id parameter.
q
required: The query that lead to the clicked document.
t
optional: The time that the clickthrough took place. Passed in as Unix Time.

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": "5c616afeb5b9e1796444e440",
       "q": "Gatsby",
       "t": 1551989483812
     }'

Plan Limitations

Analytics API data retention period and access range is limited depending on your plan:

Standard: Yesterday - 7 days. 30 day retention.
Pro: Yesterday - 30 days. 180 day retention.

The Analytics dashboard is limited to a max range of 90 days for Pro+ and 7 days for standard. For Pro+ users, if you have more than 90 days worth of data, you will need to export in batches of 90 days.

If you are on a custom plan, your limits may differ. If you would like to discuss a custom plan, email support.

Stuck? Looking for help? Contact support or check out the Site Search community forum!

Site Search

Guides

Site Search API

API Reference

API Clients

Plugins

Resources

Analytics

Searches

Autoselects

Autoselects, Recording

Autoselects, Analytics

Clicks

Top queries

Top no result queries

Clickthroughs

Clickthroughs, Public API

Clickthroughs, Private API

Plan Limitations