Address lookup API

Postcoder provides the fastest, most reliable way to capture accurate addresses.

Postcode to address lookup

Lookup UK addresses using postcodes, and Irish addresses using Eircodes.

Uses the latest PAF and Multiple Residence data from Royal Mail, and ECAD data from Eircode.

Example code

Request URL

UK postcode lookup

GET | https://ws.postcoder.com/pcw/[apikey]/address/uk/[postcode-or-address-fragment]

Irish Eircode lookup

GET | https://ws.postcoder.com/pcw/[apikey]/address/ie/[eircode-or-address-fragment]

Try it now

Optional querystring parameters

ParameterDescriptionValuesDefault
formatSets the data format of the response; the default is json unless header of application/xml is detectedxml, jsonjson
identifierSets an identifier like "checkout" or "contactform" to help you group requests within your search history
linesSets the number of address lines over which to display the first part of each address in the response0, 1, 2, 3, 40
includeSpecifies the extra address fields to include within the address lines, using a comma-delimited listcounty, posttown, postcode
excludeSpecifies the address fields to exclude within the address lines, using a comma-delimited listpobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality
addtagsSpecifies the extra address fields to include within the response, using a comma-delimited listSee Additional data fields
postcodeonlyLimits the request to a postcode-only search rather than matching the search term on other parts of an addresstrue, falsefalse
aliasIncludes aliases for addresses known to and accepted by Royal Mailtrue, falsefalse
callbackSets the name of your JSONP callback function
pageSpecifies the page of results to return where 0 is the first page0, 1, 2, 3...0

Tip

  • Be sure to URI encode the search term with percent encoding before sending your request to Postcoder. For example, NR14 7PZ should become NR14%207PZ

Response fields for postal addresses

We recommend you use the following fields for a UK or Irish postal address:

UKIreland
addressline1addressline1
addressline2addressline2
posttownposttown
postcodecounty
 postcode

Response fields

FieldDescriptionExampleReturned by default?
summarylineA string containing the entire addressAllies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZYes
addressline[n]Contains the [n]th line of the address for printing on a label. Won't contain posttown, postcode, or any fields excluded with ?exclude=Allies Computing LtdUse ?lines=[n] to set number of required address lines
poboxPO Box number, if present Yes
organisationOrganisation name at that address, if presentAllies Computing LtdYes
departmentnameDepartment nameYes
buildingnameBuilding nameManor Farm BarnsYes
subbuildingnameSub-building nameYes
numberHouse/Flat number8Yes
premiseName of the premiseManor Farm BarnsYes
dependentstreetName of a dependent street if it is present in the addressYes
streetStreet nameFox RoadYes
doubledependentlocalityName of the double dependant locality, if it is present in the addressEagle Road Industrial EstateYes
dependentlocalityName of the dependent locality, if it is present in the addressFramingham PigotYes
posttownPosttown name. Always present in UK addressesNorwichYes
countyCounty nameNorfolkYes
postcodePostcode. Always present in UK addressesNR14 7PZYes
notyetbuiltBoolean value that displays if an address is a part of the "Not Yet Built" dataset from Royal MailtrueUse ?nyb=true
recodesColon separated list of the previous postcode, previous delivery point suffix and the date it changed (YYYYMM format)CM7 8PX:1A:200112Yes
morevaluesIndicates at least one more page of addresses for the lookuptrueYes
nextpagePage number for the next page of results2Yes
totalresultsTotal number of results for the lookup458Yes
longitudeThe longitude associated with the result1.3491603533Use ?addtags=longitude
latitudeThe latitude associated with the result52.5859730797Use ?addtags=latitude
uniquedeliverypointreferencenumberUnique Delivery Point Reference Number (UDPRN) - a unique number applied by Royal Mail to every UK delivery point17448021Use ?addtags=udprn
aliasIndicates if an address is an alias record.trueUse ?alias=true

Predictive address autocomplete

Autocomplete UK addresses and Irish addresses with predictive as-you-type suggestions.

Uses the latest PAF and Multiple Residence data from Royal Mail, and ECAD data from Eircode.

Example code

Step 1: Request URL - Return as-you-type suggestions

GET | https://ws.postcoder.com/pcw/autocomplete/find
?query=[first-letters-of-address]
&country=[country]
&apikey=[apikey]

Step 1: Querystring parameters

ParameterDescriptionRequiredValues
queryThe search term (minimum of three characters required, returns empty array otherwise)YesE.g. 1 birchwood h
pathfilterAllows you to narrow down the search using the ID of a suggestion that was not an address from a previous request (i.e. where the type was not "ADD")NoE.g. UK@STATE\|Suffolk@CTY\|{Rushmere St. Andrew@LOC,Ipswich@PTN,IP@PCDA}@LOC|{Birchwood Drive@STR,IP5-1EB@PCD}@PCD
countryThe 2 letter ISO 3166-1 country codeYesUK or IE
apikeyThe API keyYesE.g. PCW45-12345-12345-1234X
formatThe response format; default is JSON unless an application/xml header is detectedNojson or xml
maximumresultsThe maximum number of results to return; default is 30No5 - 30
enablefacetsGroups some results together geographically when the search term is too vague to make a confident suggestion, making drilling down with ?pathfilter easier. Set to false to disable this behaviour.Nofalse

