address

This endpoint returns one or more full addresses for a given postcode or part of an address. It supports over 240 countries and provides UK postcode lookup, Irish Eircode lookup and global address lookup.

Ireland and Eircode: Enable access on your API key using the Data Options page or by contacting us.

Request URL

GET https://ws.postcoder.com/pcw/{apikey}/address/{countrycode}/{searchterm}

Path parameters

ParameterDescriptionExample
apikeyYour API keyPCW45-12345-12345-1234X
countrycodeThe 2-character country code, see supported countries belowuk
searchtermThe URL-encoded postcode or part of an address that you wish to look upnr14%207pz

Querystring parameters

ParameterDescriptionExample
formatSets the format of the response, xml or json (default unless "application/xml" header is detected)format=json
identifierSpecifies your own meaningful identifier for the request such as "websiteA" or "client123"; you can view usage for each identifier on the Identifier Usage page, which may be helpful when using your API key across multiple websites, apps or clientsidentifier=websiteA
linesSets the number of address lines (1-4) to include in the response so you can mirror the layout of your existing address form; use include and exclude below to further customise the address lineslines=2
includeSpecifies the extra address fields to include within the address lines using a comma-delimited list, supported values: county, posttown, postcodeinclude=county,posttown,postcode
excludeSpecifies the address fields to exclude within the address lines using a comma-delimited list, supported values: pobox, organisation, departmentname, buildingname, subbuildingname, number, premise, dependentstreet, street, doubledependentlocality, dependentlocalityexclude=organisation
addtagsSpecifies the extra address fields to include within the response using a comma-delimited list, supported values: latitude, longitude, udprn, deliverypointsuffix, usercategory... see additional response fields below for the full listaddtags=latitude,longitude
postcodeonlyLimits the request to a postcode-only search rather than matching the search term on other parts of an address, UK only, true or false (default)postcodeonly=true
aliasIncludes aliases for addresses known to and accepted by Royal Mail, UK only, true or false (default)alias=true
nybIncludes addresses from the Royal Mail Not Yet Built dataset, UK only, true or false (default)nyb=true
callbackSpecifies the name of your JSONP callback functioncallback=jsoncallback
pageSpecifies the page of results to return where page zero is the first, 0 (default), 1, 2...page=1

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

Example requests and responses

UK postcode lookup for "NR14 7PZ" with 2 address lines in the response

GET https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/uk/nr14%207pz?format=json&lines=2

[
	{
		"addressline1": "Allies Computing Ltd",
		"addressline2": "Manor Farm Barns, Fox Road, Framingham Pigot",
		"summaryline": "Allies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ",
		"organisation": "Allies Computing Ltd",
		"buildingname": "Manor Farm Barns",
		"premise": "Manor Farm Barns",
		"street": "Fox Road",
		"dependentlocality": "Framingham Pigot",
		"posttown": "Norwich",
		"county": "Norfolk",
		"postcode": "NR14 7PZ"
	},
	{
		"addressline1": "B 2 B Cashflow Solutions Ltd",
		"addressline2": "Manor Farm Barns, Fox Road, Framingham Pigot",
		...
		...
	}
]

US address lookup for "1600 Pennsylvania, 20500-0001" with 3 address lines (that exclude the organisation and country) in the response

GET https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/us/1600%20pennsylvania,%2020500-0001?format=json&lines=3&exclude=organisation,country

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

Irish Eircode lookup for "D02X285" with 2 address lines and coordinates in the response

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

[
	{
		"addressline1": "Department of Communications, Climate Action and Environment",
		"addressline2": "29-31 Adelaide Road",
		"summaryline": "Department of Communications, Climate Action and Environment, 29-31 Adelaide Road, Dublin 2, D02 X285",
		"organisation": "Department of Communications, Climate Action and Environment",
		"number": "29-31",
		"premise": "29-31",
		"street": "Adelaide Road",
		"posttown": "Dublin 2",
		"county": "Co. Dublin",
		"postcode": "D02 X285",
		"latitude": "53.332067",
		"longitude": "-6.255492"
	}
]

Response fields

FieldDescriptionExample
summarylineA summary of the address, ideal for displaying in a drop-down listAllies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ
addressline1The first line of the address, where the total number of address lines is defined by the lines querystring parameterManor Farm Barns
addressline2The second line of the addressFox Road
addressline3The third line of the addressFramingham Pigot
addressline4The fourth line of the addressAllies Computing Ltd
poboxThe PO Box number 
organisationThe organisation name at that addressAllies Computing Ltd
departmentnameThe department name
buildingnameThe building nameManor Farm Barns
subbuildingnameThe sub-building name
numberThe house or flat number8
premiseThe premise, a combination of buildingname, subbuildingname and numberManor Farm Barns
dependentstreetThe dependent street
streetThe streetFox Road
doubledependentlocalityThe double dependent localityEagle Road Industrial Estate
dependentlocalityThe dependent localityFramingham Pigot
posttownThe post townNorwich
countyThe countyNorfolk
postcodeThe postcodeNR14 7PZ
notyetbuiltA true or false indicating whether the address is from the Royal Mail Not Yet Built datasettrue
aliasA true or false indicating whether the address is a Royal Mail Alias recordtrue
recodesA colon-separated list of the previous postcode, previous delivery point suffix and the date it changed (YYYYMM format)CM7 8PX:1A:200112
stateThe stateDISTRICT OF COLUMBIA
stateabbreviationThe state abbreviationDC
morevaluesSet to true when there is at least one more page of results to requesttrue
nextpageThe page number for the next page of results to request2
totalresultsThe total number of results458

Additional response fields

These additional fields can be included in the response by using the addtags querystring parameter to specify a comma-delimited list of field names.

