Key Usage

GET/v1/keys/{key}/usage

Reports the number of lookups a key consumed over a date range, as a total and a daily breakdown.

The range defaults to the last 21 days. start and end take UNIX timestamps in milliseconds, and end defaults to the current time. The maximum range is 90 days.

Query at most three tags at once.

Path parameters

key string

API Key

The API Key to retrieve. Begins ak_.

Example ak_test

Query parameters

user_token string optional

Private User Token

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically begins uk_...

Example uk_B59ScW1p1HHouf1VqclEPZUx

start integer optional

Start Timestamp

A start date/time in the form of a UNIX Timestamp in milliseconds. E.g. 1418556452651

Format int64Example 1418556452651

end integer optional

End Timestamp

An end date/time in the form of a UNIX Timestamp in milliseconds. E.g. 1418556477882

Format int64Example 1418556492651

tags string optional

Tags

A comma separated list of tags to query over.

Useful if you want to specify the circumstances in which the request was made.

If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching "foo,bar" queries only requests tagged both "foo" and "bar".

Example foo,bar

licensee string optional

Licensee Key

Uniquely identifies a licensee.

Example sl_hk71kco54zGSGvF9eXXrvvnMOLLNh

Response

result is a single object containing the total lookup count and a daily breakdown for the requested period.

• result KeyUsageResult

  • start string

    Start date in ISO 8601 format.

    Example

    2015-01-22T15:08:06.609Z

  • end string

    End date in ISO 8601 format.

    Example

    2015-01-23T15:08:06.609Z

  • total integer

    Total of paid lookups performed in specified period.

    Format

    int32

    Example

    132

  • dailyCount object[]

    An array of objects representing number of paid lookups made on specific days, ordered by date. Each object contains a date attribute, which represents the day and a count attribute, which represents the number of paid lookups made on that day.

    • date string

      Example

      2015-01-22T00:00:00.000Z

    • count integer

      Format

      int32

      Example

      132

The result sits inside the standard { result, code, message } envelope — see the API reference for the wrapper format.

Request

URL

https://api.ideal-postcodes.co.uk/v1/keys/ak_test/usage?user_token=uk_secret

curl

curl -G 'https://api.ideal-postcodes.co.uk/v1/keys/ak_test/usage' \
  -d 'user_token=uk_secret'

JavaScript

const response = await fetch(
  'https://api.ideal-postcodes.co.uk/v1/keys/ak_test/usage?' +
  new URLSearchParams({
    user_token: 'uk_secret',
  })
);

const { result } = await response.json();

Python

import requests

response = requests.get(
    "https://api.ideal-postcodes.co.uk/v1/keys/ak_test/usage",
    params={
        "user_token": "uk_secret",
    },
)
result = response.json()["result"]

Ruby

require "net/http"
require "json"

uri = URI("https://api.ideal-postcodes.co.uk/v1/keys/ak_test/usage")
uri.query = URI.encode_www_form(user_token: "uk_secret")
result = JSON.parse(Net::HTTP.get(uri))["result"]

PHP

<?php
$response = file_get_contents(
  "https://api.ideal-postcodes.co.uk/v1/keys/ak_test/usage?" .
  http_build_query([
    "user_token" => "uk_secret",
  ])
);
$result = json_decode($response, true)["result"];

Response

200 OK

{
  "result": {
    "start": "2015-01-22T15:08:06.609Z",
    "end": "2015-01-23T15:08:06.609Z",
    "total": 132,
    "dailyCount": [
      {
        "date": "2015-01-22T00:00:00.000Z",
        "count": 132
      }
    ]
  },
  "code": 2000,
  "message": "Success"
}

400 Bad Request

response.json

{
  "code": 4000,
  "message": "Invalid date range"
}