Tip

  • If you're having issues with Chrome's autofill blocking your suggestions, use the autocomplete="xyz" attribute in your input tag. Chrome ignores the autocomplete="off" attribute.

Step 1: Response fields

FieldDescriptionExampleReturned by default?
idThe ID of the address or place52752859Yes
typeThe type of suggestion; see definitions belowADDYes
summarylineThe summary of the address or place1 Birchwood Hall CottagesYes
locationsummaryThe location associated with the address or placeChathill, Northumberland, NE67 5LGYes
countThe number of further suggestions nested within the suggestion66Yes

Definitions for the 'type' response field

NameDescription
ADDAddress
BGNBuilding group
BNABuilding name
CCNCounty
DSTDependent street
LADDistrict borough
LOCPlace
LOC2Dependent place
LOC3Double dependent place
NUMNumber
ORCOrganisation
ORDDepartment
PCDPostcode
PCDAPostcode area
PCDDPostcode district
PCDSPostcode sector
PCDU1Postcode unit 1
POBPO Box
SBNSub building name
STATEState
STRStreet
WORLDWorld

Step 2: Request URL - Return a full address

GET | https://ws.postcoder.com/pcw/autocomplete/retrieve
?id=[id-from-step-one]
&query=[query-from-step-one]
&country=[country]
&apikey=[apikey]

Step 2: Querystring parameters

ParameterDescriptionRequiredValues
idThe ID of a suggestion that was an address from a previous request (i.e. where the type was 'ADD')Yes6219058
queryThe original search termYesE.g. 1 birchwood h
countryThe 2 letter ISO 3166-1 country codeYesUK or IE
apikeyThe API keyYesE.g. PCW45-12345-12345-1234X
formatThe response format; default is JSON unless an application/xml header is detectedNojson or xml
identifierIdentify your lookup to make debugging and reviewing stats easierNoE.g. myform
linesThe number of lines over which to split the addressNo0, 1, 2, 3, 4
includeInclude extra address fields within the address lines returnedNocounty, posttown, postcode
excludeExclude address fields within the address lines returnedNopobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality
addtagsAdd extra address fields such as UDPRN to the returnNoSee Additional data fields
callbackUse to specify the name of your JSONP callback functionNo

Step 2: Response fields

FieldDescriptionExampleReturned by default?
summarylineA string containing the entire addressAllies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZYes
addressline[n]Contains the [n]th line of the address for printing on a label. Won't contain posttown, postcode, or any fields excluded with ?exclude=Allies Computing LtdUse ?lines=[n] to set number of required address lines
poboxPO Box number, if present Yes
organisationOrganisation name at that address, if presentAllies Computing LtdYes
departmentnameDepartment nameYes
buildingnameBuilding nameManor Farm BarnsYes
subbuildingnameSub-building nameYes
numberHouse/Flat number8Yes
premiseName of the premiseManor Farm BarnsYes
dependentstreetName of a dependent street if it is present in the addressYes
streetStreet nameFox RoadYes
doubledependentlocalityName of the double dependant locality, if it is present in the addressEagle Road Industrial EstateYes
dependentlocalityName of the dependent locality, if it is present in the addressFramingham PigotYes
posttownPosttown name. Always present in UK addressesNorwichYes
countyCounty nameNorfolkYes
postcodePostcode. Always present in UK addressesNR14 7PZYes
notyetbuiltBoolean value that displays if an address is a part of the "Not Yet Built" dataset from Royal MailtrueUse ?nyb=true
recodesColon separated list of the previous postcode, previous delivery point suffix and the date it changed (YYYYMM format)CM7 8PX:1A:200112Yes
morevaluesIndicates at least one more page of addresses for the lookuptrueYes
nextpagePage number for the next page of results2Yes
totalresultsTotal number of results for the lookup458Yes
longitudeThe longitude associated with the result1.3491603533Use ?addtags=longitude
latitudeThe latitude associated with the result52.5859730797Use ?addtags=latitude
aliasIndicates if an address is an alias record.trueUse ?alias=true

Examples

Show suggestions for "1 birchwood h"

https://ws.postcoder.com/pcw/autocomplete/find
?query=1%20birchwood%20h
&country=UK
&apikey=PCW45-12345-12345-1234X
&format=json

[
	{
		"id": "16291869",
		"type": "ADD",
		"summaryline": "1 Birchwood Hall Cottages",
		"locationsummary": "Chathill, Northumberland, NE67 5LG",
		"count": 1
	},
	...
	{
		"id": "UK@STATE|Greater London@CTY|London@LOC|Hackney@LAD|{Woodberry Grove@STR,N4@PCDD}@STR|{N4-1FR@PCD,Birchwood Apartments@BNA,Flat 1-66@RNG}@PCD",
		"type": "PCD",
		"summaryline": "Flat 1-66, Birchwood Apartments, N4 1FR",
		"locationsummary": "Woodberry Grove, London, Hackney",
		"count": 66
	}
]

Expand the "Flat 1-66, Birchwood Apartments, N4 1FR" suggestion found above

https://ws.postcoder.com/pcw/autocomplete/find
?query=1%20birchwood%20h
&pathfilter=UK@STATE|Greater%20London@CTY|London@LOC|Hackney@LAD|{Woodberry%20Grove@STR,N4@PCDD}@STR|{N4-1FR@PCD,Birchwood%20Apartments@BNA,Flat%201-66@RNG}@PCD
&country=UK
&apikey=PCW45-12345-12345-1234X
&format=json

