reversegeo

Request URL

Path parameters

Querystring parameters

Supported countries and country codes

To use this endpoint, your API key must have access to at least AddressBase Core/Premium and/or Eircode. Use the table below for guidance and then enable access on your API key using the Features page or by contacting us.

Example requests and responses

Return UK addresses within 10 metres of the coordinate position of (52.6308744, 1.3009883) and include up to 3 address lines and coordinates in the response:

[
	{
		"addressline1": "The Dean & Chapter of Norwich Cathedral",
		"addressline2": "Chapter Office",
		"addressline3": "65 The Close",
		"summaryline": "The Dean & Chapter of Norwich Cathedral, Chapter Office, 65 The Close, Norwich, Norfolk, NR1 4DH",
		"organisation": "The Dean & Chapter of Norwich Cathedral",
		"subbuildingname": "Chapter Office",
		"number": "65",
		"premise": "Chapter Office, 65",
		"street": "The Close",
		"posttown": "Norwich",
		"county": "Norfolk",
		"postcode": "NR1 4DH",
		"latitude": "52.6308744",
		"longitude": "1.3009883"
	}
]

Return Irish addresses within 10 metres of the coordinate position of (53.332067, -6.255492) 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. The address lines returned for addresses in the UK (uk), Guernsey (gg), Jersey (je), Isle of Man (im) and Ireland (ie) 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 Foxglove Lane",
"addressline2": "Biddenham",
...

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",
...

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

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

Credit cost

Each request costs 4.5 credits.

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