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 functions depending on the scope: 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
• Autoselects
• Clicks
• Top Queries
• Top Queries with No Results
• Clickthroughs

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.

Searches, 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

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.

Autoselects, 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

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.

Clicks, 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

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.

Top queries, Engine

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

[
  ["most popular query", 101],
  ["second most popular query", 92],
  ["third most popular query", 72]
]

Top queries, DocumentType

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

[
  ["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 that have been submitted to a given 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.

Top no result queries, 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"
      }'

[
  ["most popular query", 101],
  ["second most popular query", 92],
  ["third most popular query", 72]
]

Top no result queries, DocumentType

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

[
  ["most popular query", 55],
  ["second most popular query", 24],
  ["third most popular query", 11]
]

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.

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 data is limited depending on your plan. The Analytics dashboard is limited to a max range of 90 days. If you have more than 90 days worth of data, you will need to export in batches of 90 days.

• Standard: Yesterday - 30 days
• Pro: Yesterday - 180 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 forum!