[
	{
		"id": "52752859",
		"type": "ADD",
		"summaryline": "Flat 1",
		"locationsummary": "Birchwood Apartments, Woodberry Grove, London, Hackney, N4 1FR",
		"count": 1
	},
	...
	{
		"id": "52752397",
		"type": "ADD",
		"summaryline": "Flat 64",
		"locationsummary": "Birchwood Apartments, Woodberry Grove, London, Hackney, N4 1FR",
		count: 1
	}
]

Retrieve full address for the "Flat 1, Birchwood Apartments" suggestion found above

https://ws.postcoder.com/pcw/autocomplete/retrieve
?id=52752859
&query=1%20birchwood%20h
&country=UK
&apikey=PCW45-12345-12345-1234X
&format=json
&lines=2

[
	{
		"addressline1": "Flat 1, Birchwood Apartments",
		"addressline2": "Woodberry Grove",
		"summaryline": "Flat 1, Birchwood Apartments, Woodberry Grove, London, Greater London, N4 1FR",
		"subbuildingname": "Flat 1",
		"buildingname": "Birchwood Apartments",
		"premise": "Flat 1, Birchwood Apartments",
		"street": "Woodberry Grove",
		"posttown": "London",
		"county": "Greater London",
		"postcode": "N4 1FR"
	}
]

Additional data fields

Include additional fields by appending ?addtags=[comma-delimited-addtags-field-names] to your request URL.

Address data

DescriptionAddtags field nameTag name returned in output
Delivery Point Suffixdeliverypointsuffixdeliverypointsuffix
Unique Delivery Point Reference Number (UDPRN)udprnuniquedeliverypointreferencenumber
Multiple Occupancy Count - count of the number of multiple occupancy addresses for the delivery pointmultipleoccupancycountmultipleoccupancycount
Administrative County (top tier local government)administrativecountyadministrativecounty
Former Postal Countypostalcountypostalcounty
Traditional Countytraditionalcountytraditionalcounty
User Category (residential 'R', Non-residential 'N', or Large 'L')usercategoryusercategory
Sortcode (for Royal Mail Mailsort)sortcodesortcode
Country code (within the United Kingdom)countrycodecountrycode
Country name (within the United Kingdom)countrycountry
Welsh language alternative for dependent street fieldwelsh_dependentstreetwelsh_dependentstreet
Welsh language alternative for street fieldwelsh_streetwelsh_street
Welsh language alternative for double dependent locality fieldwelsh_doubledependentlocalitywelsh_doubledependentlocality
Welsh language alternative for dependent locality fieldwelsh_dependentlocalitywelsh_dependentlocality
Welsh language alternative for post town fieldwelsh_posttownwelsh_posttown

Coordinates

DescriptionAddtags field nameTag name returned in output
Easting OS Grid Reference (1m precision in units of 1m)grideast1metregrideasting
Northing OS Grid Reference (1m precision in units of 1m)gridnorth1metregridnorthing
Latitude (OSGB36)latitudeosgb36latitudeosgb
Longitude (OSGB36)longitudeosgb36longitudeosgb
Latitude (ETRS89)latitudeetrs89latitude
Longitude (ETRS89)longitudeetrs89longitude

Census data

DescriptionAddtags field nameTag name returned in output
2011 Census Output Areaoa11oa11
2011 Census Lower Layer Super Output Arealsoa11lsoa11
2011 Census Middle Layer Super Output Areamsoa11msoa11
2001 Census Output Areacensusoutputarea_2001censusoutputarea_2001
2001 Census Lower Layer Super Output Areacensuslowerlayersuperoutputarea_2001censuslowerlayersuperoutputarea_2001
2001 Census Middle Layer Super Output Areacensusmiddlelayersuperoutputarea_2001censusmiddlelayersuperoutputarea_2001
2001 Census Area Statistics (CAS) Wardcensusareastatisticswardcodecensusareastatisticswardcode
2005 Statistical Wardstatisticalwardcode_2005statisticalwardcode_2005

NHS data

DescriptionAddtags field nameTag name returned in output
NHS Commissioning Region Code (ONS GSS)commissioningregioncode_gsscommissioningregioncode_gss
NHS Commissioning Region Namecommissioningregionnamecommissioningregionname
NHS Area Team Code (NHS)areateamcode_nhsareateamcode_nhs
NHS Area Team Code (ONS GSS)areateamcode_gssareateamcode_gss
NHS Area Team Nameareateamnameareateamname
NHS Clinical Commissioning Group Code (NHS)clinicalcommissioninggroupcode_nhsclinicalcommissioninggroupcode_nhs
NHS Clinical Commissioning Group Code (ONS GSS)clinicalcommissioninggroupcode_gssclinicalcommissioninggroupcode_gss
NHS Clinical Commissioning Group Nameclinicalcommissioninggroupnameclinicalcommissioninggroupname

Government data

