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.
Query Parameters
Property | Description |
---|---|
licensee |
Optional Sublicensed keys only. Performs check on API Key & licensee combination. |
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 |
---|---|
available |
boolean Determines whether the key can be used by the requesting agent. Returns false if one of the following conditions are met.
|
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. |