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
Site Search Documentation / site search: Analytics
Analytics

Site Search

Guides

Site Search API

API Reference

API Clients

Plugins, Libraries, SDKs

Resources

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.

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

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

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

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

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

Record a clickthrough for a particular result.

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

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!