DescriptionAddtags field nameTag name returned in output
Local Authority Ward Codelocalauthoritywardcodelocalauthoritywardcode
Local Authority Codelocalauthoritycodelocalauthoritycode
Local Authority Namelocalauthoritynamelocalauthorityname
Electoral Ward Codeelectoralwardcodeelectoralwardcode
Electoral Ward Nameelectoralwardnameelectoralwardname
Electoral County Codeelectoralcountycodeelectoralcountycode
Electoral County Nameelectoralcountynameelectoralcountyname
Parish Codeparishcodeparishcode
Westminster Parliamentary Constituency Codeparliamentaryconstituencycodeparliamentaryconstituencycode
Westminster Parliamentary Constituency Nameparliamentaryconstituencynameparliamentaryconstituencyname
European Electoral Region Codeeuropeanelectoralregioncodeeuropeanelectoralregioncode
European Electoral Region Nameeuropeanelectoralregionnameeuropeanelectoralregionname
National Park Namenationalparknamenationalparkname
National Park Codenationalparkcodenationalparkcode

International address lookup

Lookup international addresses using the first address line and / or postal code.

Request URL

GET | https://ws.postcoder.com/pcw/[apikey]/address/[country-code]/[address-fragment]

Example

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/us/1600%20PENNSYLVANIA,%2020500-0001
?format=json
&identifier=mytestlookup
&lines=4

[
	{
		"addressline1": "PRESIDENT",
		"addressline2": "1600 PENNSYLVANIA AVE NW",
		"addressline3": "WASHINGTON DC  20500-0001",
		"addressline4": "UNITED STATES",
		"summaryline": "PRESIDENT, 1600 PENNSYLVANIA AVE NW, WASHINGTON DC  20500-0001, UNITED STATES",
		"organisation": "PRESIDENT",
		"number": "1600",
		"premise": "1600",
		"street": "PENNSYLVANIA AVE NW",
		"posttown": "WASHINGTON",
		"state": "DISTRICT OF COLUMBIA",
		"stateabbreviation": "DC",
		"postcode": "20500-0001",
		"country": "UNITED STATES"
	}
]

Supported countries and country codes

