rgeo
This endpoint provides reverse geocoding for the UK and Ireland. It returns street addresses for UK coordinates, and full Irish addresses for Irish coordinates.
Request URL
GET https://ws.postcoder.com/pcw/{apikey}/rgeo/{countrycode}/{latitude}/{longitude}?distance=
Path parameters
Parameter | Description | Example |
---|---|---|
apikey | Your API key | PCW45-12345-12345-1234X |
countrycode | The 2-character country code, use uk for UK or ie for Ireland | uk |
latitude | The ETRS89 latitude of the centre of the search area | 52.6299163702 |
longitude | The ETRS89 longitude of the centre of the search area | 1.3018030246 |
Querystring parameters
Parameter | Description | Example |
---|---|---|
distance | Sets the radius of the search from the centre position in metres | distance=50 |
format | Sets the format of the response, xml or json (default unless "application/xml" header is detected) | format=json |
identifier | Specifies 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 clients | identifier=websiteA |
lines | Sets the number of address lines (1-4) to include in the response so you can mirror the layout of your existing address form; use include and exclude below to further customise the address lines | lines=2 |
include | Specifies the extra address fields to include within the address lines using a comma-delimited list, supported values: county, posttown, postcode | include=county,posttown,postcode |
exclude | Specifies 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, dependentlocality | exclude=organisation |
addtags | Specifies 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 list | addtags=latitude,longitude |
callback | Specifies the name of your JSONP callback function | callback=jsoncallback |
page | Specifies the page of results to return where page zero is the first, 0 (default), 1, 2... | page=1 |
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.
Field | Description | Example |
---|---|---|
summaryline | A summary of the address, ideal for displaying in a drop-down list | Allies Computing Ltd, 92 St. Faiths Lane, Norwich, Norfolk, NR1 1NE |
addressline1 | The first line of the address, where the total number of address lines is defined by the lines querystring parameter | Allies Computing Ltd |
addressline2 | The second line of the address | 92 St. Faiths Lane |
addressline3 | The third line of the address | |
addressline4 | The fourth line of the address | |
pobox | The PO Box number | |
organisation | The organisation name at that address | Allies Computing Ltd |
departmentname | The department name | |
buildingname | The building name | |
subbuildingname | The sub-building name | |
number | The house or flat number | 92 |
premise | The premise, a combination of buildingname, subbuildingname and number | 92 |
dependentstreet | The dependent street | |
street | The street | St. Faiths Lane |
doubledependentlocality | The double dependent locality | |
dependentlocality | The dependent locality | |
posttown | The post town | Norwich |
county | The county | Norfolk |
postcode | The postcode | NR1 1NE |
notyetbuilt | A true or false indicating whether the address is from the Royal Mail Not Yet Built dataset | false |
alias | A true or false indicating whether the address is a Royal Mail Alias record | false |
recodes | A colon-separated list of the previous postcode, previous delivery point suffix and the date it changed (YYYYMM format) | CM7 8PX:1A:200112 |
latitude | The ETRS89 latitude | 52.6299163702 |
longitude | The ETRS89 longitude | 1.3018030246 |
grideasting | The Easting OS grid reference (1m precision in units of 1m) | 623545 |
gridnorthing | The Northing OS grid reference (1m precision in units of 1m) | 308689 |
morevalues | Set to true when there is at least one more page of results to request | true |
nextpage | The page number for the next page of results to request | 2 |
totalresults | The total number of results when there are multiple pages of results | 458 |
Additional response fields
The following fields can also be included in the response.
Use the addtags
querystring parameter to specify a comma-delimited list of fields that you wish to add.
Example: Add latitude, longitude and udprn into the response:
GET https://ws.postcoder.com/pcw/...?format=json&lines=2&addtags=latitude,longitude,udprn
Field | Description | Example |
---|---|---|
Coordinate data | ||
latitude | ETRS89 latitude (ideal for use with mapping APIs) | 52.6299163702 |
longitude | ETRS89 longitude (ideal for use with mapping APIs) | 1.3018030246 |
latitudeosgb | OSGB36 latitude | 52.6294875459 |
longitudeosgb | OSGB36 longitude | 1.3035999409 |
grideasting | Easting OS Grid Reference (1m precision in units of 1m) | 623545 |
gridnorthing | Northing OS Grid Reference (1m precision in units of 1m) | 308689 |
Address fields | ||
deliverypointsuffix | Delivery Point Suffix | 3JS |
uniquedeliverypointreferencenumber | Unique Delivery Point Reference Number (UDPRN); you can also use addtags=udprn | 50959190 |
multipleoccupancycount | Multiple Occupancy Count - count of the number of multiple occupancy addresses for the delivery point | 0 |
administrativecounty | Administrative County (top tier local government) | Norfolk |
postalcounty | Former Postal County | |
traditionalcounty | Traditional County | Norfolk |
usercategory | User Category (residential 'R', Non-residential 'N', or Large 'L') | N |
sortcode | Sortcode for Royal Mail Mailsort | 35529 |
countrycode | Country code within the United Kingdom | 064 |
country | Country name within the United Kingdom | England |
welsh_dependentstreet | Welsh language alternative for dependent street field | |
welsh_street | Welsh language alternative for street field | |
welsh_doubledependentlocality | Welsh language alternative for double dependent locality field | |
welsh_dependentlocality | Welsh language alternative for dependent locality field | |
welsh_posttown | Welsh language alternative for post town field | |
Census data | ||
oa11 | 2011 Census Output Area | E00136551 |
lsoa11 | 2011 Census Lower Layer Super Output Area | E01033438 |
msoa11 | 2011 Census Middle Layer Super Output Area | E02006907 |
NHS data | ||
commissioningregioncode_gss | NHS Commissioning Region Code (ONS GSS) | E40000007 |
commissioningregionname | NHS Commissioning Region Name | NHS England East of England |
areateamcode_nhs | NHS Area Team Code (NHS) | QMM |
areateamcode_gss | NHS Area Team Code (ONS GSS) | E54000022 |
areateamname | NHS Area Team Name | NHS Norfolk and Waveney Integrated Care Board |
clinicalcommissioninggroupcode_nhs | NHS Clinical Commissioning Group Code (NHS) | 26A |
clinicalcommissioninggroupcode_gss | NHS Clinical Commissioning Group Code (ONS GSS) | E38000239 |
clinicalcommissioninggroupname | NHS Clinical Commissioning Group Name | NHS Norfolk and Waveney ICB - 26A |
Government data | ||
localauthoritywardcode | Local Authority Ward Code | 33UGGC |
localauthoritycode | Local Authority Code | E07000148 |
localauthorityname | Local Authority Name | Norwich |
electoralwardcode | Electoral Ward Code | E05012910 |
electoralwardname | Electoral Ward Name | Thorpe Hamlet |
electoralcountycode | Electoral County Code | E10000020 |
electoralcountyname | Electoral County Name | Norfolk |
parliamentaryconstituencycode | Westminster Parliamentary Constituency Code | E14000864 |
parliamentaryconstituencyname | Westminster Parliamentary Constituency Name | Norwich South |
europeanelectoralregioncode | European Electoral Region Code | E15000006 |
europeanelectoralregionname | European Electoral Region Name | Eastern |
nationalparkcode | National Park Code | S21000003 |
nationalparkname | National Park Name | The Cairngorms National Park |
Integration advice
- URL encode all special characters (including /) in your request parameters with %xx encoding
- 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:
Country | Standard request | Enhanced request using addtags |
---|---|---|
UK | 1.9 credits | 2.3 credits |
Ireland | 4.5 credits | 4.5 credits |
Buy a credit pack or set up a monthly plan to use with all Postcoder endpoints.