Keys API

A key instance resource represents an Ideal Postcodes API Key. Use this resource to query for information regarding an API Key.

Check Key Usability

GET /keys/:key

Returns public information on key. Currently only returns whether the key is currently useable via the available property. Use this to discover if the key is useable before making further requests.

You may pass both API Keys (beginning ak_) and Sublicensed Keys (beginning sl_).

Query Parameters

Property	Description
`licensee`	Optional Sublicensed keys only. Performs check on API Key & licensee combination. Deprecated as of March 2021. You may now pass any licensee key beginning `sl_` as the `:key` resource identifier

Request

https://api.ideal-postcodes.co.uk/v1/keys/iddqd

 # Or in your terminal
curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd

Response

{ 
    "result": { 
        "available": true 
    }, 
    "code": 2000, 
    "message": "Success"
}

Property Description

Property	Description
`available`	`boolean` Determines whether the key can be used by the requesting agent. Returns false if one of the following conditions are met. Key has no lookups remaining Daily limit has been reached on the key Daily individual limit has been reached Key is not being used via an authorised URL (Sublicensed key only) Key has a valid licensee attached (Sublicensed key only) Key is not being used via an authorised URL specified by licensee

available

boolean Determines whether the key can be used by the requesting agent. Returns false if one of the following conditions are met.

Key has no lookups remaining
Daily limit has been reached on the key
Daily individual limit has been reached
Key is not being used via an authorised URL
(Sublicensed key only) Key has a valid licensee attached
(Sublicensed key only) Key is not being used via an authorised URL specified by licensee

Testing

To test your implementation of our API, you may use the following test keys.

iddqd Availability will return as true
idkfa Availability will return as false

Check Key Details

GET /keys/:key

Returns private information on a key. Details include the number of lookups remaining, current limits and limit utilisation as well as other information.

This method requires a user_token, which can be found on your accounts page.

Query Parameters

Property	Description
`user_token`	Required unless authenticating with Authorization HTTP Header.

Request

https://api.ideal-postcodes.co.uk/v1/keys/iddqd?user_token=my_secret_token

curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd \
        -d "user_token=my_secret_token"

Response

{
    "result": {
        "lookups_remaining": 8288,
        "daily_limit": {
            "limit": 1000,
            "consumed": 361
        },
        "individual_limit": {
            "limit": 15
        },
        "allowed_urls": [
            "https://www.foo.com",
            "https://www.bar.co.uk"
        ],
        "notifications": {
            "emails": ["baz@bar.co.uk"],
            "enabled": true
        },
        "automated_topups": {
            "enabled": true
        },
        datasets": {
            "paf": true,
            "mr": false,
            "nyb": false
        },
        "current_purchases": [
            {
                "expires":"2015-07-22T22:26:50.100Z",
                "purchased":20000,
                "consumed":298
            },
            {
                "expires":null,
                "purchased":1000,
                "consumed":0
            }
        ]
    },
    "code": 2000,
    "message": "Success"
}

Property	Description
`lookups_remaining`	`number` Number of lookups left on your key.
`daily_limit.limit`	`number` or `null` The daily lookup limit currently set on your key. `null` means the limit is currently disabled.
`daily_limit.consumed`	`number` Number of lookups performed today which count towards your daily limit.
`individual_limit.consumed`	`number` or `null` Limit set on the number of lookups that can be performed from a single IP address. `null` means the limit is currently disabled.
`daily_limit.consumed`	`number` Number of lookups performed today which count towards your daily limit.
`allowed_urls`	`string[]` A list of URLs from which lookups can be requested.
`notifications.emails`	`string[]` A list of email addresses designated by you to receive notifications about this key.
`notifications.enabled`	`boolean` Indicates email notifications are enabled.
`automated_topups.enabled`	`boolean` Indicates email automated topups are enabled.
`datasets.paf`	`boolean` Indicates access to Postcode Address File dataset.
`datasets.mr`	`boolean` Indicates access to Multiple Residence dataset.
`datasets.nyb`	`boolean` Indicates access to Not Yet Built dataset.
`current_purchases`	`object[]` A list of non-expired purchases indicating current state representing a list of recent purchases
`current_purchase.expires`	`string` or `null` The date when this purchase will expire in simplified extended ISO format (ISO 8601). This is typically 365 days from the time of first use. This field will be `null` if the purchase has not yet been used.
`current_purchase.purchased`	`number` Number of procured lookups from this purchase.
`current_purchase.consumed`	`number` Number of consumed lookups off this purchase.

Monitor Key Usage

GET /keys/:key/usage

Reports usage information on a key for paid lookups.

This method requires a user_token, which can be found on your accounts page.

A maximum interval of 90 days can be provided for analysis. If no start or end date is provided, the last 21 days will be used as the default interval.

Query Parameters