Code Country Buildings Streets Towns Updated
AF Afghanistan Quarterly
AL Albania Quarterly
AQ Antarctica Quarterly
DZ Algeria Quarterly
AS American Samoa Monthly
AD Andorra Quarterly
AO Angola Quarterly
AG Antigua and Barbuda Quarterly
AZ Azerbaijan Quarterly
AR Argentina Quarterly
AU Australia Quarterly
AT Austria Monthly
BS Bahamas Quarterly
BH Bahrain Quarterly
BD Bangladesh Quarterly
AM Armenia Quarterly
BB Barbados Quarterly
BE Belgium Quarterly
BM Bermuda Quarterly
BT Bhutan Quarterly
BO Bolivia Quarterly
BA Bosnia and Herzegovina Quarterly
BW Botswana Quarterly
BR Brazil Quarterly
BZ Belize Quarterly
IO Br. Indian Ocean Ter. Quarterly
SB Solomon Islands Quarterly
VG Virgin Islands, British Quarterly
BN Brunei Darussalam Quarterly
BG Bulgaria Quarterly
MM Myanmar Quarterly
BI Burundi Quarterly
BY Belarus Quarterly
KH Cambodia Quarterly
CM Cameroon Quarterly
CA Canada Quarterly
CV Cape Verde Quarterly
KY Cayman Islands Quarterly
CF Central African Rep. Quarterly
LK Sri Lanka Quarterly
TD Chad Quarterly
CL Chile Quarterly
CN China Quarterly
TW Taiwan Quarterly
CX Christmas Island Quarterly
CC Cocos (Keeling) Islands Quarterly
CO Colombia Quarterly
KM Comoros Quarterly
YT Mayotte Quarterly
CG Congo (Rep.) Quarterly
CD Congo (Dem. Rep.) Quarterly
CK Cook Islands Quarterly
CR Costa Rica Quarterly
HR Croatia Quarterly
CU Cuba Quarterly
CY Cyprus Quarterly
CZ Czech Republic Quarterly
BJ Benin Quarterly
DK Denmark Quarterly
DM Dominica Quarterly
DO Dominican Republic Quarterly
EC Ecuador Quarterly
SV El Salvador Quarterly
GQ Equatorial Guinea Quarterly
ET Ethiopia Quarterly
ER Eritrea Quarterly
EE Estonia Quarterly
FO Faröe Islands Quarterly
FK Falkland Is. (Malvinas) Quarterly
GS S. Georgia and S. Sandwich Quarterly
FJ Fiji Quarterly
FI Finland Quarterly
AX Aland Islands Quarterly
FR France Quarterly
GF French Guiana Quarterly
PF French Polynesia Quarterly
TF French Southern Territories Quarterly
DJ Djibouti Quarterly
GA Gabon Quarterly
GE Georgia Quarterly
GM Gambia Quarterly
PS Palestinian Territory Quarterly
DE Germany Quarterly
GH Ghana Quarterly
GI Gibraltar Quarterly
KI Kiribati Quarterly
GR Greece Quarterly
GL Greenland Quarterly
GD Grenada Quarterly
GP Guadeloupe Quarterly
GU Guam Monthly
GT Guatemala Quarterly
GN Guinea Quarterly
GY Guyana Quarterly
HT Haiti Quarterly
VA Vatican City Quarterly
HN Honduras Quarterly
HK Hong Kong Quarterly
HU Hungary Quarterly
IS Iceland Quarterly
IN India Quarterly
ID Indonesia Quarterly
IR Iran Quarterly
IQ Iraq Quarterly
IE Ireland Quarterly
IL Israel Quarterly
IT Italy Quarterly
CI Côte d'Ivoire Quarterly
JM Jamaica Quarterly
JP Japan Quarterly
KZ Kazakhstan Quarterly
JO Jordan Quarterly
KE Kenya Quarterly
KP Korea (Dem. Rep.) Quarterly
KR Korea (Rep.) Quarterly
KW Kuwait Quarterly
KG Kyrgyzstan Quarterly
LA Laos Quarterly
LB Lebanon Quarterly
LS Lesotho Quarterly
LV Latvia Quarterly
LR Liberia Quarterly
LY Libya Quarterly
LI Liechtenstein Quarterly
LT Lithuania Quarterly
LU Luxembourg Quarterly
MO Macao Quarterly
MG Madagascar Quarterly
MW Malawi Quarterly
MY Malaysia Quarterly
MV Maldives Quarterly
ML Mali Quarterly
MT Malta Quarterly
MQ Martinique Quarterly
MR Mauritania Quarterly
MU Mauritius Quarterly
MX Mexico Quarterly
MC Monaco Quarterly
MN Mongolia Quarterly
MD Moldova Quarterly
ME Montenegro Quarterly
MS Montserrat Quarterly
MA Morocco Quarterly
MZ Mozambique Quarterly
OM Oman Quarterly
NA Namibia Quarterly
NR Nauru Quarterly
NP Nepal Quarterly
NL Netherlands Quarterly
CW Curacao Quarterly
AW Aruba Quarterly
SX Sint Maarten Quarterly
BQ Bonaire, Sint Eustatius And Saba Quarterly
NC New Caledonia Quarterly
VU Vanuatu Quarterly
NZ New Zealand Quarterly
NI Nicaragua Quarterly
NE Niger Quarterly
NG Nigeria Quarterly
NU Niue Quarterly
NF Norfolk Island Quarterly
NO Norway Quarterly
MP Northern Mariana Islands Monthly
UM United States Minor Outlying Islands Quarterly
FM Micronesia Monthly
MH Marshall Islands Monthly
PW Palau Monthly
PK Pakistan Quarterly
PA Panama Quarterly
PG Papua New Guinea Quarterly
PY Paraguay Quarterly
PE Peru Quarterly
PH Philippines Quarterly
PN Pitcairn Quarterly
PL Poland Quarterly
PT Portugal Quarterly
GW Guinea-Bissau Quarterly
TL Timor-Leste Quarterly
PR Puerto Rico Monthly
QA Qatar Quarterly
RE Réunion Quarterly
RO Romania Quarterly
RU Russia Quarterly
RW Rwanda Quarterly
BL Saint-Barthélemy Quarterly
SH Saint Helena Quarterly
KN St. Kitts and Nevis Quarterly
AI Anguilla Quarterly
LC Saint Lucia Quarterly
MF Saint Martin Quarterly
PM Saint Pierre and Miquelon Quarterly
VC St. Vincent and Grenadines Quarterly
SM San Marino Quarterly
ST Sao Tomé and Principe Quarterly
SA Saudi Arabia Quarterly
SN Senegal Quarterly
RS Serbia Quarterly
SC Seychelles Quarterly
SL Sierra Leone Quarterly
SG Singapore Quarterly
SK Slovakia Quarterly
VN Viet Nam Quarterly
SI Slovenia Quarterly
SO Somalia Quarterly
ZA South Africa Quarterly
ZW Zimbabwe Quarterly
ES Spain Quarterly
SS South Sudan Quarterly
SD Sudan Quarterly
EH Western Sahara Quarterly
SR Suriname Quarterly
SJ Svalbard and Jan Mayen Quarterly
SZ Swaziland Quarterly
SE Sweden Quarterly
CH Switzerland Quarterly
SY Syria Quarterly
TJ Tajikistan Quarterly
TH Thailand Quarterly
TG Togo Quarterly
TK Tokelau Quarterly
TO Tonga Quarterly
TT Trinidad and Tobago Quarterly
AE United Arab Emirates Quarterly
TN Tunisia Quarterly
TR Turkey Quarterly
TM Turkmenistan Quarterly
TC Turks and Caicos Is. Quarterly
TV Tuvalu Quarterly
UG Uganda Quarterly
UA Ukraine Quarterly
MK Macedonia, TFYR Quarterly
EG Egypt Quarterly
UK United Kingdom Daily
TZ Tanzania Quarterly
US United States of America Every two months
VI United States Virgin Islands Monthly
BF Burkina Faso Quarterly
UY Uruguay Quarterly
UZ Uzbekistan Quarterly
VE Venezuela Quarterly
WF Wallis and Futuna Quarterly
WS Samoa Quarterly
YE Yemen Quarterly
ZM Zambia Quarterly

Country endpoint

Return a list of countries and their associated codes to make it easier to specify a country code in an international address lookup. This list conforms to ISO-3166.

Request URL

GET | https://ws.postcoder.com/pcw/[apikey]/countries

Example

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/countries

[
	{
		"countryname":"Afghanistan",
		"iso2":"AF",
		"iso3":"AFG",
		"iso3number":"4"
	},
	{
		"countryname":"Aland Islands",
		"iso2":"AX",
		"iso3":"ALA",
		"iso3number":"248"
	},
	...
]

Tips

  • Note that ISO-3166 specifies "GB" as the code for the United Kingdom. You can use this in your calls, but in our examples we use "UK" as the United Kingdom is not synonymous with Great Britain as the GB code might suggest.
  • Use countryname to populate your list of countries and iso2 as the country code in your calls to address lookup endpoints.

