Skip to main content
API docs by Redocly

API Reference - AddressZen (3.1.0)

Download OpenAPI specification:Download

Support: support@addresszen.com URL: https://addresszen.com/support License: AGPLv3 Terms of Service
More on our APIs, libraries with guides and examples

Getting Started

Overview

Access

All API methods are either a GET, POST or OPTIONS request.

The API communicates over both HTTPS and plain HTTP using IPv4 and IPv6.

We recommend using HTTPS only although HTTP is available.

We use appropriate HTTP status codes where possible to indicate the request status.

Rate Limiting

Each IP address is rate limited at 30 requests per second. Tripping the rate limit will result in a 503 response.

The autocomplete API also has an additional rate limit.

If you expect to breach the limit please contact us and we can move you to an endpoint with a higher limit.

JSONP

JSONP requests are supported. Include a callback= in your request as a query parameter. Your results return wrapped in a function designated by your request.

Authentication

Most requests require an API key for authentication. Authenticate by passing an api_key as part of the query string. For example:

api.addresszen.com/v1/autocomplete/addresses?api_key=iddqd&q=parkside

Alternatively, authentication can be transmitted via the Authorization header using the following scheme:

Authorization: api_key="iddqd" [other_key="foo"]

Versioning

This API is versioned with a simple prefix in the URL. The current version is /v1/. We will maintain backwards-compatibility by releasing breaking changes under a new version.

Please note that the following changes are backwards-compatible:

  • Adding new properties to existing API responses
  • Adding new API endpoints
  • Adding new optional request parameters to existing API endpoints
  • Changing the order of properties in existing API responses
  • Changing the autocomplete address suggestion format

Error Handling

A successful lookup is accompanied with a HTTP status code of 200 and a response code of 2000 (found in the body).

An error has occurred if the HTTP status code is not 200. Errors can range from a benign 404 (resource not found) to more urgent errors (your API Key ran out of credit, failed authentication, etc).

Testing

Each new account comes with a free test balance. Contact us if you need more for testing and integration.

Community Key

Our documentation and demos make heavy use of our community key iddqd. This allows for convenient access for trialing the API.

Many restrictions on this key are relaxed to allow developers make test requests. This key has a limit of 15 lookups per IP address per day as well as a daily usage cap. If you hit any limit restrictions, you can continue testing the API by creating a key of your own and using our free test methods.

Please be kind with the community key. We're trusting everyone to use it responsibly so that other developers may trial the API. Thank you!

Metadata

Requests that affect your balance may be annotated with arbitrary metadata. This data is stored along with your lookup history and can be queried at a later date via the API or the dashboard. We call the ability to label your requests tagging.

Response Codes

The API returns two indicators to help you to determine the status of each HTTP request.

The first is the HTTP Status, which is found in the status-line of all HTTP requests. The API will return status codes that adhere to HTTP /1.1 Specifications wherever possible.

2XX status codes indicates success while 4XX and 5XX indicate client and server errors respectively.

The second is the API response code, which can be found in the code property of the response body. This code will provide a more specific reason if a failure has occurred and can point you in the right direction when debugging.

Please use the glossary of code numbers and HTTP status codes below when debugging your requests.

200 Request Success

HTTP Code API Code Description
200 2000 Success. Request was completed successfully.

400 Bad Request

The request could not be understood due to some input error.

HTTP Code API Code Description
400 4000 Invalid syntax submitted. Some part of your request was malformed or did not match our specifications.
400 4001 Validation failed on your submitted data. Some of the data you provided did not meet our validation requirements, e.g. string length.
400 4005 Invalid start date. Please ensure start dates are provided as a UTC Timestamp in milliseconds.
400 4006 Invalid end date. Please ensure end dates are provided as a UTC Timestamp in milliseconds.
400 4007 Invalid date range. Check if your start and end dates are in the right order.
400 4008 Invalid date range. Check that your date range is 90 days or less.
400 4009 Too many tags. Please specify no more than 3 tags to query.

401 Unauthorised

Authorization credentials are not valid.

HTTP Code API Code Description
401 4010 Invalid Key. The api_key you provided is not valid.
401 4011 Requesting URL not on whitelist. The cross domain request is not coming from a whitelisted URL. You can update or disable your allowed URLs via your Key settings.
401 4012 Failed user authentication. Invalid user_token presented.
401 4013 Licensee Key is required. Sublicensed keys require you need to present licensee credentials via the licensee parameter.

402 Request Failed

Your request is well-formed but are not able to complete your request for another reason.

HTTP Code API Code Description
402 4020 Key balance depleted. You're out of lookups on your API Key.
402 4021 Limit reached. One of your lookup limits has been breached for today. This could either be your total daily limit on your key or the individual IP limit. You can either wait for for the limit to reset (after a day) or manually disable or increase your limit.

404 Resource Not Found

The resource you requested does not exist.

HTTP Code API Code Description
404 4040 Postcode not found. The postcode you have submitted does not exist.
404 4041 User not found. Your user could not be identified given the credentials you presented.
404 4042 Key not found. Your key could not be identified given the credentials you presented.
404 4044 No UDPRN found. No address is associated with the UDPRN queried
404 4045 No licensee found. Your licensee could not be identified given the credentials you presented.
404 4046 No UMPRN found. No Multiple Residence premise is associated with the UMPRN queried.

500 Server Error

A error occurred on our server.

HTTP Code API Code Description
500 5000 An error occurred on our end. These errors are logged and queued so we can understand what went wrong. However, if you need speedy resolution please email support
500 5001 Akin to 5000.
500 5002 The server took too long to process on our end, so we aborted the request. You may retry the request.

Find Address

The address autocomplete API returns a list of address suggestions that match the query ordered by relevance.

This API can be used to power realtime address finders, also known as address autofill or address autocomplete.

Consider using our Address Autocomplete JavaScript libraries to add address lookup to a form in moments.

Implementing Address Autocomplete

Rapid address autocompletion using our Address Autocomplete API is a 2 step process.

  1. Retrieve partial address suggestions via /autocomplete/addresses
  2. Retrieve the entire address with the ID provided in the suggestion

Step 2 will decrement your lookup balance.

Please note, this API is not intended to be a free standalone resource.

Filters

You can strictly narrow your result by adding filters to your querystring. For instance, you can restrict to postcode SW1A 2AA by appending postcode=sw1a2aa.

If a filter term is invalid, e.g. postcode=SW1A2AAA, then an empty result set is returned and no lookup is incurred.

You can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: postcode_outward=e1,e2,e3. Multiple terms are OR'ed, i.e. the matching result sets are combined.

All filters can accept multiple terms unless stated otherwise below.

Filters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: su_organisation_indicator=Y&postcode_area=n. Multiple filters are AND'ed, i.e. each additional filter narrows the result set.

A maximum of 10 terms are allowed across all filters.

Biases

You can boost certain addresses results that match specific address criteria. All bias searches are prefixed with bias_.

Biasing (unlike filtering) also allow unmatched addresses to appear with lower precedence.

For instance, can boost addresses with postcode areas SW and SE by appending bias_postcode_area=SW,SE.

No bias effect applies to bias terms that are invalid. e.g. bias_postcode=SW1A2AAA

You may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: bias_postcode_outward=e1,e2,e3.

All biases can accept multiple terms unless stated otherwise below.

A combined maximum of 5 terms are allowed across all biases.

Suggestion Format

The suggestion format is prone to change over time. Attempts to parse the suggestion may result in your integration breaking. Instead use the suggestion as-is.

Rate Limiting

You can make up to 3000 requests to the autocomplete API within a 5 minute span. The HTTP Header contains information on your current rate limit.

Header Description
X-RateLimit-Limit The maximum number of requests that can be made in 5 minutes
X-RateLimit-Remaining The remaining requests within the current rate limit window
X-RateLimit-Reset The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds

Pricing

This API currently does not affect your balance. However, resolving a suggestion into a full address requires a paid request.

Please note, this API is not intended as a standalone free resource. Integrations that consistently make autocomplete requests without a paid request to resolve an address may be disrupted via tightened rate limits. Continued misuse will result in account suspension.

query Parameters
api_key
string (API Key)
Example: api_key=ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

query
string

Specifies the address you wish to query. Query can be shortened to q=

context
string (Context)

Limits search results within a geographical boundary or country.

limit
integer <int32> (Limit) [ 1 .. 100 ]
Default: 10
Example: limit=5

Limits number of address suggestions unless a postcode is detected. In this instance entire list of addreses for that postcode is returned.

postcode_outward
string (Postcode Outward)
Example: postcode_outward=1AA

Filter by outward code.

postcode
string (Postcode)
Example: postcode=SW1A 2AA

Filter by postcode. Can be combined with query to perform a postcode + building number/name search.

postcode_area
string (Postcode Area)
Example: postcode_area=SW

Filter by postcode. Can be combined with query to perform a postcode + building number/name search.

postcode_sector
string (Postcode Sector)
Example: postcode_sector=SW1A 2

Filter by postcode sector, the outward code plus first numeric of the inward code.

post_town
string (Post Town)
Example: post_town=London

Filter by town.

uprn
integer (UPRN)
Example: uprn=100023336956

Filters by UPRN. Does not accept comma separated terms. Only a single term is permitted

country
string (Country)
Example: country=England

Filter by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.

postcode_type
string (Country)
Example: postcode_type=L

Filter by Postcode Type. Useful for separating organisational and residential addresses

su_organisation_indicator
string (SU Organisation Indicator)
Example: su_organisation_indicator=Y

Filter by Organisation Indicator. Useful for separating organisational and residential addresses

box
string (Box)
Example: box=2.095,57.15,-2.096,57.14

