autocomplete/retrieve

Request URL

Querystring parameters

Supported countries and country codes

The following 249 countries are supported by this endpoint. The address level shown for each country reflects 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

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

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:

Address lines

This endpoint can return up to 9 address lines that contain the required address elements in the correct order for each address. For example:

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

"addressline1": "2101 E COAST HWY STE 100",
"addressline2": "CORONA DEL MAR CA  92625-1963",
...

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

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

Configuring address lines

You can specify the number of address lines by setting the lines querystring parameter in your request to 1, 2, 3... or 9, although note that empty address lines are not returned. For example:

...&lines=3

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

You can customise what is contained within the address lines by setting the include and exclude querystring parameters. For example, to include the posttown and postcode in the address lines:

...&lines=3&include=posttown,postcode

"addressline1": "123 Foxglove Lane",
"addressline2": "Biddenham",
"addressline3": "Ashford, TN27 8BT",
...

Or, to exclude the postcode from the address lines:

...&lines=3&exclude=postcode

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

Working with existing address forms

The address lines returned by this endpoint handle the complexity of international address formats for you, and are ready-made for address forms that use generic address lines.

However, there may be occasions where you need to work with an existing address form that has fields for specific address elements. For example, if you serve customers all around the world, your address form might contain these fields:

For requests where the country is set to UK (uk), Guernsey (gg), Jersey (je), Isle of Man (im) or Ireland (ie), you can return the response fields necessary to populate the form fields above by appending:

...&lines=3

"addressline1": "123 Foxglove Lane",    --> Address line 1
"addressline2": "Biddenham",            --> Address line 2
...
"posttown": "Ashford",                  --> City/Town
"county": "Kent",                       --> State/Region/County (not required in the UK)
"postcode": "TN27 8BT"                  --> Postal/Zip code

For requests with any other country, append:

...&lines=3&exclude=posttown,county,postcode,country

"addressline1":"123 Rue Brizeux",       --> Address line 1
...
"posttown": "Plouvien",                 --> City/Town
"county": "Finistère",                  --> State/Region/County
"postcode": "29860",                    --> Postal/Zip code
...

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:

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