AddressBase API for address lookup

Postcoder provides you with access to AddressBase Core and AddressBase Premium through an API using the latest data from Ordnance Survey.

You can enable access on your API key using the Data Options within your Postcoder account, or by contacting us directly.

About AddressBase

AddressBase is a suite of data products from Ordnance Survey built from council records. Councils add records to a national data hub which is used by an organisation called GeoPlace to generate rich datasets showing how the United Kingdom is made up.

Ordnance Survey is the national mapping agency for Great Britain; there is a separate agency for Northern Ireland and others for the Crown Dependencies in the Channel Islands. AddressBase products therefore only provide data for the British mainland plus the Shetland Isles, Orkney, the Hebrides, the Isle of Wight and the Scilly Isles.

Use cases for AddressBase

  • Navigation and mapping applications can make use of property level coordinates. Coordinates are available in terms of Eastings and Northings or Latitude and Longitude using coordinates common to online maps, GPS and sat nav systems.
  • If you are involved in delivering national infrastructure projects, the Unique Property Reference Number (UPRN) which identifies each building in Great Britain is a critical key field which ties into council records.
  • If you have an interest in buildings and properties individually or collectively then you will want to have access to the keys in council records.

Help me choose between AddressBase Core and AddressBase Premium

AddressBase Core and AddressBase Premium are built from the same source data.

AddressBase Core is designed for people who want to know geographical positioning details for properties and people who are after keys into other systems. For many use cases involving property coordinates and UPRNs, the core data will suit your purposes very well.

AddressBase Core contains geographic rather than postal address details but also contains the crucial key fields that can be used to get a postal address from Royal Mail. The key fields to link to Royal Mail are the Unique Delivery Point Reference Number (UDPRN), which is Royal Mail’s recommended key, or you can use the composite key of Postcode + Delivery Point Suffix. These data elements are provided where it has been possible to match a record to PAF. Please note that in the vast majority of cases the geographic address and postal address as used by Royal Mail’s mail sortation systems is identical however remote and rural locations in particular will have very different addresses.

On the other hand if you need to know more in depth details about a property – for example you might want to know what sort of road it is on for assessing insurance quotes or you might want to know the date a particular property or street was first entered on council records – you will need the more in depth data provided by AddressBase Premium. AddressBase Premium also directly provides the postal routing address used by Royal Mail where it has been possible to match the records together. This means you can retrieve a correct postal address as well as a geographic address using AddressBase Premium.

AddressBase request URLs and examples

Once enabled, your API key determines whether you access AddressBase Core or AddressBase Premium.

Address lookup using AddressBase Core / Premium

GET | https://ws.postcoder.com/pcw/[apikey]/addressbase/[postcode-or-address-fragment]

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2

UPRN lookup using AddressBase Core / Premium

GET | https://ws.postcoder.com/pcw/[apikey]/addressbase/uprn/[single-uprn-or-comma-delimited-uprns]

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/uprn/2630163102
?format=json
&identifier=mytestlookup
&lines=2

Address lookup using PAF enriched with AddressBase Core / Premium

GET | https://ws.postcoder.com/pcw/[apikey]/pafaddressbase/[postcode-or-address-fragment]

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/pafaddressbase/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2

DPA lookup using AddressBase Premium only

GET | https://ws.postcoder.com/pcw/[apikey]/addressbase/dpa/[postcode-or-address-fragment]

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/dpa/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=uprn

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/dpa/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=addressbase

LPI lookup using AddressBase Premium only

GET | https://ws.postcoder.com/pcw/[apikey]/addressbase/lpi/[postcode-or-address-fragment]

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/lpi/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=uprn

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/lpi/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=addressbase

DPA and LPI lookup using AddressBase Premium only

GET | https://ws.postcoder.com/pcw/[apikey]/addressbase/dpalpi/[postcode-or-address-fragment]

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/dpalpi/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=uprn

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/dpalpi/NR14%207PZ
?format=json
&identifier=mytestlookup
&lines=2
&addtags=addressbase

Optional querystring parameters

ParameterDescriptionValuesDefault
formatSets the data format of the response; the default is json unless header of application/xml is detectedxml, jsonjson
identifierSets an identifier like "checkout" or "contactform" to help you group requests within your search history
linesSets the number of address lines over which to display the first part of each address in the response0, 1, 2, 3, 40
includeSpecifies the extra address fields to include within the address lines, using a comma-delimited listcounty, posttown, postcode
excludeSpecifies the address fields to exclude within the address lines, using a comma-delimited listpobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality
addtagsSpecifies the extra fields to include within the response, using a comma-delimited list. A value of 'addressbase' returns all data (except 'tile' data); the other values shown here allow you to return particular fields and groups of fields. In addition to these AddressBase-specific values, see the additional data fieldsaddressbase, uprn, deliverypointaddress, lpis, blpu, classifications, organisations, applicationcrossreferences, tile, latitude, longitude...
callbackSets the name of your JSONP callback function
pageSpecifies the page of results to return where 0 is the first page0, 1, 2, 3...0

AddressBase response fields

The following fields are returned in the response for AddressBase Core:

