Keys

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 usable via the available property. Use this to discover if the key is useable before making further requests.

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.
  • 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
        },
        "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 Indicator of whether email notifications are enabled or disabled.
automated_topups.enabled boolean Indicator of whether email automated topups have been enabled.
current_purchases object[] A list of non-expired purchases indicating current state representinga 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 email 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. 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.
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.