Restrict search to a geospatial box determined by the "top-left" and "bottom-right" gelocations. Only one geospatial box can be provided.

bias_postcode_outward
string (Bias Postcode Outward)

Bias by outward code

bias_postcode
string (Bias Postcode)
Example: bias_postcode=/addresses?postcode=SW1A2AA&q=10

Bias by postcode. Can be combined with query to perform a postcode + building number/name search.

bias_postcode_area
string (Bias Postcode Area)
Example: bias_postcode_area=The postcode area of SW1A 2AA and N1 6RT are SW and N respectively

Bias by postcode area, the first one or two non-numeric characters of a postcode.

bias_postcode_sector
string (Bias Postcode Sector)
Example: bias_postcode_sector=SW1A 2AA is SW1A 2

Bias by postcode sector, the outward code plus first numeric of the inward code.

bias_post_town
string (Bias Post Town)

Bias by town.

bias_thoroughfare
string (Bias Thoroughfare)

Bias by street name.

bias_country
string (Bias County)

Bias by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.

bias_lonlat
string (Bias Lon/Lat)
Example: bias_lonlat=-2.095,57.15,100

Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is 50000. Uses the format bias_lonlat=[longitude],[latitude],[radius in metres] Only one geospatial bias may be provided

bias_ip
string (Bias query by Geolocation of IP)
Value: "true"
Example: bias_ip=bias_ip=true

Biases search based on approximate geolocation of IP address. Set bias_ip=true to enable.

Responses

Request samples 

https://api.addresszen.com/v1/autocomplete/addresses?api_key=iddqd&q=10%20downing

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Resolve Address (GBR)

Resolves an address autocompletion by its address ID.

Resolved addresses (including global addresses) are returned in a UK format (up to 3 address lines) using UK nomenclature (like postcode and county).

path Parameters
address
required
string

ID of address suggestion

query Parameters
api_key
string (API Key)
Example: api_key=ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

Responses

Request samples 

https://api.addresszen.com/v1/autocomplete/addresses/paf_23747771/gbr?api_key=iddqd

Response samples

Content type
application/json
{
  • "code": 2000,
  • "message": "Success",
  • "result": {
    }
}

Resolve Address (USA)

Resolves an address autocompletion by its address ID.

Resolved addresses (including global addresses) are returned in a US format (up to 2 address lines) using US nomenclature (like zipcode, state and city).

path Parameters
address
required
string

ID of address suggestion

query Parameters
api_key
string (API Key)
Example: api_key=ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

Responses

Request samples 

https://api.addresszen.com/v1/autocomplete/addresses/usps_Z222446599|1||1101/usa?api_key=iddqd

Response samples

Content type
application/json
{
  • "code": 2000,
  • "message": "Success",
  • "result": {
    }
}

UK

UK Address and Postcode Search

Lookup Postcode

Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive.

The Postcode Lookup API provides a JSON interface to search UK addresses from a postcode. It can be used to power Postcode Lookup driven address searches, like Postcode Lookup.

Postcode Not Found

Lookup balance is unaffected by invalid postcodes. The API returns a 404 response with response body:

{
  "code": 4040,
  "message": "Postcode not found",
  "suggestions": ["SW1A 0AA"]
}

Suggestions

If a postcode cannot be found, the API will provide up to 5 closest matching postcodes. Common errors will be corrected first (e.g. mixing up O and 0 or I and 1).

If the suggestion list is small (fewer than 3), there is a high probability the correct postcode is there. You may notify the user or immediately trigger new searches.

The suggestion list will be empty if the postcode has deviated too far from a valid postcode format.

Multiple Residence

A small number of postcodes will return more than 100 premises. These may require pagination. Use page to paginate the result set.

path Parameters
postcode
required
string (Postcode) [ 6 .. 8 ] characters
Example: SW1A 2AA

Postcode to retrieve

query Parameters
api_key
string (API Key)
Example: api_key=ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

filter
string (Filter)
Example: filter=line_1,line_2,line_3

Comma separated whitelist of address elements to return.

E.g. filter=line_1,line_2,line_3 returns only line_1, line_2 and line_3 address elements in your response

page
integer <int32> (Page) >= 0
Default: 0
Example: page=0

0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0.

A small number of Multiple Residence postcodes may need pagination (i.e. have more than 100 premises).

Responses

Request samples 

https://api.addresszen.com/v1/postcodes/SW1A2AA?api_key=iddqd

Response samples

Content type
application/json
{
  • "result": [
    ],
  • "code": 2000,
  • "message": "Success"
}

Retrieve by UDPRN

Returns an address as identified by its Unique Delivery Point Reference Number (UDPRN).

You may find it useful to store UDPRN information as it can be used to retrieve the most recent information for an address. It can also be used to test for a deleted address.

UDPRNs are an eight digit unique numeric code (e.g. 25962203) for any premise on the Postcode Address File. It's essentially a unique identifier for every address in the UK that Royal Mail has in its database.

Testing

To test your implementation of our API we have a range of test UDPRNs that yield both successful and unsuccessful responses to your request.

They are the following:

  • 0 Returns a successful UDPRN lookup response 2000
  • -1 Returns "UDPRN not found", error 4044
  • -2 Returns "no lookups remaining", error 4020
  • -3 Returns "daily (or individual) lookup limit breached", error 4021

Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.

path Parameters
udprn
required
string

UDPRN to be retrieved

query Parameters
api_key
string (API Key)
Example: api_key=ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

filter
string (Filter)
Example: filter=line_1,line_2,line_3

Comma separated whitelist of address elements to return.

E.g. filter=line_1,line_2,line_3 returns only line_1, line_2 and line_3 address elements in your response

Responses

Request samples 

https://api.addresszen.com/v1/udprn/0?api_key=iddqd

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Retrieve by UMPRN

Returns a multiple occupancy address identifited via its UMPRN (Multiple Residence Unique ID).

UMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset.

Testing

To test your implementation of our API we have a range of test UMPRNs that yield both successful and unsuccessful responses to your request. They are the following

  • 0 Returns a successful UMPRN lookup response 2000
  • -1 Returns "UMPRN not found", error 4044
  • -2 Returns "no lookups remaining", error 4020
  • -3 Returns "daily (or individual) lookup limit breached", error 4021

Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.

Pricing

Per lookup charges apply. Empty responses are not charged.

path Parameters
umprn
required
string

UMPRN to be retrieved

query Parameters
api_key
string (API Key)
Example: api_key=ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

filter
string (Filter)
Example: filter=line_1,line_2,line_3

Comma separated whitelist of address elements to return.

E.g. filter=line_1,line_2,line_3 returns only line_1, line_2 and line_3 address elements in your response

Responses

Request samples 

https://api.addresszen.com/v1/umprn/0?api_key=iddqdmr

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Extract Addresses

Extract a list of complete addresses that match the query ordered by relevance score. This query accepts an optional limit and page query (defaults to 10 and 0 respectively).

If a valid postcode is passed as the query string, the entire address list for that postcode is passed as a result. Note, in these cases, limit and page parameters are ignored.

This API is designed as a multi-purpose tool for generating address lists, cleansing and wholesale data extraction according to specific parameters.

For address autocomplete, see our address finder API - which is designed for speed and address completion.

Reverse Geocoding

Return a list of addresses around a point using the lon= and lat= querystring arguments. Addresses will be sorted in order of distance to the point. The search radius is 100m.

Filters

You can strictly narrow your result by adding filters to your query string which correspond with an address attribute.

For instance, you can restrict to postcode SW1A 2AA by appending postcode=sw1a2aa.

If a filter term is invalid, e.g. postcode=SW1A2AAA, then an empty result set is returned and no lookup is incurred.

You can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: postcode_outward=e1,e2,e3. Multiple terms are OR'ed, i.e. the matching result sets are combined.

All filters can accept multiple terms unless stated otherwise below.

Multiple filters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: su_organisation_indicator=Y&postcode_area=n. Multiple filters are AND'ed, i.e. each additional filter narrows the result set.

A combined maximum of 5 terms are allowed across all filters.

Biases

You can boost certain addresses results that correspond with a certain address attribute. All bias searches are prefixed with bias_.

Biased searches, unlike filtered searches, also allow unmatched addresses to appear . These will rank lower.

For instance, you can boost addresses with postcode areas SW and SE by appending bias_postcode_area=SW,SE.

If a bias term is invalid, e.g. bias_postcode=SW1A2AAA no bias effect is applied.

You may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: bias_postcode_outward=e1,e2,e3.

All biases can accept multiple terms unless stated otherwise below.

A combined maximum of 5 terms are allowed across all biases.

Search by Postcode and Building Name or Number

Search by postcode and building attribute with the postcode filter and query argument. E.g. For "SW1A 2AA Prime Minister" /v1/addresses?postcode=sw1a2aa&q=prime minister.

The advantage of using filters is a postcode mismatch does not result in a lookup as no results are returned.

Search By UPRN

Search by UPRN using the uprn filter and excluding the query argument. E.g. /v1/addresses?uprn=100.

Testing

  • ID1 1QD Returns a successful query response 2000
  • ID1 KFA Returns an empty query response 2000
  • ID1 CLIP Returns "no lookups remaining" error 4020
  • ID1 CHOP Returns "daily (or individual) lookup limit breached" error 4021

Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.

query Parameters
api_key
required
string (API Key)
Example: api_key=ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

query
string

Specifies the address you wish to query. Query can be shortened to q=

limit
integer <int32> (Limit) [ 1 .. 100 ]
Default: 10
Example: limit=5

Specifies the maximum number of suggestions to retrieve.

