Analytics
The Analytics endpoints allow you to extract and record analytics information for a search engine. These endpoints provide the same analytics details that are available in the Swiftype dashboard.
Each endpoint has two different forms depending on the scope for which the data is returned:
| URL Format | Data scope |
|---|---|
/api/v1/engines/{engine_id}/analytics/{method}.json |
Engine |
/api/v1/engines/{engine_id}/document_types/{document_type_id}/analytics/{method}.json |
Document type |
In case of invalid or missing parameters, the API will return an HTTP 400 code and a JSON message explaining the validation error.
Searches
This endpoint returns the number of searches that occurred on a given day. Note that the maximum time range between the start and end dates is 30 days.
Options
| Option | Default | Description |
|---|---|---|
start_date |
2 weeks ago | The first date from which you would like analytics |
end_date |
today | The last date from which you would like analytics |
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-03"
}'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"
}'Autoselects
This endpoint returns the number of autoselects (selections or clicks on an item in the autocomplete dropdown) that occurred on a given day. Note that the maximum time range between the start and end dates is 30 days.
Options
| Option | Default | Description |
|---|---|---|
start_date |
2 weeks ago | The first date from which you would like analytics |
end_date |
today | The last date from which you would like analytics |
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-03"
}'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"
}'Clicks
This endpoint returns the number of clickthroughs (clicks on an item on the search results page) that occurred on a given day. Note that the maximum time range between the start and end dates is 30 days.
Options
| Option | Default | Description |
|---|---|---|
start_date |
2 weeks ago | The first date from which you would like analytics |
end_date |
today | The last date from which you would like analytics |
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-03"
}'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"
}'Top queries
This endpoint returns a paginated list of the queries that have been submitted to a given engine
in a given time period (between start_date and end_date). The result is
an Array of [ "query", query_count ] arrays of in a descending order by query count.
DEPRECATION NOTICE: Please note, that top_queries_in_range API call is now deprecated and should be replaced with top_queries if needed.
Options
| Option | Default | Description |
|---|---|---|
start_date |
2 weeks ago | The first day of the range (formatted like 2012-01-01) |
end_date |
today | The last day of the range (formatted like 2012-01-01) |
page |
1 | Page number, numeration starts from 1. Maximum page number is 50. |
per_page |
20 | Number of items per page. Maximum number of items per page is 100. |
Please note, that the total maximum number of queries you are allowed to page through is 1000.
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": "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
This endpoint returns a paginated list of the queries with no results that have been submitted
to a given engine in a given time period (between start_date and end_date).
The result is an Array of [ "query", query_count ] arrays of in a descending order by
query count.
Options
| Option | Default | Description |
|---|---|---|
start_date |
2 weeks ago | The first day of the range (formatted like 2012-01-01) |
end_date |
today | The last day of the range (formatted like 2012-01-01) |
page |
1 | Page number, numeration starts from 1. Maximum page number is 50. |
per_page |
20 | Number of items per page. Maximum number of items per page is 100. |
Please note, that the total maximum numner of queries you are allowed to page through is 1000.
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]
]Recording clickthroughs
This endpoint allows you to record a clickthrough to a particular result. Note that our JavaScript libraries do this by default, but you can implement these endpoints if you are using another client.
Options
| Option | Required | Description |
|---|---|---|
id |
yes | The external_id or ID of the document the user clicked on |
q |
yes | The query that led to the 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": "1234",
"q": "Gatsby"
}'