FieldDescription
summarylineThe address given in a single field separated by commas. Where matched against PAF this is a postal address
organisationOrganisation name. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
departmentnameWhere there is a distinct delivery point for receipt of mail for a department, the department name is indicated here. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
poboxWhere linked to a PAF PO Box holder, this is the PO Box number. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
subbuildingnameSub-building name – usually a unit number or flat number. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
buildingnameName of the building. For instance Nelson House. May or may not be further sub-divided. Often contains what Royal Mail would class as a Dependent Street. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
numberThe street number. Note that this may be alpha numeric. E.g. 1A. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
uniquedeliverypointreferencenumberRoyal Mail’s unique identifier for a Delivery Point (i.e. where postal delivery staff go to deliver mail). Assigned by Royal Mail and only available where an address record has been matched against PAF. Provides a unique identifier and designed to be unique over the life time of a delivery point
premiseA concatenation of the Department, PO Box, Sub-building Name, Building Name and Number (in that order). Useful if you have a single field in your database for storing the premise
dependentstreetA street that needs another one for access. For example a cul-de-sac or a named parade of shops on a main road
streetThe main street on which a property is situated. Commonly seems to be a main road especially in rural and remote settings. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
doubledependentlocalityThis is a smaller industrial estate or sub-division of a town or village. The data in this field comes from Royal Mail if the record has been matched to a delivery point but the equivalent data from council records goes into Dependentlocality
dependentlocalityThis is analogous to Royal Mail’s Double Dependent Locality and is generally representative of retail parks or industrial estates. Source: Council records or, if PAF matched, Royal Mail
townnameThis is analogous to Royal Mail’s Dependent Locality and represents a suburb or small town. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
posttownWhere an address record has been matched against PAF, this is the post town responsible for mail sorting. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
postcodeThis is the Postcode assigned by Royal Mail
deliverypointsuffixThe Delivery Point Suffix used by Royal Mail. This, along with a Postcode, provides a unique identifier for a delivery point at a point in time. Source: Royal Mail
latitudeThis is the latitude on the ETRS89 projection. See rpc
longitudeThis is the longitude on the ETRS89 projection. See rpc
grideastingThe Easting on Ordnance Survey’s British National Grid. The units are in metres to 2 decimal places. See rpc
gridnorthingThe Northing on Ordnance Survey’s British National Grid. The units are in metres to 2 decimal places. See rpc
uprnThe Unique Property Reference Number – the primary key field for AddressBase data. Assigned by GeoPlace or Ordnance Survey
parentuprnWhere a particular property is part of another one (for example a flat in a block of flats or a unit on a business park) the owning property’s UPRN is indicated here. Please note that this is not the same as Royal Mail’s multiple residence indicator for postal purposes but is a good indicator that this is not a stand-alone property
usrnThe Unique Street Reference Number – every street under council control has its own unique identifier and this is it
changecodeIndicates how this record was last amended on the national hub. AddressBase Core only
toidThe topographical identifier which associates this record with OS MasterMap. AddressBase Core only
classificationcodeDescribes the classification of the property according to council records
rpcTells you how accurate the coordinates are. For safety critical applications this may be a particularly important field:


1 – Central Internal Position – The address is contained within an OS MasterMap Topography Later building and within 2.5m of its calculated centre. Or the coordinates represent the best possible position based on the nature of the premises

2- General Internal Position – The address is contained within an OS MasterMap Topography Later building but is more than 2.5m away from its calculated centre. Or the seed is in an internal position based on the nature of the premises

3 – Transitional Position – The address has been changed from Under Development to Live within the last 6 months. It has been captured to a high level of positional accuracy but pending large scale mapping updates still may be moved

4 – Street Location – The address is plotted in accordance with the declared street start and end coordinates

5 – Postcode Unit position – The address has been captured to Postcode Unit level and will be updated when more information becomes available. It is likely that every property on the Postcode will be sharing these same coordinates

9 – Low Accuracy – The address has been captured to a lower level of accuracy and will be updated as a priority over the coming months
gsscodeProvided by the Office for National Statistics and used for official records. Codes are structured: the first three characters are an Entity Code and the remaining 6 characters are the particular instance. Entity Codes are: E06 (Unitary Authority); E07 (Local Authority District Council); E08 (Metropolitan Borough Council); and E09 (London Borough)
lastupdatedateThe date this record was last updated

Eircode API for Irish address lookup

Postcoder provides you with access to Eircode ECAD through an API using the latest data from Capita Ireland.

You can enable access on your API key using the Data Options within your Postcoder account, or by contacting us directly.

Eircode request URLs

Irish address lookup using Eircode

GET | https://ws.postcoder.com/pcw/[apikey]/address/ie/[eircode-or-address-fragment]

Irish reverse geocoding using Eircode

GET | https://ws.postcoder.com/pcw/[apikey]/rgeo/ie/[latitude]/[longitude]?distance=[distance-in-metres]

Irish geocoding using Eircode

GET | https://ws.postcoder.com/pcw/[apikey]/position/ie/[eircode]

Eircode request examples

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/ie/D02X285
?format=json
&identifier=mytestlookup
&lines=2
&addtags=latitude,longitude

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/rgeo/ie/53.332067/-6.255492
?distance=50
&format=json
&identifier=mytestlookup

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/position/ie/D02X28
?format=json
&identifier=mytestlookup

Tip

Most but not all Irish addresses require a post town. Postcoder will return a post town in the response only when it is required.

Optional querystring parameters

