address

Request URL

Path parameters

Querystring parameters

Supported countries and country codes

The following 249 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

Example requests and responses

Return UK addresses with a postcode of NR1 1NE and include up to 3 address lines in the response:

[
	...
	...
	{
		"addressline1": "Allies Computing Ltd",
		"addressline2": "92 St. Faiths Lane",
		"summaryline": "Allies Computing Ltd, 92 St. Faiths Lane, Norwich, Norfolk, NR1 1NE",
		"organisation": "Allies Computing Ltd",
		"number": "92",
		"premise": "92",
		"street": "St. Faiths Lane",
		"posttown": "Norwich",
		"county": "Norfolk",
		"postcode": "NR1 1NE"
	},
	...
	...
]

Return US addresses that match "1600 Pennsylvania, 20500-0001" and include up to 3 address lines (which exclude the organisation and country fields) in the response:

[
	{
		"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"
	}
]

Return the Irish address with an Eircode of D02X285 and include up to 3 address lines and coordinates in the response:

[
	{
		"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

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 where the country is United States (us), append:

...&lines=3&exclude=posttown,state,stateabbreviation,postcode,country

"addressline1": "2600 E COAST HWY STE 100",     --> Address line 1
...
"posttown": "CORONA DEL MAR",                   --> City/Town
...
"state": "CALIFORNIA",
"stateabbreviation": "CA",                      --> State/Region/County
"postcode": "92625-2118",                       --> 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
...

Pagination

When a request returns many addresses, Postcoder may paginate the response across multiple pages. The first page is returned by default and has an index of 0.

If another page is available, the last address on the current page will include two extra fields: morevalues (indicates another page is available when "true") and nextpage (provides the index of the next page).

[
    ...
    ...
    {
        // Last address on current page
        ...
        ...
        "posttown": "Norwich",
        "county": "Norfolk",
        "postcode": "NR1 1NE",
        "morevalues": "true",
        "nextpage": "1",
        "totalresults": "180"
    }
]

You can retrieve the next page by setting the page querystring parameter to the index of the next page. In the scenario above, you could do this by adding ?page=1 to your request.

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
• If your address form has a country selector, use the ipaddress endpoint to preset the country based on the user's IP address

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.