rgeo

Request URL

GET https://ws.postcoder.com/pcw/{apikey}/rgeo/{countrycode}/{latitude}/{longitude}?distance=

Path parameters

Querystring parameters

Example requests and responses

Return UK streets within 50 metres of the coordinate position of 52.6299163702, 1.3018030246:

GET https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/rgeo/uk/52.6299163702/1.3018030246?distance=50&format=json

[
	{
		"summaryline": "St. Faiths Lane, Norwich, Norfolk, NR1 1NE",
		"street": "St. Faiths Lane",
		"posttown": "Norwich",
		"county": "Norfolk",
		"postcode": "NR1 1NE",
		"latitude": "52.6299163702",
		"longitude": "1.3018030246",
		"grideasting": "623545",
		"gridnorthing": "308689"
	}
]

Return Irish addresses within 50 metres of the coordinate position of 53.332067, -6.255492:

GET https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/rgeo/ie/53.332067/-6.255492?distance=50&format=json

[
	{
		"summaryline": "Irish Pension Trust Limited, Marsh House, 25-28 Adelaide Road, Dublin 2, D02 RY98",
		"organisation": "Irish Pension Trust Limited",
		"buildingname": "Marsh House",
		"number": "25-28",
		"premise": "Marsh House, 25-28",
		"street": "Adelaide Road",
		"posttown": "Dublin 2",
		"county": "Co. Dublin",
		"postcode": "D02 RY98"
	}
]

Response fields

The address-level fields below (such as buildingname and number) are only relevant to reverse geocoding in Ireland.

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:

GET https://ws.postcoder.com/pcw/...?format=json&lines=2&addtags=latitude,longitude,udprn

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 the following number of credits:

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