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
Swiftype Documentation / api: Analytics

Analytics

The Analytics endpoints allow you to extract and record analytics information for a search engine. These endpoints provide the same analytics details that are available in the Swiftype dashboard.

Each endpoint has two different forms depending on the scope for which the data is returned:

URL Format Data scope
/api/v1/engines/{engine_id}/analytics/{method}.json Engine
/api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/{method}.json Document type

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

Searches

This endpoint returns the number of searches that occurred on a given day. Note that 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"
    }'
  
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

This endpoint returns the number of autoselects (selections or clicks on an item in the autocomplete dropdown) that occurred on a given day. Note that 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

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

This endpoint returns the number of clickthroughs (clicks on an item on the search results page) that occurred on a given day. Note that the maximum time range between the start and end dates 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

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 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"
    }'
  
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 start_date and end_date). The result is an Array of [ "query", query_count ] arrays of in a descending order by query count.

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

DEPRECATION NOTICE: Please note, that top_queries_in_range API call is now deprecated and should be replaced with top_queries if needed.

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 number of queries you are allowed to page through is 1000.

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

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 start_date and end_date). The result is an Array of [ "query", query_count ] arrays of in a descending order by query count.

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

Recording clickthroughs

This endpoint allows you to record a clickthrough to 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"
     }'