IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Analytics APIs Analytics counts API »
Elastic Docs › ›API Reference

Analytics clicks API

edit

Analytics clicks API

edit

Returns the number of clicks received by a document in descending order.

GET /api/as/v1/engines/{ENGINE_NAME}/analytics/clicks
POST /api/as/v1/engines/{ENGINE_NAME}/analytics/clicks
// An example JSON payload from the analytics/queries endpoint.
{
  "results": [
    {
      "document_id": string,
      "clicks": number
    }
  ],
  "meta": {
    "page": {
      "size": number,
      "current": number
    }
  }
}

Top Clicks

edit
page/size (optional)
Provide an integer to retrieve a specific number of results.

Return the 10 most clicked results 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/clicks' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx'

Example Response

{
  "meta": {
    "page": {
      "size": 3,
      "current": 1
    }
  },
  "results": [
    {
      "document_id": "5209",
      "clicks": 3
    },
    {
      "document_id": "163",
      "clicks": 2
    },
    {
      "document_id": "6879",
      "clicks": 2
    }
  ]
}

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 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/clicks' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "size": 20
  }
}'

Example Response

{
  "meta": {
    "page": {
      "size": 20,
      "current": 1
    }
  },
  "results": [
    {
      "document_id": "5209",
      "clicks": 3
    },
    {
      "document_id": "163",
      "clicks": 2
    },
    {
      "document_id": "6879",
      "clicks": 2
    },
    {
      "document_id": "9797",
      "clicks": 2
    },
    {
      "document_id": "567",
      "clicks": 1
    },
    ...
  ]
}

By Query

edit

You can provide a query to see clicks for its returned documents.

Example - A GET request with the query filter option. We want to see how many clicks the everglade query received, and for which documents.

curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/clicks' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \
-d '{
  "query": "everglade"
}'

Example Response

{
  "meta": {
    "page": {
      "size": 2,
      "current": 1
    }
  },
  "results": [
    {
      "document_id": "5209",
      "clicks": 3
    },
    {
      "document_id": "6879",
      "clicks": 2
    }
  ]
}

Clicks Filtering

edit
filters (required)
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.
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.

Date

edit

Example - 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/clicks' \
-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": [
    {
      "document_id": "5209",
      "clicks": 3
    }
  ],
  "meta": {
    "page": {
      "size": 1,
      "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 clicks that documents with the web tag received.

curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/clicks' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \
-d '{
  "filters": { "tag": "web" }
}'

Example Response

{
  "results": [
    {
      "document_id": "6879",
      "clicks": 2
    }
  ],
  "meta": {
    "page": {
      "size": 1,
      "current": 1
    }
  }
}
Multiple Tags
edit

Example - A GET request with the tag filter option containing multiple tags. We want to see how many clicks that documents with the web and mobile tags received.

curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/clicks' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \
-d '{
  "filters": { "tag": ["web", "mobile"] }
}'

Example Response

{
  "results": [
    {
      "document_id": "163",
      "clicks": 2
    },
  ],
  "meta": {
    "page": {
      "size": 1,
      "current": 1
    }
  }
}

Multiple Filters

edit

Example - A GET request with the date and tag filter options. We want to see which documents have been clicked and how many times, between a time-range, for documents containing two different tags.

curl -X GET 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/clicks' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \
-d '{
  "filters": {
    "all": [
      {
        "tag": ["mobile", "web browser"]
      }, {
        "date": {
          "from": "2018-07-02T00:00:00+00:00",
          "to": "2018-07-06T00:00:00+00:00"
        }
      }
    ]
  }
}'

Example Response

{
  "results": [
    {
      "document_id": "9797",
      "clicks": 2
    }
  ],
  "meta": {
    "page": {
      "size": 1,
      "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 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/api/as/v1/engines/national-parks-demo/analytics/clicks' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxxxxxx' \
-d '{
  "query": "everglade",
  "filters": {
    "all": [
      {
        "tag": ["mobile", "web browser"]
      }, {
        "date": {
          "from": "2018-07-02T00:00:00+00:00",
          "to": "2018-07-06T00:00:00+00:00"
        }
      }
    ]
  },
  "page": {
    "size": 5
  }
}'

Example Response

{
  "results": [
    {
      "document_id": "9797",
      "clicks": 2
    }
  ],
  "meta": {
    "page": {
      "size": 1,
      "current": 1
    }
  }
}
« Analytics APIs Analytics counts API »