API Key Settings

Ideal Postcodes allows you to control how often your API Key is used via the Security panel on your dashboard.

This is important when you want to control how many lookups you spend per day.


Setting the Right Restrictions

There are two approaches to using your api key within your project. Your key can either be:

  • Private. Lookups are generated from a controlled environment, such as a server belonging to you
  • Public. Lookups are generated from a client (e.g. browser or app), which means embedding the key on the client side

In both scenarios, we strongly recommend you to set both a daily and individual limit on lookups.

If you will be making requests from within your clients browser, we strongly recommend you created a list of "Allowed URLs" from which you can make requests.


API Key Controls

The following controls are provided to limit how your API Key can be used:

Daily Lookup Limits

A limit on the number of lookups your API Key can make per day

  • This limits the number of postcode lookups on your API Key per day. The limit is reset on midnight.
  • This is ideal for controlling the amount you wish to spend on lookups per day.

Your email notification recipients will be notified when you reach 90% or 100% of this cap

Individual Lookup Limits

A limit on the number of lookups an individual user can make on your API Key per day

  • This limits the number of daily requests from an specific IP address. The limit is reset on each IP Address on midnight.
  • This is ideal if you intend on embedding your key on client-side code, such as the jQuery plugin.

IP Address Forwarding

Forward the IP address to be whitelisted for paid API requests

When the the Daily Individual Lookup Limit is enabled, you may also opt to enable IP Address Forwarding. This will limit requests based on the IP address you provide using a HTTP request header named IDPC-Source-IP. If an address is successfully forwarded, your API response will also contain a IDPC-Source-IP header relaying the rate limited IP address.

Malformed IP addresses passed with the IDPC-Source-IP header will return a 400 response.

IP Address Forwarding should be enabled for integrations that require IP based daily limiting, but API requests are proxied through a small number of privately controlled hosts. Without IP Address Forwarding, the IP addresses associated with the proxies themselves will be rate limited rather than the end user.

If IP Address Forwarding is enabled but no IDPC-Source-IP header is provided, the original IP address will be limited as usual.

IP Address Forwarding should not be enabled for client side integrations as this would allow daily rate limiting to be circumvented.

Allowed URLs

A list of web addresses that can perform lookups using your API Key.

  • This list determines the URLs that are allowed to perform lookups on your API Key.
  • E.g. ideal-postcodes.co.uk or ideal-postcodes.co.uk/users/signup
  • This is ideal if you intend on embedding your key on client-side code, such as the jQuery plugin.

Enabling URL whitelisting will also enable CORS.

Whitelisted strings beginning with http:// or https:// will look for matches that start with the string. For instance, https://www.example.com will match https://www.example.com/ as well as https://www.example.com/signup

Whitelisted strings which do not begin with http[s]:// will look for positive substring matches. For instance, .example.com/signup will match https://www.example.com/signup as well as https://app.example.com/signup

Api Key Regeneration

You can also generate a new key through API Key Settings. This will not affect your existing purchases. Requests made on your old key will fail. Please note this is not reversible.

Retention Period (Days)

Your transaction logs will contain some personal information detailed in our data processing section.

We will periodically redact any logs (older than your retention period) of personal data. This includes IP address, address query and URL referer headers.

By default, this retention period is set at 28 days. You may also set the retention period to 0 if you wish to disable retention of any personal data.