Example: addtags=latitude,longitude,udprn,deliverypointsuffix,usercategory

FieldDescriptionQuerystring parameter to use
Coordinate data
latitudeLatitude (ETRS89)addtags=latitude
longitudeLongitude (ETRS89)addtags=longitude
latitudeosgbLatitude (OSGB36)addtags=latitudeosgb36
longitudeosgbLongitude (OSGB36)addtags=longitudeosgb36
grideastingEasting OS Grid Reference (1m precision in units of 1m)addtags=grideast1metre
gridnorthingNorthing OS Grid Reference (1m precision in units of 1m)addtags=gridnorth1metre
Address fields
deliverypointsuffixDelivery Point Suffixaddtags=deliverypointsuffix
uniquedeliverypointreferencenumberUnique Delivery Point Reference Number (UDPRN)addtags=udprn
multipleoccupancycountMultiple Occupancy Count - count of the number of multiple occupancy addresses for the delivery pointaddtags=multipleoccupancycount
administrativecountyAdministrative County (top tier local government)addtags=administrativecounty
postalcountyFormer Postal Countyaddtags=postalcounty
traditionalcountyTraditional Countyaddtags=traditionalcounty
usercategoryUser Category (residential 'R', Non-residential 'N', or Large 'L')addtags=usercategory
sortcodeSortcode for Royal Mail Mailsortaddtags=sortcode
countrycodeCountry code (within the United Kingdom)addtags=countrycode
countryCountry name (within the United Kingdom)addtags=country
welsh_dependentstreetWelsh language alternative for dependent street fieldaddtags=welsh_dependentstreet
welsh_streetWelsh language alternative for street fieldaddtags=welsh_street
welsh_doubledependentlocalityWelsh language alternative for double dependent locality fieldaddtags=welsh_doubledependentlocality
welsh_dependentlocalityWelsh language alternative for dependent locality fieldaddtags=welsh_dependentlocality
welsh_posttownWelsh language alternative for post town fieldaddtags=welsh_posttown
Census data
oa112011 Census Output Areaaddtags=oa11
lsoa112011 Census Lower Layer Super Output Areaaddtags=lsoa11
msoa112011 Census Middle Layer Super Output Areaaddtags=msoa11
censusoutputarea_20012001 Census Output Areaaddtags=censusoutputarea_2001
censuslowerlayersuperoutputarea_20012001 Census Lower Layer Super Output Areaaddtags=censuslowerlayersuperoutputarea_2001
censusmiddlelayersuperoutputarea_20012001 Census Middle Layer Super Output Areaaddtags=censusmiddlelayersuperoutputarea_2001
censusareastatisticswardcode2001 Census Area Statistics (CAS) Wardaddtags=censusareastatisticswardcode
statisticalwardcode_20052005 Statistical Wardaddtags=statisticalwardcode_2005
NHS data
commissioningregioncode_gssNHS Commissioning Region Code (ONS GSS)addtags=commissioningregioncode_gss
commissioningregionnameNHS Commissioning Region Nameaddtags=commissioningregionname
areateamcode_nhsNHS Area Team Code (NHS)addtags=areateamcode_nhs
areateamcode_gssNHS Area Team Code (ONS GSS)addtags=areateamcode_gss
areateamnameNHS Area Team Nameaddtags=areateamname
clinicalcommissioninggroupcode_nhsNHS Clinical Commissioning Group Code (NHS)addtags=clinicalcommissioninggroupcode_nhs
clinicalcommissioninggroupcode_gssNHS Clinical Commissioning Group Code (ONS GSS)addtags=clinicalcommissioninggroupcode_gss
clinicalcommissioninggroupnameNHS Clinical Commissioning Group Nameaddtags=clinicalcommissioninggroupname
Government data
localauthoritywardcodeLocal Authority Ward Codeaddtags=localauthoritywardcode
localauthoritycodeLocal Authority Codeaddtags=localauthoritycode
localauthoritynameLocal Authority Nameaddtags=localauthorityname
electoralwardcodeElectoral Ward Codeaddtags=electoralwardcode
electoralwardnameElectoral Ward Nameaddtags=electoralwardname
electoralcountycodeElectoral County Codeaddtags=electoralcountycode
electoralcountynameElectoral County Nameaddtags=electoralcountyname
parishcodeParish Codeaddtags=parishcode
parliamentaryconstituencycodeWestminster Parliamentary Constituency Codeaddtags=parliamentaryconstituencycode
parliamentaryconstituencynameWestminster Parliamentary Constituency Nameaddtags=parliamentaryconstituencyname
europeanelectoralregioncodeEuropean Electoral Region Codeaddtags=europeanelectoralregioncode
europeanelectoralregionnameEuropean Electoral Region Nameaddtags=europeanelectoralregionname
nationalparknameNational Park Nameaddtags=nationalparkname
nationalparkcodeNational Park Codeaddtags=nationalparkcode

Integration advice

  • URL encode all special characters (including /) in your request parameters with %xx encoding
  • When using your API key across multiple websites, apps or clients, set the identifier querystring parameter to a meaningful value such as "websiteA" or "client123"; you'll then be able to view these identifiers and the number of requests made by each one on the Identifier Usage page
  • Treat all response fields as optional
  • Use these fields to create postal addresses:
    • UK: addressline1, addressline2, posttown, postcode
    • Ireland and global: addressline1, addressline2, posttown, county, postcode, country

Credit cost

Each request costs the following number of credits:

CountryStandard requestEnhanced request using addtags
UK2 credits2.4 credits
Ireland4.5 credits4.5 credits
Rest of world2 credits

Buy a credit pack or set up a monthly plan to use with all Postcoder endpoints.

Live Start Loading Now Chatting Offline