Analytics queries API
editAnalytics queries API
editReturns queries, number of queries, and clicks received, in descending order.
GET /api/as/v1/engines/{ENGINE_NAME}/analytics/queries
POST /api/as/v1/engines/{ENGINE_NAME}/analytics/queries
// An example JSON payload from the analytics/queries endpoint. { "meta": { "page": { "size": number, "current": number } }, "results": [ { "term": string, "clicks": number, "queries": number } ] }
Top Queries
edit-
page
/size
(optional) - Provide an integer to retrieve a specific number of top results. View example.
Return the top 10 queries over the past 7 days.
Example - A GET
request with no addition parameters.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/queries' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx'
Example Response
{ "results": [ { "term": "everglade", "clicks": 14, "queries": 49 }, { "term": "", "clicks": 0, "queries": 9 }, { "term": "old parks", "clicks": 0, "queries": 3 }, { "term": "eastern parks", "clicks": 0, "queries": 2 }, { "term": "everglade everglade", "clicks": 9, "queries": 1 }, { "term": "clean parks", "clicks": 0, "queries": 1 }, { "term": "heritate sites", "clicks": 2, "queries": 0 }, { "term": "everglade asdfasdf", "clicks": 2, "queries": 0 } ], "meta": { "page": { "size": 8, "current": 1 } } }
Pagination
editSpecify the number of results returned.
Example - A GET
request asking for 20
results using the page
argument with the size
option.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/queries' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "page": { "size": 20 } }'
Example Response
{ "results": [ { ... } ], "meta": { "page": { "size": 20, "current": 1 } } }
Queries Filtering
edit-
filters
(optional) - The filters key is the parent key. If no options are provided underneath it, the top 10 queries over the past 7 days are returned.
-
clicks
(optional) - A boolean, returns queries that have - or have not - received clicks. If true, returns queries with clicks. If false, returns queries without clicks. View example.
-
results
(optional) - A boolean, returns queries that have - or have not - received results. If true, returns queries with results. If false, returns queries without results. View example.
-
tag
(optional) - The Search endpoint can be used to attach tags to your documents. One or more tags can be applied to filter results via the API or within your analytics dashboard. View example.
-
date
(optional) - Specify a range of time. The from and to fields are optional and the expected format is RFC3339. You may omit the time: YYYY-MM-DD. View example.
-
all
(optional) - Nest multiple filters under the all option. View example.
Clicks
editExample - A POST
request with the clicks
filter option. We want to see only queries that have been clicked.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/queries' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "filters": { "clicks": true } }'
Example Response
{ "results": [ { "term": "everglade", "clicks": 14, "queries": 49 }, { "term": "everglade everglade", "clicks": 9, "queries": 1 }, { "term": "taco", "clicks": 2, "queries": 0 }, { "term": "everglade asdfasdf", "clicks": 2, "queries": 0 } ], "meta": { "page": { "size": 4, "current": 1 } } }
Results
editExample - A GET
request with the results
filter option. We want to see only queries that have not returned results.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/queries' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "filters": { "results": false } }'
Example Response
{ "results": [ { "term": "everglade", "clicks": 0, "queries": 8 }, { "term": "grumpy cat", "clicks": 0, "queries": 2 }, { "term": "", "clicks": 0, "queries": 1 } ], "meta": { "page": { "size": 3, "current": 1 } } }
Tag(s)
editWe have a Tags Guide, too.
Single Tag
editExample - A GET
request with the tag
filter option. We want to see how many queries documents with the web
tag received. Tags can be added via the search endpoint.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/queries' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "filters": { "tag": "web" } }'
Example Response
{ "results": [ { "term": "red", "clicks": 0, "queries": 1 }, ], "meta": { "page": { "size": 1, "current": 1 } } }
Multiple Tags
editExample - A GET
request with the tag
filter option and one tag. Tags can be added via the search endpoint.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/queries' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "filters": { "tag": ["web", "mobile"] } }'
Example Response
{ "results": [ { "term": "taco", "clicks": 2, "queries": 0 }, ], "meta": { "page": { "size": 1, "current": 1 } } }
Date
editExample - A POST
request with the date
filters option. Expects results from the earlier date, to the later date.
curl -X POST 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/queries' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "filters": { "date": { "from": "2018-06-15T12:00:00+00:00", "to": "2018-06-19T00:00:00+00:00" } } }'
Example Response
{ "results": [ { "term": "everglade", "clicks": 14, "queries": 49 }, { "term": "", "clicks": 0, "queries": 9 }, { "term": "heritage sites", "clicks": 0, "queries": 3 } ], "meta": { "page": { "size": 3, "current": 1 } } }
Multiple Filters
editExample - A GET
request with the clicks
and results
filter options. We want to see queries that have results and that did not generate any clicks.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/queries' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "filters": { "all": [ { "clicks": false }, { "results": true } ] } }'
Example Response
{ "results": [ { "term": "", "clicks": 0, "queries": 8 }, { "term": "everglade", "clicks": 0, "queries": 3 }, { "term": "old parks", "clicks": 0, "queries": 1 } ], "meta": { "page": { "size": 3, "current": 1 } } } ➜
Full Example
editYou can combine all of the different parameters for granular responses.
Example - A GET
request that includes the page
and filters
arguments. All filters
options are included.
curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/queries' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \ -d '{ "filters": { "all": [ { "clicks": false }, { "date": { "from": "2018-06-15T12:00:00+00:00", "to": "2018-06-19T00:00:00+00:00" } }, { "results": false }, { "tag": ["web", "mobile"] } ] }, "page": { "size": 20 } }'
Example Response
{ "results": [ { ... } ], "meta": { "page": { "size": 20, "current": 1 } } }