Property	Description
`user_token`	Required unless authenticating with Authorization HTTP Header.
`start`	Optional. An start date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no start time is provided, the start time will be assigned to a time 21 days prior to the end time.
`end`	Optional. An end date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no end time is provided, the current time will be used.
`tags`	Optional. An comma separated list of tags you wish to query for. This is useful if you want to specify the circumstances in which the request was made. If multiple tags are specified, the analysed dataset will only comprise of requests for which all the tags are satisfied - i.e. searching `foo,bar` will only query requests which tagged both `"foo"` and `"bar"`.
`licensee`	Optional. Sublicensed keys only. This will restrict the analysed dataset to a specific licensee.

Request

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

curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/usage \
    -d "user_token=my_secret_token"

Response

{
    "result": {
        "start": "2015-01-22T15:08:06.609Z",
        "end": "2015-02-12T15:08:06.609Z",
        "total": 132,
        "dailyCount": [{
            "date": "2015-02-12T00:00:00.000Z",
            "count": 1
        }, {
            "date": "2015-02-11T00:00:00.000Z",
            "count": 1
        }, {
            "date": "2015-02-10T00:00:00.000Z",
            "count": 6
        }, {
            "date": "2015-02-09T00:00:00.000Z",
            "count": 10
        }, {
            "date": "2015-02-08T00:00:00.000Z",
            "count": 2
        }, {
            "date": "2015-02-07T00:00:00.000Z",
            "count": 1
        }, {
            "date": "2015-02-06T00:00:00.000Z",
            "count": 13
        }, {
            "date": "2015-02-05T00:00:00.000Z",
            "count": 11
        }, {
            "date": "2015-02-04T00:00:00.000Z",
            "count": 13
        }, {
            "date": "2015-02-03T00:00:00.000Z",
            "count": 3
        }, {
            "date": "2015-02-02T00:00:00.000Z",
            "count": 3
        }, {
            "date": "2015-02-01T00:00:00.000Z",
            "count": 1
        }, {
            "date": "2015-01-31T00:00:00.000Z",
            "count": 1
        }, {
            "date": "2015-01-30T00:00:00.000Z",
            "count": 1
        }, {
            "date": "2015-01-29T00:00:00.000Z",
            "count": 16
        }, {
            "date": "2015-01-28T00:00:00.000Z",
            "count": 9
        }, {
            "date": "2015-01-27T00:00:00.000Z",
            "count": 20
        }, {
            "date": "2015-01-26T00:00:00.000Z",
            "count": 3
        }, {
            "date": "2015-01-24T00:00:00.000Z",
            "count": 3
        }, {
            "date": "2015-01-23T00:00:00.000Z",
            "count": 10
        }, {
            "date": "2015-01-22T00:00:00.000Z",
            "count": 4
        }]
    },
    "code": 2000,
    "message": "Success"
}

Property	Description
`start`	`string` Start date in ISO 8601 format.
`end`	`string` End date in ISO 8601 format.
`total`	`number` Total of paid lookups performed in specified period.
`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.

Download Usage History (CSV)

GET /keys/:key/lookups

Returns a CSV download of lookups performed and associated information.

Note that the Content-Type returned will be CSV (text/csv). For a non 200 response, the Content-Type will revert to JSON with the error code and message embedded.

This method requires a user_token, which can be found on your accounts page.

A maximum interval of 90 days may be specified. If no start or end date is provided, the last 21 days will be used as the default interval.

GDPR Update

After May 2018, the API will begin to redact IP Address, Search Term and URL data that is older than 28 days from our stores on a weekly basis as part of our new data protection strategy. This means the aforementioned data points will no longer be retrievable from this API if it is more than 28 days old.

Reach out to us by mail or chat if you would like to modify this 28 day window or prefer this data not be collected at all.

Query Parameters

Property	Description
`user_token`	Required unless authenticating with Authorization HTTP Header.
`start`	Optional. A start date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no start time is provided, the start time will be assigned to a time 21 days prior to the end time.
`end`	Optional. An end date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no end time is provided, the current time will be used.
`licensee`	Optional. Sublicensed keys only. This will restrict the analysed dataset to a specific licensee.

Request

https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups?user_token=my_secret_token

curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups \
    -d "user_token=my_secret_token"

Response

2015-02-21T16:05:22.991Z,82.85.128.18,SW12AA,https://www.example.com/,Postcode Lookup,
2015-02-21T16:05:38.298Z,82.85.128.18,10 Downing Street London,https://www.example.com/,Address Lookup,CRM
2015-02-21T16:06:49.227Z,82.85.128.18,OX44PP,https://www.example.com/,Postcode Lookup,"Website,Live"
2015-02-21T16:07:02.706Z,82.85.128.18,PL9 9HE,https://www.example.com/,Postcode Lookup,

Column	Description
Date	The date the lookup was made in ISO 8601 format.
IP Address	Originating IP Address of the request request.
Search Term	The search query used (e.g. postcode or address fragment).
URL	The URL from which the request was made (if applicable).
Search Type	A description of the type of search that was made.
Tags	A list of tags associated with this request, concatenated by commas.

Documentation

Keys API

Check Key Usability

Query Parameters

Request

Response

Testing

Check Key Details

Query Parameters

Request

Response

Monitor Key Usage

Query Parameters

Request

Response

Download Usage History (CSV)

GDPR Update

Query Parameters

Request

Response