By default the limit is 10, unless a postcode is queried (then all addresses at that postcode will be returned). Limit can be shortened to l=

page
integer <int32> (Page) >= 0
Default: 0
Example: page=0

0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0.

A small number of Multiple Residence postcodes may need pagination (i.e. have more than 100 premises).

filter
string (Filter)
Example: filter=line_1,line_2,line_3

Comma separated whitelist of address elements to return.

E.g. filter=line_1,line_2,line_3 returns only line_1, line_2 and line_3 address elements in your response

lon
number <float> (Longitude) [ -90 .. 90 ]
Example: lon=-0.12767

Longitude query for reverse geocoding.

An accompanying latitude (lat=) query must be submitted for a valid reverse geocode query.

lat
number <float> (Latitude) [ -90 .. 90 ]
Example: lat=51.503541

Latitude query for reverse geocoding.

An accompanying longitude (lon=) query must be submitted for a valid reverse geocode query.

postcode_outward
string (Postcode Outward)
Example: postcode_outward=1AA

Filter by outward code.

postcode
string (Postcode)
Example: postcode=SW1A 2AA

Filter by postcode. Can be combined with query to perform a postcode + building number/name search.

postcode_area
string (Postcode Area)
Example: postcode_area=SW

Filter by postcode. Can be combined with query to perform a postcode + building number/name search.

postcode_sector
string (Postcode Sector)
Example: postcode_sector=SW1A 2

Filter by postcode sector, the outward code plus first numeric of the inward code.

post_town
string (Post Town)
Example: post_town=London

Filter by town.

uprn
integer (UPRN)
Example: uprn=100023336956

Filters by UPRN. Does not accept comma separated terms. Only a single term is permitted

country
string (Country)
Example: country=England

Filter by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.

postcode_type
string (Country)
Example: postcode_type=L

Filter by Postcode Type. Useful for separating organisational and residential addresses

su_organisation_indicator
string (SU Organisation Indicator)
Example: su_organisation_indicator=Y

Filter by Organisation Indicator. Useful for separating organisational and residential addresses

box
string (Box)
Example: box=2.095,57.15,-2.096,57.14

Restrict search to a geospatial box determined by the "top-left" and "bottom-right" gelocations. Only one geospatial box can be provided.

bias_postcode_outward
string (Bias Postcode Outward)

Bias by outward code

bias_postcode
string (Bias Postcode)
Example: bias_postcode=/addresses?postcode=SW1A2AA&q=10

Bias by postcode. Can be combined with query to perform a postcode + building number/name search.

bias_postcode_area
string (Bias Postcode Area)
Example: bias_postcode_area=The postcode area of SW1A 2AA and N1 6RT are SW and N respectively

Bias by postcode area, the first one or two non-numeric characters of a postcode.

bias_postcode_sector
string (Bias Postcode Sector)
Example: bias_postcode_sector=SW1A 2AA is SW1A 2

Bias by postcode sector, the outward code plus first numeric of the inward code.

bias_post_town
string (Bias Post Town)

Bias by town.

bias_thoroughfare
string (Bias Thoroughfare)

Bias by street name.

bias_country
string (Bias County)

Bias by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.

bias_lonlat
string (Bias Lon/Lat)
Example: bias_lonlat=-2.095,57.15,100

Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is 50000. Uses the format bias_lonlat=[longitude],[latitude],[radius in metres] Only one geospatial bias may be provided

Responses

Request samples 

https://api.addresszen.com/v1/addresses?api_key=iddqd&query=10%20downing%20street%20london

Response samples

Content type
application/json
{
  • "code": 2000,
  • "message": "Success",
  • "result": {
    }
}

Keys

Monitor and manage API Keys

Availability

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.

You may pass both API Keys (beginning ak_) and Sub-licensed Keys (beginning sl_).

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
path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "message": "Success",
  • "code": 2000
}

Details

Returns private data on the key including remaining lookups, available datasets and usage limits.

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

query Parameters
user_token
string (User Token)
Example: user_token=uk_B59ScW1p1HHouf1VqclEPZUx

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically beings uk_...

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Usage Stats

Reports the number of lookups consumed on a key for a range of days.

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.

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

query Parameters
start
integer <int32> (Start Time)
Example: start=1418556452651

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
integer <int32> (End Time)
Example: end=1418556477882

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
string (Tags)
Example: tags=foo,bar

A comma separated list of tags to query over.

Useful if you want to specify the circumstances in which the request was made.

If multiple tags are specified, the response 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
string (Licensee Key)
Example: licensee=sk_hk71kco54zGSGvF9eXXrvvnMOLLNh

Sublicensed keys only. This will restrict the analysed dataset to a specific licensee.

Responses

Request samples 

https://api.addresszen.com/v1/keys/iddqd/usage?user_token=my_secret_token

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Logs (CSV)

Reports lookup 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.

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.

Data Redaction

Personally Identifiable Data (PII) caught in this your usage log (including IP, search term and URL data) will be redacted on a weekly basis.

By default, PII will be redacted if it is older than 21 days. This timeframe can be configured from your dashboard.

You may prevent PII collection altogether by setting the interval to 0 days.

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

query Parameters
start
integer <int32> (Start Time)
Example: start=1418556452651

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
integer <int32> (End Time)
Example: end=1418556477882

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
string (Licensee Key)
Example: licensee=sk_hk71kco54zGSGvF9eXXrvvnMOLLNh

Sublicensed keys only. This will restrict the analysed dataset to a specific licensee.

Responses

Request samples 

https://api.addresszen.com/v1/keys/iddqd/lookups?user_token=my_secret_token

Response samples

Content type
text/csv
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,

Licensees

The Licensee resource represents an alternate legal End User of our data who may not be same entity as the owners of the account.

The concept of Licensees underpins our sublicensing platform, which allows users to license multiple external organisations or individuals to access data under the same account.

Sublicensing is ideal for platform vendors, who provide services to multiple clients who in turn each have their own users.

List

Returns a list of licensees for a key.

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

query Parameters
starting_after
integer <int32>

Specify ID of the licensee after which you would like to list results

user_token
string (User Token)
Example: user_token=uk_B59ScW1p1HHouf1VqclEPZUx

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically beings uk_...

limit
integer <int32> (Limit) [ 1 .. 100 ]
Default: 10
Example: limit=5

Specify the maximum number of results to return per page. Default and maximum is 100.

query
string

Filter result by licensee name. Query can be shortened to q=

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "message": "Success",
  • "code": 2000
}

Create

Create a licensee for the specified API Key.

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

query Parameters
user_token
string (User Token)
Example: user_token=uk_B59ScW1p1HHouf1VqclEPZUx

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically beings uk_...

Request Body schema: application/json
name
string

Licensee individual or organisation name

address
string

Licensee's first, second and third line address as well as post town concatenated by commas

postcode
string

Licensee's postcode

whitelist
Array of strings

A list of allowed URLs. An empty list means that whitelisting is disabled

object

Responses

Request samples

