ℹ️ For new users, we recommend using our native Elasticsearch tools, rather than the standalone App Search product. We are actively developing new features and capabilities in the Elastic Stack to help you build powerful search applications. Refer to Elasticsearch feature recommendations for more information.
« Analytics counts API API logs API »
Elastic Docs › ›API Reference

Analytics queries API

edit

Analytics queries API

edit

Returns queries, number of queries, and clicks received, in descending order.

GET <ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/{ENGINE_NAME}/analytics/queries
POST <ENTERPRISE_SEARCH_BASE_URL>/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 '<ENTERPRISE_SEARCH_BASE_URL>/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": 6
    },
    {
      "term": "everglade everglade",
      "clicks": 5,
      "queries": 5
    },
    {
      "term": "clean parks",
      "clicks": 0,
      "queries": 3
    },
    {
      "term": "heritate sites",
      "clicks": 2,
      "queries": 2
    },
    {
      "term": "everglade asdfasdf",
      "clicks": 2,
      "queries": 2
    }
  ],
  "meta": {
    "page": {
      "size": 8,
      "current": 1
    }
  }
}

Pagination

edit

Specify the number of results returned.

Example - A GET request asking for 20 results using the page argument with the size option.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/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: YYYY-MM-DDTHH:mm:ssZ. View example.
all (optional)
Nest multiple filters under the all option. View example.
Clicks
edit

Example - A POST request with the clicks filter option. We want to see only queries that have been clicked.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/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": 15
    },
    {
      "term": "taco",
      "clicks": 2,
      "queries": 5
    },
    {
      "term": "everglade asdfasdf",
      "clicks": 2,
      "queries": 4
    }
  ],
  "meta": {
    "page": {
      "size": 4,
      "current": 1
    }
  }
}
Results
edit

Example - A GET request with the results filter option. We want to see only queries that have not returned results.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/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)
edit

We have a Tags Guide, too.

Single Tag
edit

Example - 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 '<ENTERPRISE_SEARCH_BASE_URL>/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
edit

Example - A GET request with the tag filter option and one tag. Tags can be added via the search endpoint.

curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/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": 5
    },
  ],
  "meta": {
    "page": {
      "size": 1,
      "current": 1
    }
  }
}
Date
edit

Example - A POST request with the date filters option. Expects results from the earlier date, to the later date.

curl -X POST '<ENTERPRISE_SEARCH_BASE_URL>/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

edit

Example - 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 '<ENTERPRISE_SEARCH_BASE_URL>/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

edit

You 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 '<ENTERPRISE_SEARCH_BASE_URL>/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
    }
  }
}
« Analytics counts API API logs API »