ParameterDescriptionValuesDefault
formatSets the data format of the response; the default is json unless header of application/xml is detectedxml, jsonjson
identifierSets an identifier like "checkout" or "contactform" to help you group requests within your search history
linesSets the number of address lines over which to display the first part of each address in the response0, 1, 2, 3, 40
includeSpecifies the extra address fields to include within the address lines, using a comma-delimited listcounty, posttown, postcode
excludeSpecifies the address fields to exclude within the address lines, using a comma-delimited listpobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality
languageSpecifies the language to return the address in - either Irish (gle) or English (eng)gle, engeng
callbackSets the name of your JSONP callback function
pageSpecifies the page of results to return where 0 is the first page0, 1, 2, 3...0

Not Yet Built API for addresses under construction

Postcoder provides you with access to Not Yet Built through an API using the latest data from Royal Mail.

You can enable access on your API key using the Data Options within your Postcoder account, or by contacting us directly.

NYB request URL

GET | https://ws.postcoder.com/pcw/[apikey]/nyb/uk/[postcode-or-address-fragment]

NYB request example

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/nyb/uk/NR147P
?format=json
&identifier=mytestlookup
&lines=2

Optional querystring parameters

ParameterDescriptionValuesDefault
formatSets the data format of the response; the default is json unless header of application/xml is detectedxml, jsonjson
identifierSets an identifier like "checkout" or "contactform" to help you group requests within your search history
linesSets the number of address lines over which to display the first part of each address in the response0, 1, 2, 3, 40
includeSpecifies the extra address fields to include within the address lines, using a comma-delimited listcounty, posttown, postcode
excludeSpecifies the address fields to exclude within the address lines, using a comma-delimited listpobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality
addtagsSpecifies the extra address fields to include within the response, using a comma-delimited listSee Additional data fields
callbackSets the name of your JSONP callback function
pageSpecifies the page of results to return where 0 is the first page0, 1, 2, 3...0

UK geocoding

Lookup coordinates for a postcode in the UK.

Uses the latest data from the Office for National Statistics.

Example code

Request URL

Postcode to geodata

GET | https://ws.postcoder.com/pcw/[apikey]/position/uk/[postcode]

Full address with geodata

GET | https://ws.postcoder.com/pcw/[apikey]/address/uk/[postcode-or-address-fragment]?addtags=latitude,longitude

Try it now

Optional querystring parameters

ParameterDescriptionValuesDefault
formatSets the data format of the response; the default is json unless header of application/xml is detectedxml, jsonjson
identifierSets an identifier like "checkout" or "contactform" to help you group requests within your search history
callbackSets the name of your JSONP callback function




UK reverse geocoding

Lookup street addresses in the UK using latitude and longitude.

Uses the latest data from Royal Mail and the Office for National Statistics.

Request URL

GET | https://ws.postcoder.com/pcw/[apikey]/rgeo/uk/[latitude]/[longitude]?distance=[distance-in-metres]

Example

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/rgeo/uk/52.5859714116/1.3492192897
?distance=50
&format=json
&identifier=mytestlookup

Optional querystring parameters

ParameterDescriptionValuesDefault
formatSets the data format of the response; the default is json unless header of application/xml is detectedxml, jsonjson
identifierSets an identifier like "checkout" or "contactform" to help you group requests within your search history
callbackSets the name of your JSONP callback function

UK street lookup

Lookup the UK street(s) for a postcode.

Uses the latest PAF and Multiple Residence data from Royal Mail.

Request URL

GET | https://ws.postcoder.com/pcw/[apikey]/street/uk/[postcode]

Example

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/street/uk/NR147P
?format=json
&identifier=mytestlookup

Optional querystring parameters

ParameterDescriptionValuesDefault
formatSets the data format of the response; the default is json unless header of application/xml is detectedxml, jsonjson
identifierSets an identifier like "checkout" or "contactform" to help you group requests within your search history
callbackSets the name of your JSONP callback function

UDPRN lookup

Lookup a UK address using a UDPRN.

Uses the latest PAF and Multiple Residence data from Royal Mail.

Request URL

GET | https://ws.postcoder.com/pcw/[apikey]/udprn/[udprn]

Example

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/udprn/1744802
?format=json
&identifier=mytestlookup
&lines=2

Optional querystring parameters

ParameterDescriptionValuesDefault
formatSets the data format of the response; the default is json unless header of application/xml is detectedxml, jsonjson
identifierSets an identifier like "checkout" or "contactform" to help you group requests within your search history
linesSets the number of address lines over which to display the first part of each address in the response0, 1, 2, 3, 40
includeSpecifies the extra address fields to include within the address lines, using a comma-delimited listcounty, posttown, postcode
excludeSpecifies the address fields to exclude within the address lines, using a comma-delimited listpobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocality
addtagsSpecifies the extra address fields to include within the response, using a comma-delimited listSee Additional data fields
callbackSets the name of your JSONP callback function

Paging

Up to 100 results can be returned at a time in response to a lookup. If there are more results beyond the current page for a UK or Eircode address search, the last result will include a morevalues field with a value of true.

We also include a nextpage field with the number of the next page, so you can easily append ?page=[nextpage] to your request. The totalresults field lets you know how many results in total have been returned by your search.

Notes:

  • First page = 0, second page = 1, etc...
  • If there are no more results beyond the current page, the morevalues field will not be present.
Live Start Loading Now Chatting Offline