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.
- 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.
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"
}'
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.
- 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.
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.
- 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.
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"
}'
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
Returns the number of clicks a search received by Engine or for a DocumentType.
- 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.
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"
}'
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.
- 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.
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"
}'
[
["most popular query", 101],
["second most popular query", 92],
["third most popular query", 72]
]
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"
}'
[
["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.
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"
}'
[
["most popular query", 101],
["second most popular query", 92],
["third most popular query", 72]
]
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"
}'
[
["most popular query", 55],
["second most popular query", 24],
["third most popular query", 11]
]
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
- 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.
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
- 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 theid
parameter. - q
- required
- The query that lead to the clicked document.
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!