Cookie consent

We use some essential cookies to make this website work. We'd like to set additional cookies to help us measure your experience when you view and interact with the website.

Cookie policy


Postcoder address autocomplete provides real-time suggestions as a user types in their address. It supports over 240 countries and consists of two types of request: one or more find requests to narrow down a list of address suggestions, and a retrieve request to retrieve a full address.

This is the retrieve endpoint and it returns the full address for a given suggestion ID. Before using this endpoint, use the autocomplete/find endpoint to get address suggestions and their IDs.

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

Request URL


Querystring parameters

idThe ID of the suggestion which was found using the /autocomplete/find endpointid=52752859
queryThe URL-encoded search term which was used with /autocomplete/find endpointquery=1%20birchwood
countryThe 2-character country code, see supported countries belowcountry=uk
apikeyYour API keyapikey=PCW45-12345-12345-1234X
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-9) to include in the response so you can mirror the layout of your existing address form, see address lines belowlines=3
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
callbackSpecifies the name of your JSONP callback functioncallback=jsoncallback

Supported countries and country codes

The following countries are supported by this endpoint. The address and geocoding levels shown for each country reflect the highest level of data supported. There are three levels:

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

Example request and response

After finding suggestions using the autocomplete/find endpoint, return the UK address with a suggestion ID of 52752859 and include up to 3 address lines in the response:


		"addressline1": "Flat 1",
		"addressline2": "Birchwood Apartments",
		"addressline3": "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"

Response fields

summarylineA summary of the address, ideal for displaying in a drop-down listAllies Computing Ltd, 92 St. Faiths Lane, Norwich, Norfolk, NR1 1NE
addressline1The first address line, where the total number of address lines is defined by the lines querystring parameterAllies Computing Ltd
addressline2The second address line92 St. Faiths Lane
addressline3The third address line
addressline4The fourth address line
addressline5The fifth address line
addressline6The sixth address line
addressline7The seventh address line
addressline8The eighth address line
addressline9The ninth address line
poboxThe PO Box number
organisationThe organisation name at that addressAllies Computing Ltd
departmentnameThe department name
buildingnameThe building name
subbuildingnameThe sub-building name
numberThe house or flat number92
premiseThe premise, a combination of buildingname, subbuildingname and number92
dependentstreetThe dependent street
streetThe streetSt. Faiths Lane
doubledependentlocalityThe double dependent locality
dependentlocalityThe dependent locality
posttownThe post townNorwich
countyThe countyNorfolk
postcodeThe postcodeNR1 1NE
notyetbuiltA true or false indicating whether the address is from the Royal Mail Not Yet Built datasetfalse
aliasA true or false indicating whether the address is a Royal Mail Alias recordfalse
recodesA colon-separated list of the previous postcode, previous delivery point suffix and the date it changed (YYYYMM format)CM7 8PX:1A:200112

Additional response fields

Use the addtags querystring parameter to specify a comma-delimited list of fields that you wish to add to the response. For example, to add latitude, longitude and udprn:


