Developer FAQs

Can I publicly expose my API Key by embedding it in some client side code?

Yes. Many people choose this route due to faster response times and no server side code to handle postcode queries.

However, you need to take appropriate measures to limit your token so it cannot be misused by others. Please see our documentation on token settings to find out more.

Why do my purchased balances need to expire?

Our licence with Royal Mail determines that each batch of lookups you purchase expire 12 months after you first use it. Furthermore, all Royal Mail data suppliers need to comply with the same limitations.

We will however do what we can to push the expiry date of your purchases to as far back into future as possible. For example:

  • The expiry timer on your purchase will only start at the moment you start using that batch
  • We will try wherever possible to deduct lookups from your earliest purchased balances
  • The expiry date of a purchase is independent of your previous purchases, i.e. subsequent purchases will not be affected by the expiry of earlier purchases

Can I get my data in XML (or some other data format)?

Not right now. It's all in JSON. We do not have plans to use other formats. If you think there is a good reason for us to support alternative standards please write to us and let us know.

What is Multiple Residence?

Royal Mail’s Postcode Address File (PAF) is the most complete listing of all addresses in the UK with around 30 million delivery points.

Alongside PAF is an dataset of 730,000 additional dwellings which reside behind a shared delivery point. This dataset is called Multiple Residence and it is essentially a list of dwellings that use the same mailbox.

A typical example is a three-storey residential premise converted into flats where the building owner has yet to assign individual delivery points to each flat. This building will have a single delivery point (i.e. the building’s address) which is listed on PAF; however, it will also have dwellings which share the same delivery point (e.g. Basement flat, Flat 1, Flat 2) which will only be listed on the Multiple Residence dataset.

Around 180,000 (0.6%) PAF premises will have multiple dwellings attached to a single delivery point. Of these premises, the average number of additional dwellings is 4.

Please note that it is often not the case that dwellings which in the same building can only be found in the Multiple Residence dataset. PAF, for example, contains the addresses of over 1.9 million flats in the UK. This is because established buildings, which provide multiple dwellings, often create individual delivery points for each household.

See our MR guide to find out more.

When should I use Multiple Residence?

The Postcode Address File alone will be adequate to identify a premise for most use cases, like completing the delivery of mail or parcels. In the case of addresses listed under the Multiple Residence dataset, any deliveries typically are forwarded internally to the correct occupant.

Multiple Residence, on the other hand, is ideal for establishing the exact number of households within a particular premise. Typically public utilities (ISPs, water, energy) would like to know how many potential customers reside at an address.

If you wish to present a postcode lookup dropdown (i.e. using the /v1/postcodes API), we highly recommend the standard PAF dataset without Multiple Residence. A small number of postcodes contain a lot of Multiple Residence data, making dropbox selection unwieldy.

How do I retrieve both Postcode Address File and Multiple Residence addresses from my API queries?

You will need to create a new separate Multiple Residence Key (via the your dashboard). Due to the different licensing arrangements around Multiple Residence data, the incurred licensing fees are generally higher than just using PAF.

Multiple Residence data is only updated on a monthly basis whereas the Postcode Address File is updated daily.

What is Not Yet Built?

The Not Yet Built (NYB) dataset is outside of the standard Postcode Address File (PAF). It lists residential and commercial premises that are under construction or in the planning stage.

Royal Mail works with each UK authority supporting planning departments to define street names and addresses. The NYB dataset identifies buildings still in construction or in the planning stage.

See our NYB guide to find out more.

What are external or internal lookups?

The internal and external lookups distinction only applied prior to April 2015. Before then, different uses of PAF required different licensing and vastly different costs.

Since then, PAF licensing has been drastically simplified. Using the same license, you may draw address data for both internal and external use for the same price.