Content type
application/json
{
  • "name": "Qwerty Widgets Limited",
  • "address": "12 High Street, Manchester",
  • "postcode": "ID1 1QD",
  • "whitelist": [],
  • "daily": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Retrieve

Returns licensee information as identified by the licensee key.

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

licensee
required
string (Licensee Key)
Example: sk_hk71kco54zGSGvF9eXXrvvnMOLLNh

Uniquely identifies a licensee

query Parameters
user_token
string (User Token)
Example: user_token=uk_B59ScW1p1HHouf1VqclEPZUx

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically beings uk_...

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Cancel

Cancels a licensee key. This renders a licensee unusable. This action can be reversed if you get in contact with us.

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

licensee
required
string (Licensee Key)
Example: sk_hk71kco54zGSGvF9eXXrvvnMOLLNh

Uniquely identifies a licensee

query Parameters
user_token
string (User Token)
Example: user_token=uk_B59ScW1p1HHouf1VqclEPZUx

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically beings uk_...

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Update

Update Licensee

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

licensee
required
string (Licensee Key)
Example: sk_hk71kco54zGSGvF9eXXrvvnMOLLNh

Uniquely identifies a licensee

query Parameters
user_token
string (User Token)
Example: user_token=uk_B59ScW1p1HHouf1VqclEPZUx

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically beings uk_...

Request Body schema: application/json
name
string

Licensee individual or organisation name

address
string

Licensee's first, second and third line address as well as post town concatenated by commas

postcode
string

Licensee's postcode

whitelist
Array of strings

A list of allowed URLs. An empty list means that whitelisting is disabled

object

Responses

Request samples

Content type
application/json
{
  • "name": "Qwerty Widgets Limited",
  • "address": "12 High Street, Manchester",
  • "postcode": "ID1 1QD",
  • "whitelist": [],
  • "daily": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Configs

The Config resource allows users to assign serialised configuration data to API Keys. The payloads assigned to a Config object can later be retrieved to dynamically configure your integration.

Useful if you need to configure your integration remotely rather than editing code in situ.

List

Lists configurations associated with a key

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

query Parameters
user_token
string (User Token)
Example: user_token=uk_B59ScW1p1HHouf1VqclEPZUx

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically beings uk_...

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "message": "Success",
  • "code": 2000
}

Create

Create a config

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

query Parameters
user_token
string (User Token)
Example: user_token=uk_B59ScW1p1HHouf1VqclEPZUx

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically beings uk_...

Request Body schema: application/json
name
required
string [ 0 .. 32 ]

A unique name to identify the configuration payload

payload
required
string [ 0 .. 4096 ]

A serialised payload of up to 4096 characters

Responses

Request samples

Content type
application/json
{
  • "name": "woocommerce",
  • "payload": "{\n \"removeOrganisation\": false\n}\n"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Retrieve

Retrieve config object by name

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

config
required
string (Configuration Name)
Example: idpc-be

User provided configuration object name

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Delete

Permanently deletes a configuration object.

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

config
required
string (Configuration Name)
Example: idpc-be

User provided configuration object name

query Parameters
user_token
string (User Token)
Example: user_token=uk_B59ScW1p1HHouf1VqclEPZUx

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically beings uk_...

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Update

Updates configuration object

path Parameters
key
required
string (API Key)
Example: ak_hk71kco54zGSGvF9eXXrvvnMOLLNh

Your API Key. Typically beings ak_.

Available from your dashboard

config
required
string (Configuration Name)
Example: idpc-be

User provided configuration object name

query Parameters
user_token
string (User Token)
Example: user_token=uk_B59ScW1p1HHouf1VqclEPZUx

A secret key used for sensitive operations on your account and API Keys.

Your user token can be retrieved and managed from your accounts page.

Typically beings uk_...

Request Body schema: application/json
payload
string [ 0 .. 4096 ]

A serialised payload of up to 4096 characters

Responses

Request samples

Content type
application/json
{
  • "payload": "{\n \"removeOrganisation\": false\n}\n"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "code": 2000,
  • "message": "Success"
}

Address Suggestion

Address Suggestions are simple, human readable representations of an address. This format is sufficient tfor a user to determine an address match in an address autocomplete interface. A second request must be made to the API to gather fully validated address.

See our Address Search APIs for more information on address autocompletion.

id
required
string (ID)

Global unique internally generated identifier for an address

suggestion
required
string

Address Suggestion to be displayed to the user

urls
required
object
{
  • "id": "paf_8387729",
  • "suggestion": "Flat 6, 12 Roskear, Camborne, TR14",
  • "urls": { }
}

US Address

Standard US Address format as reported by USPS.

id
required
string (ID)

Global unique internally generated identifier for an address

dataset
required
string (USA Dataset)
Value: "usps"

Identifies the address as sourced from USPS

country
required
string (Country)
Enum: "United States" "Guam" "Puerto Rico"

Full country names (ISO 3166)

country_iso
required
string (ISO Country Code (3))
Enum: "USA" "PRI" "GUM"

3 letter country code (ISO 3166-1)

country_iso_2
required
string (ISO Country Code (2))
Enum: "US" "PR" "GU"

2 letter country code (ISO 3166-1)

language
required
string (Language)
Value: "en"

Language represented by 2 letter ISO Code (639-1)

primary_number
required
string (Primary Number)

A house, rural route, contract box, or Post Office Box number. The numeric or alphanumeric component of an address preceding the street name. Often referred to as house number.

secondary_number
required
string (Secondary Number)

Number of the sub unit, apartment, suite etc

plus_4_code
required
string (Plus 4 Code)

4 digit ZIP add-on code.

line_1
required
string (First Address Line)

The primary delivery line (usually the street address) of the address.

line_2
required
string (Second Address Line)

Secondary delivery line of the address. Typically populated if the first line is the firm or building name.

last_line
required
string (Last Line)

Last line of the address comprising of city, state, zip code and zip+4

zip_code
required
string (ZIP Code)

A 5-digit code that identifies a specific geographic delivery area. ZIP Codes can represent an area within a state, or a single building or company that has a very high mail volume.

zip_plus_4_code
required
string (ZIP + 4 Code)

Nine-digit code that identifies a small geographic delivery area that is serviceable by a single carrier; appears in the last line of the address on a mail piece.

update_key_number
required
string (Update Key Number)

Field that contains a number that uniquely identifies a record; used to identify the base record to which an add or delete transaction is being directed. The Update Key Number field is used only when applying transactions to the base file; it is not used in address matching and remains fixed for the life of the record. The field is alphanumeric and consists of the database segment code (V1, V2, W1, W2, X1, X2, Y1, Y2, Z1, or Z2) and eight characters containing an alphanumeric value ranging from 00000001 to AAAAAAAA.

record_type_code
required
string (Record Type Code)
Enum: "G" "H" "F" "S" "P" "R" "M" ""

An alphabetic value that identifies the type of data in the record. - G = General delivery (5-Digit ZIP, ZIP + 4, and Carrier Route products) - H = High-rise (ZIP + 4 only) - F = Firm (ZIP + 4 only) - S = Street (5-Digit ZIP, ZIP + 4, and Carrier Route products) - P = PO Box (5-Digit ZIP, ZIP + 4, and Carrier Route products) - R = Rural route/contract (5-Digit ZIP, ZIP + 4, and Carrier Route products) - M = Multi-carrier (Carrier Route product only)

carrier_route_id
required
string (Carrier Route ID)

A 4 character ID identifying the postal route for the address. The first character indicates the route type. Specifically:

  • "B" indicates PO Box
  • "H" indicates highway
  • "C" indicates city
  • "G" indicates general
  • "R" indicates rural
street_pre_directional_abbreviation
required
string (Street Pre-Directional Abbreviation)

A geographic direction that precedes the street name.

street_name
required
string (Street Name)

The official name of a street as assigned by a local governing authority. The Street Name field contains only the street name and does not include directionals (EAST, WEST, etc.) or suffixes (ST, DR, BLVD, etc.). This element may also contain literals, such as PO BOX, GENERAL DELIVERY, USS, PSC, or UNIT.

street_suffix_abbreviation
required
string (Street Suffix Abbreviation)

Code that is the standard USPS abbreviation for the trailing designator in a street address.

street_post_directional_abbreviation
required
string (Street Post Directional Abbreviation)

A geographic direction that follows the street name.

building_or_firm_name
required
string (Building or Firm Name)

The name of a company, building, apartment complex, shopping center, or other distinguishing secondary address information. This field is normally used with firm and highrise records but may also contain literals such as “Postmaster” or “United States Postal Service.”

address_secondary_abbreviation
required
string (Address Secondary Abbreviation)

A descriptive code used to identify the type of address secondary range information in the Address Secondary Range field. This code may be useful in address matching, e.g., the secondary address numbers may indicate apartment, suite, or trailer numbers.

base_alternate_code
required
string (Base Alternate Code)
Enum: "A" "B" ""

Code that specifies whether a record is a base (preferred) or alternate record. Base records (represented as "B") can represent a range of addresses or an individual address, such as a firm record, while alternate records (represented as "A") are individual delivery points. Base records are generally preferred over alternate records. Government deliveries will only be listed on alternate records with the appropriate government building indicator (federal, state, or city) set.

lacs_status_indicator
required
string (LACS Status Indicator)
Enum: "" "L"

The Locatable Address Conversion Service (LACS) indicator describes records that have been converted to the LACS system (a product/system in a different USPS® product line that allows mailers to identify and convert a rural route address to a city-style address). Rural route and some city addresses are being modified to city-style addresses so that emergency services (e.g., ambulances, police) can find these addresses more efficiently.

  • L = LACS address: The old (usually rural-route) address that has been converted for the LACS system.
  • Blank = Not applicable
government_building_indicator
required
string (Government Building Indicator)
Enum: "" "A" "B" "C" "D" "E" "F" "G"

An alphabetic value that identifies the type of government agency at the delivery point and/or whether a firm is the only delivery at an address. For this purpose, "address" is defined as the complete delivery line (e.g., complete street address and, if included as part of the firm record, the secondary abbreviation and/or address secondary number).

  • A = City government building—alternates only
  • B = Federal government building—alternates only
  • C = State government building—alternates only
  • D = Firm only—base and alternates
  • E = City government building and firm only—alternates only
  • F = Federal government building and firm only—alternates only
  • G = State government building and firm only—alternates only
state_abbreviation
required
string (State Abbreviation)

A 2-character abbreviation for the name of a state, U.S. territory, or armed forces ZIP Code designation. If APO/FPO/DPO, then the state abbreviation will be “AA,” “AE,” or “AP.”

state
required
string (State)

Full name of a state, U.S. territory, or armed forces ZIP Code designation.

municipality_city_state_key
required
string (Municipality City State Key)

Municipality City State Key. Currently blank.

urbanization_city_state_key
required
string (Urbanization City State Key)

An index to the City State file that provides the urbanization name for this delivery range.

preferred_last_line_city_state_key
required
string (Preferred Last Line City State Key)

In the Carrier Route, Five-Digit ZIP Code, Delivery Statistics, and ZIP + 4 products, an index to the City State product record that provides the preferred last-line name for this address range. In the City State product, the preferred last line city/state key contains the key value of a City State product record that has the default preferred or alternate preferred last-line key for a given ZIP Code.

county
required
string (County Name)

The name of the county or parish in which the 5-digit ZIP Code resides. If APO/FPO/DPO, then the county name will be blank.

city
required
string (City Name)

A valid city name for mailing purposes; appears in the last line of an address on a mail piece.

city_abbreviation
required
string (City State Name Abbreviation)

A standard 13-character abbreviation for a city/state name. This field is only used for names that are greater than 13 characters in length and have a city/state mailing name indicator of "Y." If the field is longer than 13 characters and the city/state mailing name indicator is "N," the field will be blank.

preferred_city
required
string (Preferred Last Line City State Name)

Field that contains the default preferred or alternate preferred last-line name for a ZIP Code.

city_state_name_facility_code
required
string (City State Name Facility Code)
Enum: "B" "C" "N" "P" "S" "U" "Y" ""

The type of locale identified in the city/state name. The facility may be a USPS facility, such as a post office, station, or branch, or it may be a non-postal place name. City/state name facility codes include the following:

  • B = Branch
  • C = Community post office (CPO)
  • N = Non-postal community name, former USPS facility, or place name
  • P = Post Office
  • S = Station
  • U = Urbanization
zip_classification_code
required
string (ZIP Classification Code)
Enum: "" "M" "P" "U"

A field that describes the type of ZIP area that a 5-digit ZIP Code serves, e.g., a single educational institution, post office boxes only, or a single address that has unusually high mail volume or many different addresses.

  • M = Military ZIP Code
  • P = ZIP Code having only Post Office Boxes
  • U = Unique ZIP Code (ZIP assigned to a single organization)
  • Blank = Standard ZIP with many addresses assigned to it
city_state_mailing_name_indicator
required
string (City State Mailing Name Indicator)

Specifies whether or not the city state name can be used as a last line of address on a mail piece.

  • "Y = City/state name is a USPS-approved mailing name."
  • "N = City/state name is not approved for mailing purposes."
carrier_route_rate_sortation
required
string (Carrier Route Rate Sortation and Merged 5-Digit Indicator)

Identifies where automation Carrier Route rates are available and where the commingling of automation and non-automation mail, including Enhanced Carrier Routes and 5-digit presort, on the same pallet or in the same container is allowed.

required
Finance Number (string) or Finance Number (number) (Finance Number)

A code assigned to Postal Service facilities (primarily Post Offices) to collect cost and statistical data and compile revenue and expense data.

required
Congressional District Number (string) or Congressional District Number (number) (Congressional District Number)

A standard value identifying a geographic area within the United States served by a member of the U.S. House of Representatives. If Army/Air Force (APO), Fleet Post Office (FPO), or Diplomatic/Defense Post Office (DPO), this field will be blank. If there is only one member of Congress within a state, the code will be "AL" (at large).

required
County Number (string) or County Number (number) (County Number)

The Federal Information Processing Standard (FIPS) code assigned to a given county or parish within a state. In Alaska, it identifies a region within the state. If APO/FPO/DPO, and the record type is “S,” “H,” or “F,” the county number will be blank.

{
  • "id": "paf_8387729",
  • "dataset": "usps",
  • "country": "United States",
  • "country_iso": "USA",
  • "country_iso_2": "US",
  • "language": "en",
  • "primary_number": "A298",
  • "secondary_number": "123A",
  • "plus_4_code": "1234",
  • "line_1": "12 Armstrong Ct Apt 12",
  • "line_2": "9450 Pinecroft Dr",
  • "last_line": "Greenwich CT 06830-1234",
  • "zip_code": "1234",
  • "zip_plus_4_code": "12345-6789",
  • "update_key_number": "00000001",
  • "record_type_code": "G",
  • "carrier_route_id": "R012",
  • "street_pre_directional_abbreviation": "string",
  • "street_name": "GOSHEN",
  • "street_suffix_abbreviation": "ST",
  • "street_post_directional_abbreviation": "string",
  • "building_or_firm_name": "POSTMASTER",
  • "address_secondary_abbreviation": "string",
  • "base_alternate_code": "A",
  • "lacs_status_indicator": "",
  • "government_building_indicator": "",
  • "state_abbreviation": "NY",
  • "state": "New York",
  • "municipality_city_state_key": "string",
  • "urbanization_city_state_key": "V18475",
  • "preferred_last_line_city_state_key": "V13916",
  • "county": "Suffolk",
  • "city": "HOLTSVILLE",
  • "city_abbreviation": "W TOWNSHEND",
  • "preferred_city": "AGUADA",
  • "city_state_name_facility_code": "B",
  • "zip_classification_code": "",
  • "city_state_mailing_name_indicator": "string",
  • "carrier_route_rate_sortation": "string",
  • "finance_number": "string",
  • "congressional_district_number": "string",
  • "county_number": "string"
}

UK Address

Standard UK Address format as reported by Royal Mail's Postcode Address File (PAF). PAF is the most complete and up-to-date address database in the UK.

id
required
string (ID)

Global unique internally generated identifier for an address

dataset
required
string (Dataset)
Value: "paf"

Indicates the provenance of an address

country_iso
required
string (ISO Country Code (3))
Enum: "GBR" "IMN" "JEY" "GGY"

3 letter country code (ISO 3166-1)

country_iso_2
required
string (ISO Country Code (2))
Enum: "GB" "IM" "JE" "GG"

2 letter country code (ISO 3166-1)

country
required
string (Country)
Enum: "England" "Scotland" "Wales" "Northern Ireland" "Jersey" "Guernsey" "Isle of Man"

Full country names (ISO 3166)

language
required
string (Language)
Value: "en"

Language represented by 2 letter ISO Code (639-1)

line_1
required
string (Line 1)

First Address Line. Often contains premise and thoroughfare information. In the case of a commercial premise, the first line is always the full name of the registered organisation. Never empty.

line_2
required
string (Line 2)

Second Address Line. Often contains thoroughfare and locality information. May be empty

line_3
required
string (Line 3)

Third address line. May be empty.

post_town
required
string (Post Town) <= 30 characters

A Post Town is mandatory for delivery of mail to a Delivery Point. This is not necessarily the nearest town geographically, but a routing instruction to the Royal Mail delivery office sorting mail for that Delivery Point. A Post Town will always be present in every address, and for some Localities the Post Town will be the only locality element present.

postcode
required
string (Postcode) [ 6 .. 8 ] characters

Correctly formatted postcode. Capitalised and spaced.

county
required
string (County)

Since postal, administrative or traditional counties may not apply to some addresses, the county field is designed to return whatever county data is available. Normally, the postal county is returned. If this is not present, the county field will fall back to the administrative county. If the administrative county is also not present, the county field will fall back to the traditional county. May be empty in cases where no administrative, postal or traditional county present.

county_code
required
string (County Code)

Short code representing the county or province. May be empty ("")

uprn
required
string (Unique Property Reference Number)

UPRN stands for Unique Property Reference Number and is maintained by the Ordnance Survey (OS). Local governments in the UK have allocated a unique number for each land or property.

Up to 12 digits in length.

Multiple Residence premises currently share the same UPRN as the parent premise.

May not be available for a small number of Great Britain addresses due to longer update cycles for Ordnance Survey's AddressBase datasets. Returns empty string "" in these instances.

Although UPRN takes an integer format, we encode and transmit this data as strings. As a 12 digit number, the UPRN can exceed the maximum safe integer Number.MAX_SAFE_INTEGER in most browsers causing this datapoint to be corrupted.

Take special care when storing UPRN. As a 12 digit identifier, you will need 64 bits to encode every possible UPRN value. This means applications like Excel will corrupt cells containing UPRN values.

udprn
required
integer <int32> (Unique Delivery Point Reference Number (UDPRN))

UDPRN stands for ‘Unique Delivery Point Reference Number’. Royal Mail assigns a unique UDPRN code for each premise on PAF. Simple, unique reference number for each Delivery Point. Unlikely to be reused when an address expires.

Up to 8-digit numeric code.

A new UDPRN is automatically assigned to each new Delivery Point added to PAF.

required
UMPRN (string) or UMPRN (number) (UMPRN)

A small minority of individual premises (as identified by a UDPRN) may have multiple occupants behind the same letterbox. These are known as Multiple Residence occupants and can be queried via the Multiple Residence dataset. Simple, unique reference number for each Multiple Residence occupant.

Note: this will be an empty string "" when not used.

postcode_outward
required
string (Postcode Outward) [ 2 .. 4 ] characters

The first part of a postcode is known as the outward code. e.g. The outward code of ID1 1QD is ID1. Enables mail to be sorted to the correct local area for delivery. This part of the code contains the area and the district to which the mail is to be delivered, e.g. ‘PO1’, ‘SW1A’ or ‘B23’.

postcode_inward
required
string (Postcode Inward) = 3 characters

The second part of a postcode is known as the inward code. e.g. The inward code of ID1 1QD is 1QD.

The number identifies the sector in the postal district. The number is followed by 2 letters. The letters then define one or more properties in that sector.

dependant_locality
required
string (Dependant Locality) <= 35 characters

When the same thoroughfare name reoccurs in a Post town, it may not be possible to make it dependant on a dependant thoroughfare. In this case the thoroughfare is dependant on a locality. For example if we want to find 1 Back Lane in Huddersfield we see that there are three.

double_dependant_locality
required
string (Double Dependant Locality) <= 35 characters

Used to supplement Dependant Locality. A Double Dependant Locality supplied along with a Dependant Locality if the Dependant Locality exists twice in the same locality.

thoroughfare
required
string (Thoroughfare) <= 80 characters

Also known as the street or road name. In general each Thoroughfare Name will have a separate Postcode. Longer Thoroughfares with high number ranges often have multiple Postcodes covering the entire length of the road, with breaks at suitable points e.g. junctions or natural breaks in the road.

dependant_thoroughfare
required
string (Dependant Thoroughfare) <= 80 characters

Used to supplement thoroughfare. When a thoroughfare name is used twice in the same Post Town, the dependant thoroughfare is added to uniquely indentify a delivery point.

building_number
required
string (Building Number) <= 4 characters

Number to identify premise on a thoroughfare or dependant thoroughfare.

building_name
required
string (Building Name) <= 50 characters

Name of residential or commercial premise.

Examples:

  • The Manor
  • 1-2
  • A
  • 12A
  • K
  • Victoria House
sub_building_name
required
string (Sub-Building Name) <= 30 characters

When a premise is split into individual units such as flats, apartments or business units. Cannot be present without either building_name or building_number. E.g. Flat 1, A, 10B

po_box
required
string (PO Box) <= 6 characters

When the PO Box Number field is populated it will contain PO BOX nnnnnn where n represents the PO Box number. Note that the PO Box details can occasionally consist of a combination of numbers and letters. PO Box Numbers are only allocated to Large Users.

department_name
required
string (Department Name) <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation.

organisation_name
required
string (Organisation Name) <= 60 characters

Used to supplment Organisation Name to identify a deparment within the organisation

postcode_type
required
string (Postcode Type)
Enum: "S" "L"

This indicates the type of user. It can only take the values 'S' or 'L' indicating small or large respectively. Large User Postcodes. These are assigned to one single address either due to the large volume of mail received at that address, or because a PO Box or Selectapost service has been set up. Small User Postcodes. These identify a group of Delivery Points.

On average there are 15 Delivery Points per Postcode. However this can vary between 1 and, in some cases, 100. There will never be more than 100 Delivery Points on a Postcode.

su_organisation_indicator
required
string (Small User Organisation Indicator)

Small User Organisation Indicator can have the values 'Y' or space. A value of 'Y' indicates that a Small User Organisation is present at this address.

delivery_point_suffix
required
string (Delivery Point Suffix)

A unique Royal Mail 2-character code (the first numeric & the second alphabetical), which, when added to the Postcode, enables each live Delivery Point to be uniquely identified. Once the Delivery Point is deleted from PAF the DPS may be reused (although they aren’t reused until all remaining Delivery Points in the range have been allocated). The DPS for a Large User is always '1A' as each Large User has its own Postcode.

premise
required
string (Premise) <= 84 characters

A pre-computed string which sensibly combines building_number, building_name and sub_building_name. building_number, building_name and sub_building_name represent raw data from Royal Mail's and can be difficult to parse if you are unaware of how the Postcode Address File premise fields work together. For this reason, we also provide a pre-computed premise field which intelligently gathers these points into a single, simple premise string. This field is ideal if you want to pull premise information and thoroughfare information separately instead of using our address lines data.

administrative_county
required
string (Administrative County)

The current administrative county to which the postcode has been assigned.

A Unitary Authority name, where one is present. If there is no Unitary Authority, the County name is used. This information is not static, because County boundaries may change due to administrative changes. Data

source: ONS

postal_county
required
string (Postal County)

Postal counties were used for the distribution of mail before the Postcode system was introduced in the 1970s. The Former Postal County was the Administrative County at the time. This data rarely changes. May be empty.

traditional_county
required
string (Traditional County)

Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty.

district
required
string (District)

The current district/unitary authority to which the postcode has been assigned.

ward
required
string (Ward)

The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses.

required
Longitude (string) or Longitude (number) (Longitude)

The longitude of the postcode (WGS84/ETRS89).

Can be a positive or negative decimal. E.g. -0.1283983

Returns an empty string if no location data is available.

required
Longitude (string) or Longitude (number) (Longitude)

The latitude of the postcode (WGS84/ETRS89).

Can be a positive or negative decimal. E.g. 51.5083983.

Returns an empty string if no location data is available.

required
Eastings (string) or Eastings (number) (Eastings)

Eastings reference using the Ordnance Survey National Grid reference system.

Northern Ireland Eastings uses the Irish Grid Reference System.

Metres from origin. E.g. 550458

Returns an empty string if no location data is available. Otherwise a number is returned.

required
Northings (string) or Northings (number) (Northings)

Northings reference using the Ordnance Survey National Grid reference system

Northern Ireland Northings uses the Irish Grid Reference System

Metres from origin. E.g. 180458

Returns an empty string if no location data is available. Otherwise a number is returned

{
  • "id": "paf_8387729",
  • "dataset": "paf",
  • "country_iso": "GBR",
  • "country_iso_2": "GB",
  • "country": "England",
  • "language": "en",
  • "line_1": "Prime Minister &amp; First Lord of Treasury",
  • "line_2": "10 Downing Street",
  • "line_3": "",
  • "post_town": "London",
  • "postcode": "SW1A 2AA",
  • "county": "London",
  • "county_code": "",
  • "uprn": "string",
  • "udprn": 23747771,
  • "umprn": "string",
  • "postcode_outward": "SW1A",
  • "postcode_inward": "2AA",
  • "dependant_locality": "",
  • "double_dependant_locality": "",
  • "thoroughfare": "Downing Street",
  • "dependant_thoroughfare": "",
  • "building_number": "10",
  • "building_name": "",
  • "sub_building_name": "Flat 1",
  • "po_box": "100",
  • "department_name": "",
  • "organisation_name": "Prime Minister &amp; First Lord Of The Treasury",
  • "postcode_type": "S",
  • "su_organisation_indicator": "Y",
  • "delivery_point_suffix": "1A",
  • "premise": "10",
  • "administrative_county": "",
  • "postal_county": "London",
  • "traditional_county": "Greater London",
  • "district": "Westminster",
  • "ward": "St. James'",
  • "longitude": "string",
  • "latitude": "string",
  • "eastings": "string",
  • "northings": "string"
}

IE Address

Standard Republic of Ireland Address format as reported by the Eircode ECAF file.

id
required
string (ID)

Global unique internally generated identifier for an address

dataset
required
string
Value: "ecaf"

Source of address

country_iso
required
any
Value: "IRL"

3 letter country code (ISO 3166-1)

country_iso_2
required
string
Value: "IE"

2 letter country code (ISO 3166-1)

country
required
string
Value: "Ireland"

Full country names (ISO 3166)

language
required
any
Enum: "en" "ga"

Language represented by 2 letter ISO Code (639-1)

line_1
required
string [ 0 .. 200 ] characters

Address Line 1

line_2
required
string [ 0 .. 200 ] characters

Address Line 2

line_3
required
string [ 0 .. 200 ] characters

Address Line 3

line_4
required
string [ 0 .. 200 ] characters

Address Line 4

line_5
required
string [ 0 .. 200 ] characters

Address Line 5

line_6
required
string [ 0 .. 200 ] characters

Address Line 6

line_7
required
string [ 0 .. 200 ] characters

Address Line 7

line_8
required
string [ 0 .. 200 ] characters

Address Line 8

line_9
required
string [ 0 .. 200 ] characters

Address Line 9

department
required
string [ 0 .. 60 ] characters

The department or division within an organisation. If the department element exists, then the organisation must also exist.

organisation
required
string [ 0 .. 60 ] characters

Organisation name

sub_building_name
required
string [ 0 .. 60 ] characters

The sub-building refers to an apartment, flat or unit within a building.

building_name
required
string [ 0 .. 60 ] characters

The name given to the building. Prepended by sub building, if any, when the sub building does not appear on a line to itself. The building name is omitted if it is the same as either the Organisation or Building Group.

building_number
required
string [ 0 .. 40 ] characters

A number associated with the whole building. The building number may have a numeric and an alphanumeric component, which are concatenated e.g. 2A, or alternatively will have a simple building number or a complex building number. The building number always relates to the whole building and not a sub-unit within it. A complex building number may be one of the following:

  • Dual. Two number separated by '/' e.g. 63/64 = 63, 64
  • Sequence. An odd or even sequence of numbers with lower and upper bound separated by an underscore '_' e.g. 1_5 = 1,3,5 and 2_6 = 2,4,6
  • Range. A range of consecutive numbers with lower and upper bound separated by a dash '-' e.g. 63-66 = 63, 64, 56, 66 The building number never appears on a line by itself and can prepend Building Group, Primary Thoroughfare or Primary Locality.
building_group
required
string [ 0 .. 60 ] characters

A building group is a collection of buildings with a collective name, located on or near the same thoroughfare.

primary_thoroughfare
required
string [ 0 .. 40 ] characters

The name of the thoroughfare on which premises are located. It may appear on a line by itself or be appended to either a sub building or building number.

Addresses with thoroughfares can sometimes have the thoroughfare excluded where a Building Group exists, such as a Retail Centre or Business Park, and the thoroughfare is not part of the Postal Address.

secondary_thoroughfare
required
string [ 0 .. 40 ] characters

It is never present without a primary thoroughfare. The primary thoroughfare is dependent on the secondary thoroughfare and appears before the secondary thoroughfare in any address.

Secondary thoroughfare are generally used to assist locating a primary thoroughfare.

primary_locality
required
string [ 0 .. 40 ] characters

First locality elements which can refer to areas, districts, industrial estates, towns, etc.

The primary locality refers to the specific place the address is.

In urban areas, the primary locality can be required to distinguish between two thoroughfares of the same name in the same district or town. Industrial estates with named thoroughfares are also held as localities. In rural areas the primary locality is generally a townland name.

secondary_locality
required
string [ 0 .. 40 ] characters

Never present without a primary locality. The secondary locality has a wider geographic scope than the primary locality.

It is the secondary locality therefore which differentiates addresses with the same primary locality name within the same county.

Secondary localities are more likely to be required for rural addresses.

Second locality elements which can refer to areas, districts, industrial estates, towns, etc

The secondary locality helps identify where the primary locality is located.

tertiary_locality
required
string [ 0 .. 40 ] characters

Also known as the Post Town.

The name of the post town associated with the premises for postal delivery purposes. This includes Dublin Postal Districts "Dublin 1" to "Dublin 24".

The post town is a significant element of the Postal Address, however it is not always populated in an address. The official post office guide, Eolaí an Phoist4, describes post towns in the following manner:

"A provincial postal address may include the name of a town or village several miles distant, with which the addressee has little or no connection, and, in some places, especially if this residence happens to be near a county boundary, the name of the neighbouring county instead of the county in which he actually resides. The explanation is that the main mail despatches have to be sent for more detailed sub division to certain centres known as POST TOWNS, chosen because of their accessibility and convenience."

post_county
required
string [ 0 .. 30 ] characters

One of the 26 Counties in the Republic of Ireland. These counties are sub-national divisions used for the purposes of administrative, geographical and political demarcation. Post County is the County associated with the Post Town, not the geographic county in which the building is located. The Post County is normally used as part of the Postal Address with some exceptions e.g. Dublin Postal Districts where the Post County is not used and some Post Towns (e.g. Tipperary, Kildare, etc.) that have the same name as the Post County.

eircode
required
string [ 0 .. 60 ] characters

The seven character Eircode has an A65 F4E2 format. The Eircode is a mandatory address element. The last line of a Postal Address will contain the Eircode, displayed with a space. e.g. A65 F4E2.

The Eircode is always the last line of a Postal Address generated within the state, e.g. if an address has four lines then the Eircode will be on its own on Address Line 5. For inbound international mail the country name IRELAND should be appended as the last line of the Postal Address.

address_reference
required
string [ 0 .. 16 ] characters

The address reference is the An Post GeoDirectory address reference identifier used by the Universal Service Provider.

required
Longitude (string) or Longitude (number) (Longitude)

The longitude of the postcode (WGS84/ETRS89).

Can be a positive or negative decimal. E.g. -0.1283983

Returns an empty string if no location data is available.

required
Longitude (string) or Longitude (number) (Longitude)

The latitude of the postcode (WGS84/ETRS89).

Can be a positive or negative decimal. E.g. 51.5083983.

Returns an empty string if no location data is available.

ecaf_id
required
string [ 0 .. 10 ] characters

The unique identifier in the ECAF is the ecaf_id. This unique identifier allows each address in the ECAF to be uniquely identified. It can also be used as index once the data has been imported into a relational database. This is a numeric field that can store values from 0 to 2,147,483,647. It is represented as a number up to 10 digits long. All other fields in ECAF are alphanumeric.

{
  • "id": "paf_8387729",
  • "dataset": "ecaf",
  • "country_iso": "IRL",
  • "country_iso_2": "IE",
  • "country": "Ireland",
  • "language": "en",
  • "line_1": "string",
  • "line_2": "string",
  • "line_3": "string",
  • "line_4": "string",
  • "line_5": "string",
  • "line_6": "string",
  • "line_7": "string",
  • "line_8": "string",
  • "line_9": "string",
  • "department": "Accounts Department",
  • "organisation": "Oak Tree Limited",
  • "sub_building_name": "Flat 1",
  • "building_name": "Rose Cottage",
  • "building_number": 22,
  • "building_group": "Marrian Terrace",
  • "primary_thoroughfare": "Griffith Road",
  • "secondary_thoroughfare": "Navan Road",
  • "primary_locality": "Cookstown Industrial Estate",
  • "secondary_locality": "Manorhamilton",
  • "tertiary_locality": "Dublin 14",
  • "post_county": "Cork",
  • "eircode": "A65 R2AF",
  • "address_reference": "string",
  • "longitude": "string",
  • "latitude": "string",
  • "ecaf_id": "string"
}

IE Address (ECAD)

ECAF file including additional data for each address.

id
required
string (ID)

Global unique internally generated identifier for an address

dataset
required
string
Value: "ecad"

Source of address

country_iso
required
any
Value: "IRL"

3 letter country code (ISO 3166-1)

country_iso_2
required
string
Value: "IE"

2 letter country code (ISO 3166-1)

country
required
string
Value: "Ireland"

Full country names (ISO 3166)

language
required
any
Enum: "en" "ga"

Language represented by 2 letter ISO Code (639-1)

line_1
required
string [ 0 .. 200 ] characters

Address Line 1

line_2
required
string [ 0 .. 200 ] characters

Address Line 2

line_3
required
string [ 0 .. 200 ] characters

Address Line 3

line_4
required
string [ 0 .. 200 ] characters

Address Line 4

line_5
required
string [ 0 .. 200 ] characters

Address Line 5

line_6
required
string [ 0 .. 200 ] characters

Address Line 6

line_7
required
string [ 0 .. 200 ] characters

Address Line 7

line_8
required
string [ 0 .. 200 ] characters

Address Line 8

line_9
required
string [ 0 .. 200 ] characters

Address Line 9

department
required
string [ 0 .. 60 ] characters

The department or division within an organisation. If the department element exists, then the organisation must also exist.

organisation
required
string [ 0 .. 60 ] characters

Organisation name

sub_building_name
required
string [ 0 .. 60 ] characters

The sub-building refers to an apartment, flat or unit within a building.

building_name
required
string [ 0 .. 60 ] characters

The name given to the building. Prepended by sub building, if any, when the sub building does not appear on a line to itself. The building name is omitted if it is the same as either the Organisation or Building Group.

building_number
required
string [ 0 .. 40 ] characters

A number associated with the whole building. The building number may have a numeric and an alphanumeric component, which are concatenated e.g. 2A, or alternatively will have a simple building number or a complex building number. The building number always relates to the whole building and not a sub-unit within it. A complex building number may be one of the following:

  • Dual. Two number separated by '/' e.g. 63/64 = 63, 64
  • Sequence. An odd or even sequence of numbers with lower and upper bound separated by an underscore '_' e.g. 1_5 = 1,3,5 and 2_6 = 2,4,6
  • Range. A range of consecutive numbers with lower and upper bound separated by a dash '-' e.g. 63-66 = 63, 64, 56, 66 The building number never appears on a line by itself and can prepend Building Group, Primary Thoroughfare or Primary Locality.
building_group
required
string [ 0 .. 60 ] characters

A building group is a collection of buildings with a collective name, located on or near the same thoroughfare.

primary_thoroughfare
required
string [ 0 .. 40 ] characters

The name of the thoroughfare on which premises are located. It may appear on a line by itself or be appended to either a sub building or building number.

Addresses with thoroughfares can sometimes have the thoroughfare excluded where a Building Group exists, such as a Retail Centre or Business Park, and the thoroughfare is not part of the Postal Address.

secondary_thoroughfare
required
string [ 0 .. 40 ] characters

It is never present without a primary thoroughfare. The primary thoroughfare is dependent on the secondary thoroughfare and appears before the secondary thoroughfare in any address.

Secondary thoroughfare are generally used to assist locating a primary thoroughfare.

primary_locality
required
string [ 0 .. 40 ] characters

First locality elements which can refer to areas, districts, industrial estates, towns, etc.

The primary locality refers to the specific place the address is.

In urban areas, the primary locality can be required to distinguish between two thoroughfares of the same name in the same district or town. Industrial estates with named thoroughfares are also held as localities. In rural areas the primary locality is generally a townland name.

secondary_locality
required
string [ 0 .. 40 ] characters

Never present without a primary locality. The secondary locality has a wider geographic scope than the primary locality.

It is the secondary locality therefore which differentiates addresses with the same primary locality name within the same county.

Secondary localities are more likely to be required for rural addresses.

Second locality elements which can refer to areas, districts, industrial estates, towns, etc

The secondary locality helps identify where the primary locality is located.

tertiary_locality
required
string [ 0 .. 40 ] characters

Also known as the Post Town.

The name of the post town associated with the premises for postal delivery purposes. This includes Dublin Postal Districts "Dublin 1" to "Dublin 24".

The post town is a significant element of the Postal Address, however it is not always populated in an address. The official post office guide, Eolaí an Phoist4, describes post towns in the following manner:

"A provincial postal address may include the name of a town or village several miles distant, with which the addressee has little or no connection, and, in some places, especially if this residence happens to be near a county boundary, the name of the neighbouring county instead of the county in which he actually resides. The explanation is that the main mail despatches have to be sent for more detailed sub division to certain centres known as POST TOWNS, chosen because of their accessibility and convenience."

post_county
required
string [ 0 .. 30 ] characters

One of the 26 Counties in the Republic of Ireland. These counties are sub-national divisions used for the purposes of administrative, geographical and political demarcation. Post County is the County associated with the Post Town, not the geographic county in which the building is located. The Post County is normally used as part of the Postal Address with some exceptions e.g. Dublin Postal Districts where the Post County is not used and some Post Towns (e.g. Tipperary, Kildare, etc.) that have the same name as the Post County.

eircode
required
string [ 0 .. 60 ] characters

The seven character Eircode has an A65 F4E2 format. The Eircode is a mandatory address element. The last line of a Postal Address will contain the Eircode, displayed with a space. e.g. A65 F4E2.

The Eircode is always the last line of a Postal Address generated within the state, e.g. if an address has four lines then the Eircode will be on its own on Address Line 5. For inbound international mail the country name IRELAND should be appended as the last line of the Postal Address.

address_reference
required
string [ 0 .. 16 ] characters

The address reference is the An Post GeoDirectory address reference identifier used by the Universal Service Provider.

required
Longitude (string) or Longitude (number) (Longitude)

The longitude of the postcode (WGS84/ETRS89).

Can be a positive or negative decimal. E.g. -0.1283983

Returns an empty string if no location data is available.

required
Longitude (string) or Longitude (number) (Longitude)

The latitude of the postcode (WGS84/ETRS89).

Can be a positive or negative decimal. E.g. 51.5083983.

Returns an empty string if no location data is available.

ecad_id
string [ 1 .. 10 ] characters

Unique 10 digit ECAD ID

organisation_id
required
string [ 1 .. 10 ] characters

Organisation ID

address_point_id
required
string [ 1 .. 10 ] characters

Address Point ID

building_id
required
string [ 1 .. 10 ] characters

Building ID

building_group_id
required
string

Building Group ID

primary_thoroughfare_id
required
string [ 1 .. 10 ] characters

Primary Thoroughfare ID

secondary_thoroughfare_id
required
string

Secondary Thoroughfare ID

primary_locality_id
required
string [ 1 .. 10 ] characters

Primary Locality ID

secondary_locality_id
required
string

Secondary Locality ID

post_town
required
string >= 0 characters

The post town is a significant element of the Postal Address, however it is not always populated in an address. The official post office guide, Eolaí an Phoist1, describes post towns in the following manner:

"A provincial postal address may include the name of a town or village several miles distant, with which the addressee has little or no connection, and, in some places, especially if this residence happens to be near a county boundary, the name of the neighbouring county instead of the county in which he actually resides. The explanation is that the main mail despatches have to be sent for more detailed sub division to certain centres known as post towns, chosen because of their accessibility and convenience."

post_town_id
required
string [ 1 .. 10 ] characters

Post Town ID

post_county_id
required
string [ 1 .. 10 ] characters

Post County ID

nua
required
boolean

NUA means "non-unique address".

The NUA field contains true when the address is a non-unique address, and false when it is a unique address.

Ireland has a very high level of non-unique addresses (NUA), i.e. the address does not contain a unique building number or name. Approximately 35% of all Irish addresses are non-unique which equates to 600,000 addresses.

The typical example of NUA addressing is where every address in a townland is the same. The way that post is delivered is by local knowledge of postal delivery personnel of which addressee lives in which house.

N.B. For a NUA address, it is impossible to match to a unique record in the ECAD and assign an Eircode.

gaeltacht
required
boolean

Gaeltact refers to a district where the Irish government recognises that the Irish language is the predominant language.

Returns true if address is in a Gaeltacht area and false if not.

address_type
required
string >= 0 characters

Addresses points can assume one of the following values:

  • Residential Address Point. This type of address point has one residential addresses associated with it.
  • Non-Residential Address Point. This type of address point has one or more non-residential address (business, club or other organisation) associated with it.
  • Mixed Address Point. This is a special case where the residential and non residential addresses in the building are essentially the same address. The typical example is a farm house on an active farm. It is important to note that this is a special case. In general a building with both residential and non-residential addresses (e.g. an apartment over a shop) will receive two address points, one commercial and one residential, and hence two Eircodes.

Buildings can contain multiple address points of type Residential and/or Non-Residential.

building_address_type
required
string >= 0 characters

The building type can assume one of the following values:

  • Single Occupancy Residential Building. This type of building contains one residential address.
  • Multi Occupancy Residential Building. This type of building contains multiple residential addresses.
  • Single Occupancy Non-Residential Building. This type of building contains one non-residential address (business, club or other organisation).
  • Multi Occupancy Non-Residential Building. This type of building contains multiple non-residential addresses (business, club or other organisation).
  • Multi Occupancy Mixed Use Building. This type of building contains multiple residential and non- residential addresses.

Buildings can also have a more specific address types such as a Hospital, School, Shopping Centre, etc.

building_group_address_type
required
string >= 0 characters

The building group type can be:

  • Residential Building Group. This type of building group contains buildings with residential addresses only.
  • Non-Residential Building Group This type of building group contains buildings with non-residential addresses (business, club or other organisation) only.
  • Mixed Building Group. This type of building group contains buildings with residential and non-residential addresses. Can also have a more specific address type such as a Hospital, School, Shopping Centre, etc.

Building groups can also have a more specific address type such as a Hospital, School, Shopping Centre, etc.

primary_locality_address_type
required
string >= 0 characters

The locality type can be:

  • Rural Locality. This is generally a townland.
  • Industrial Estate. Industrial Estate, Industrial Park, Business Campus, etc.
  • Shopping District. Shopping Centre.
  • Housing Estate. Residential Housing Estate.
  • Village. Based on Census 2011 population < 1,500.
  • Town. Based on Census 2011 population > 1,500.
  • Urban Area. Wholly within a village/town/city e.g. Rathmines.
  • Suburban Locality. This is an area that is both rural and urban, as it is both a townland, and also an area name applied to houses in a town, as the town has extended partially into the townland.

Where the locality is also the post town, the type can be:

  • Village. Based on Census 2011 population < 1,500
  • Town. Based on Census 2011 population > 1,500
  • Postal District. Dublin 1 to 24
  • City. Dublin, Cork, Limerick, Galway or Waterford
secondary_locality_address_type
required
string >= 0 characters

The locality type can be:

  • Rural Locality. This is generally a townland.
  • Industrial Estate. Industrial Estate, Industrial Park, Business Campus, etc.
  • Shopping District. Shopping Centre.
  • Housing Estate. Residential Housing Estate.
  • Village. Based on Census 2011 population < 1,500.
  • Town. Based on Census 2011 population > 1,500.
  • Urban Area. Wholly within a village/town/city e.g. Rathmines.
  • Suburban Locality. This is an area that is both rural and urban, as it is both a townland, and also an area name applied to houses in a town, as the town has extended partially into the townland.

Where the locality is also the post town, the type can be:

  • Village. Based on Census 2011 population < 1,500
  • Town. Based on Census 2011 population > 1,500
  • Postal District. Dublin 1 to 24
  • City. Dublin, Cork, Limerick, Galway or Waterford
building_type
required
string >= 0 characters

Describes the type of building, e.g. detached, semi-detached, bungalow.

holiday_home
required
any
Enum: "N" "Y" ""

A Yes/No field, indicating whether or not the building is a holiday home.

under_construction
required
any
Enum: "N" "Y" ""

A Yes/No field, indicating whether or not the building is under construction.

building_use
required
any
Enum: "R" "C" "B" "U"

Can be one of:

  • R Residential
  • C Commercial
  • B Both
  • U Unknown
vacant
required
any
Enum: "Y" "N" ""

A Yes/No field, indicating whether the building is vacant.

org_vacant
required
any
Enum: "Y" "N" ""

A Yes/No field, indicating whether the organisation is vacant.

nace_code
required
string >= 0 characters

The NACE Code for the Category.

nace_category
required
string >= 0 characters

Name of the NACE Category

local_authority
required
string >= 0 characters

Name of local authority

ded_id
required
string >= 0 characters

Unique Identifier for Electoral Divisions 2017 data.

Note that this field is subject to breaking changes if a new generation of government data IDs is released. Currently this uses 2017 IDs. Contact us to be notified ahead of his change.

small_area_id
required
string >= 0 characters

Unique Identifier for the Small Area 2017 data.

Note that this field is subject to breaking changes if a new generation of government data IDs is released. Currently this uses 2017 IDs. Contact us to be notified ahead of his change.

townland_id
required
string >= 0 characters

Unique Identifier for townland 2017 data.

Note that this field is subject to breaking changes if a new generation of government data IDs is released. Currently this uses 2017 IDs. Contact us to be notified ahead of his change.

gaeltacht_id
required
string >= 0 characters

Unique Identifier for the 7 Gaeltacht areas 2017 data.

Note that this field is subject to breaking changes if a new generation of government data IDs is released. Currently this uses 2017 IDs. Contact us to be notified ahead of his change.

postaim_presort_61
required
string >= 0 characters

An Post sorting information.

postaim_presort_152
required
string >= 0 characters

An Post sorting information.

publicity_post_zone
required
string >= 0 characters

An Post publicity post zone information.

{
  • "id": "paf_8387729",
  • "dataset": "ecad",
  • "country_iso": "IRL",
  • "country_iso_2": "IE",
  • "country": "Ireland",
  • "language": "en",
  • "line_1": "string",
  • "line_2": "string",
  • "line_3": "string",
  • "line_4": "string",
  • "line_5": "string",
  • "line_6": "string",
  • "line_7": "string",
  • "line_8": "string",
  • "line_9": "string",
  • "department": "Accounts Department",
  • "organisation": "Oak Tree Limited",
  • "sub_building_name": "Flat 1",
  • "building_name": "Rose Cottage",
  • "building_number": 22,
  • "building_group": "Marrian Terrace",
  • "primary_thoroughfare": "Griffith Road",
  • "secondary_thoroughfare": "Navan Road",
  • "primary_locality": "Cookstown Industrial Estate",
  • "secondary_locality": "Manorhamilton",
  • "tertiary_locality": "Dublin 14",
  • "post_county": "Cork",
  • "eircode": "A65 R2AF",
  • "address_reference": "string",
  • "longitude": "string",
  • "latitude": "string",
  • "ecad_id": "17000000",
  • "organisation_id": "10098783",
  • "address_point_id": "10098783",
  • "building_id": "10098783",
  • "building_group_id": "10098783",
  • "primary_thoroughfare_id": "10098783",
  • "secondary_thoroughfare_id": "10098783",
  • "primary_locality_id": "10098783",
  • "secondary_locality_id": "10098783",
  • "post_town": "string",
  • "post_town_id": "10098783",
  • "post_county_id": "10098783",
  • "nua": true,
  • "gaeltacht": true,
  • "address_type": "string",
  • "building_address_type": "string",
  • "building_group_address_type": "string",
  • "primary_locality_address_type": "string",
  • "secondary_locality_address_type": "string",
  • "building_type": "string",
  • "holiday_home": "N",
  • "under_construction": "N",
  • "building_use": "R",
  • "vacant": "Y",
  • "org_vacant": "Y",
  • "nace_code": "string",
  • "nace_category": "string",
  • "local_authority": "string",
  • "ded_id": "string",
  • "small_area_id": "string",
  • "townland_id": "string",
  • "gaeltacht_id": "string",
  • "postaim_presort_61": "string",
  • "postaim_presort_152": "string",
  • "publicity_post_zone": "string"
}