Open Nav

What is a Lookup?

How lookups are counted across Ideal Postcodes address search and validation APIs

Updated 5 Mar 2020

Summary

  • Every API Key on an account has its own Lookup Balance
  • A postcode search with addresses counts as 1 lookup
  • An address search with results counts a 1 lookup
  • A postcode or address search that yields no addresses does not affect your lookup balance
  • An autocomplete query that returns suggestions counts as 0 lookups
  • Resolving the full address by UDPRN or UMPRN counts as 1 lookup
  • Extracting autocomplete suggestions without resolving for a specific address is, unfortunately, a Terms of Service violation.
  • We provide a number of test methods that do not affect your balance and return test data.

Lookup Balance

Each account can produce one or more API Keys. These Keys are used to access addressing data.

Each Key has its own lookup balance. This means usage from one key does not affect the balance of the other.

A lookup balance is our form of credit, often purchased ahead of time, which generally permits one valid address search.

Postcode Search

Each postcode search which returns at least one premise deducts one lookup from your Key balance.

A postcode search can return a maximum of 100 premises. If you are using the Multiple Residence dataset and retrieve more than 100 addresses, each additional page is 1 lookup.

Invalid postcodes do not affect your balance.

Our canonical test postcode, which does not affect your balance, is ID1 1QD

Address Search

Each address search that returns at least one premise deducts 1 lookup from your key.

Empty address searches do not affect your balance.

Our test address query is also ID1 1QD

Autocomplete

Retrieving a list of suggestions for a given address query does not affect your Lookup Balance. However, resolving a full address for a suggestion deducts 1 lookup.

Note that the suggestion API must be used in conjunction with the address resolution APIs. i.e. you must intend to resolve a full address for at least one of your search suggestions. Consistently failing to do so violates our Terms of Service.

Not Sure?

Drop by our chat page and someone can walk you through it.