search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso

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

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.

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

Options

Option Default Description
start_date 2 weeks ago The first date from which you would like analytics
end_date today The last date from which you would like analytics

Example - Get the number of searches on each day for a month for Engine "bookstore".
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:

Example - Get the number of searches on each day for the last two weeks for Engine "bookstore".
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.

GET /api/v1/engines/{engine_id}/analytics/autoselects.json
GET /api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/autoselects.json
Option Default Description
`start_date` 2 weeks ago The first date from which you would like analytics
`end_date` today The last date from which you would like analytics
Example - Get the number of autoselects on each day for a month for Engine "bookstore".
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:

Example - Get the number of autoselects on each day for the last two weeks for Engine "bookstore".'
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.

GET /api/v1/engines/{engine_id}/analytics/clicks.json
GET /api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/clicks.json
Option Default Description
`start_date` 2 weeks ago The first date from which you would like analytics
`end_date` today The last date from which you would like analytics
Example - Get the number of clicks on each day for a month for Engine "bookstore".
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:

Example - Get the number of clicks on each day for the last two weeks for Engine "bookstore".
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.

GET /api/v1/engines/{engine_id}/analytics/top_queries.json
GET /api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/top_queries.json
Option Default Description
`start_date` 2 weeks ago The first day of the range (formatted like `2012-01-01`)
`end_date` today The last day of the range (formatted like `2012-01-01`)
`page` 1 Page number, numeration starts from 1. Maximum page number is 50.
`per_page` 20 Number of items per page. Maximum number of items per page is 100.
Example - Get the top 10 queries submitted to Engine "bookstore" in the given month.
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"
      }'
Example Response
[
  ["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.

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

Options

Option Default Description
start_date 2 weeks ago The first day of the range (formatted like 2012-01-01)
end_date today The last day of the range (formatted like 2012-01-01)
page 1 Page number, numeration starts from 1. Maximum page number is 50.
per_page 20 Number of items per page. Maximum number of items per page is 100.

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

Example - Record a clickthrough to book "1234" for the query "Gatsby".
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]
]

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.

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

Options

Option Required Description
id yes The external_id or ID of the document the user clicked on
q yes The query that led to the document

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!