Coordinate data
latitudeETRS89 latitude (ideal for use with mapping APIs)52.6299163702
longitudeETRS89 longitude (ideal for use with mapping APIs)1.3018030246
latitudeosgbOSGB36 latitude52.6294875459
longitudeosgbOSGB36 longitude1.3035999409
grideastingEasting OS Grid Reference (1m precision in units of 1m)623545
gridnorthingNorthing OS Grid Reference (1m precision in units of 1m)308689
Address fields
deliverypointsuffixDelivery Point Suffix3JS
uniquedeliverypointreferencenumberUnique Delivery Point Reference Number (UDPRN); there is no additional credit cost for including this field; you can also use addtags=udprn50959190
multipleoccupancycountMultiple Occupancy Count - count of the number of multiple occupancy addresses for the delivery point0
administrativecountyAdministrative County (top tier local government)Norfolk
postalcountyFormer Postal County
traditionalcountyTraditional CountyNorfolk
usercategoryUser Category ('R' for Residential, 'N' for Non-residential, 'L' for Large User)N
sortcodeSortcode for Royal Mail Mailsort35529
countrycodeCountry code within the United Kingdom064
countryCountry name within the United KingdomEngland
welsh_dependentstreetWelsh language alternative for dependent street field
welsh_streetWelsh language alternative for street field
welsh_doubledependentlocalityWelsh language alternative for double dependent locality field
welsh_dependentlocalityWelsh language alternative for dependent locality field
welsh_posttownWelsh language alternative for post town field
Special PAF keys
The uniquedeliverypointreferencenumber is populated across countries and is the recommended primary key. For Royal Mail PAF addresses only, the following keys can be used as a composite primary key in this order: addresskey,organisationkey,postcodetype.
addresskeyThe 8-digit PAF Address Key from Royal Mail (UK only)00001000
organisationkeyThe 8-digit PAF Organisation Key from Royal Mail (UK only, '0' for Residential Small Users and Large Users)00456120
postcodetypeThe PAF Postcode Type from Royal Mail (UK only, 'S' for Small Users, 'L' for Large Users)S
Census data
oa112011 Census Output AreaE00136551
lsoa112011 Census Lower Layer Super Output AreaE01033438
msoa112011 Census Middle Layer Super Output AreaE02006907
NHS data
commissioningregioncode_gssNHS Commissioning Region Code (ONS GSS)E40000007
commissioningregionnameNHS Commissioning Region NameNHS England East of England
areateamcode_nhsNHS Area Team Code (NHS)QMM
areateamcode_gssNHS Area Team Code (ONS GSS)E54000022
areateamnameNHS Area Team NameNHS Norfolk and Waveney Integrated Care Board
clinicalcommissioninggroupcode_nhsNHS Clinical Commissioning Group Code (NHS)26A
clinicalcommissioninggroupcode_gssNHS Clinical Commissioning Group Code (ONS GSS)E38000239
clinicalcommissioninggroupnameNHS Clinical Commissioning Group NameNHS Norfolk and Waveney ICB - 26A
Government data
localauthoritycodeLocal Authority CodeE07000148
localauthoritynameLocal Authority NameNorwich
electoralwardcodeElectoral Ward CodeE05012910
electoralwardnameElectoral Ward NameThorpe Hamlet
electoralcountycodeElectoral County CodeE10000020
electoralcountynameElectoral County NameNorfolk
parliamentaryconstituencycodeWestminster Parliamentary Constituency CodeE14000864
parliamentaryconstituencynameWestminster Parliamentary Constituency NameNorwich South
europeanelectoralregioncodeEuropean Electoral Region CodeE15000006
europeanelectoralregionnameEuropean Electoral Region NameEastern
nationalparkcodeNational Park CodeS21000003
nationalparknameNational Park NameThe Cairngorms National Park

Address lines

When retrieving an address using this endpoint, Postcoder can optionally return up to 9 address lines that contain all the address elements (such as organisation, number, street, dependentlocality, posttown, county, postcode and country) needed to represent the address.

	"addressline1":"123 Rue Brizeux",
	"addressline2":"29860 Plouvien",

The address lines returned by Postcoder for addresses in the UK (country=uk), Guernsey (gg), Jersey (je), Isle of Man (im) and Ireland (ie) are different: they do not contain the posttown, county, postcode and country by default.

	"addressline1": "123 Foxglove Lane",
	"addressline2": "Biddenham",

You can specify the number of address lines by setting the lines querystring parameter in your request to 1, 2, 3... or 9. To return up to 3 address lines, for example:


Fewer address lines will be returned when there are not enough address elements to fill them.

You can customise what is contained within the address lines by setting the include and exclude querystring parameters. For example, to exclude the posttown, county, postcode and country when retrieving a French address:


	"addressline1":"123 Rue Brizeux",

You can use the address lines and address elements returned by Postcoder to populate any type of address form. If your users or customers are worldwide, your address form may contain these fields:

Country selector
Postcoder input (Start typing your address…)
Address line 1
Address line 2
Address line 3
Postal/Zip code

When the country is UK (country=uk), Guernsey (gg), Jersey (je), Isle of Man (im) or Ireland (ie), this request structure will return the response fields you need:


	"addressline1": "123 Foxglove Lane",
	"addressline2": "Biddenham",
	"posttown": "Ashford",
	"county": "Kent",
	"postcode": "TN27 8BT"

For any other country, this request structure will return the response fields you need:


	"addressline1":"123 Rue Brizeux",
	"posttown": "Plouvien",
	"county": "Finistère",
	"postcode": "29860",

Integration advice

  • URL encode all special characters (including /) in your request parameters with %xx encoding
  • Verify your request was successful by checking for an HTTP status code of 200; see all HTTP status codes with descriptions
  • 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
  • County is no longer required in UK addresses; however, it may include essential postal details for addresses in other countries

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.0 credits2.4 credits

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