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"
}'
Autocompletes
How often a document was autocompleted in a dropdown menu.
Top Search Autocompletes
Retrieve top search autocompletes data by Engine or DocumentType.
- 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.
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"
}'
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"
}'
[
["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.
- 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.
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"
}'
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"
}'
[
["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.
- 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]
]
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.
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
- 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!