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

Extract and record analytics information from your Engines.

The following analytical capabilities are available to you:

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

Autocompletes

How often a document was autocompleted in a dropdown menu.

Retrieve top search autocompletes data by Engine or DocumentType.

GET /api/v1/engines/{engine_id}/analytics/top_autocomplete_searches.json
GET /api/v1/engines/{engine_id}/document_types/{document_type}/analytics/top_autocomplete_searches.json
start_date
optional
The first day from which to retrieve top search autocompletes. Defaults to 2 weeks ago.
end_date
optional
The last day from which to retrieve search autocompletes. Defaults to the current date.
Example - Get the list of top search autocompletes conducted each day for a month for the bookstore Engine.
curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/analytics/top_autocomplete_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 list of top search autocompletes for the default two week period for the books DocumentType within the bookstore Engine.
curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/document_types/books/analytics/top_autocomplete_searches.json' \
-H 'Content-Type: application/json' \
-d '{
      "auth_token": "YOUR_API_KEY"
    }'
Example Response
[
  ["most search autocompleted query", 132],
  ["second most search autocompleted query", 31],
  ["third most search autocompleted query", 55]
]

Top Clickthrough Autocompletes

Retrieve top clickthrough autocompletes data by Engine or DocumentType.

GET /api/v1/engines/{engine_id}/analytics/top_autocomplete_clickthroughs.json
GET /api/v1/engines/{engine_id}/document_types/{document_type}/analytics/top_autocomplete_clickthroughs.json
start_date
optional
The first day from which to retrieve top clickthrough autocompletes. Defaults to 2 weeks ago.
end_date
optional
The last day from which to retrieve clickthrough autocompletes. Defaults to the current date.
Example - Get the list of top clickthrough autocompletes conducted each day for a month for the bookstore Engine.
curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/analytics/top_autocomplete_clickthroughs.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 list of top clickthrough autocompletes for the default two week period for the books DocumentType within the bookstore Engine.
curl -X GET 'https://api.swiftype.com/api/v1/engines/bookstore/document_types/books/analytics/top_autocomplete_clickthroughs.json' \
-H 'Content-Type: application/json' \
-d '{
      "auth_token": "YOUR_API_KEY"
    }'
Example Response
[
  ["first-document-id", 132],
  ["second-document-id", 31],
  ["third-document-id", 55]
]

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!