Cookie

We use cookies to improve your experience on our site, and to provide a live chat feature. To find out more please read our privacy policy.

Skip to content

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.

Ireland and Eircode: Enable access on your API key using the Features page or by contacting us.

Request URL

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

Path parameters

ParameterDescriptionExample
apikeyYour API keyPCW45-12345-12345-1234X
countrycodeThe 2-character country code, use uk for UK or ie for Irelanduk
latitudeThe ETRS89 latitude of the centre of the search area52.6299163702
longitudeThe ETRS89 longitude of the centre of the search area1.3018030246

Querystring parameters

ParameterDescriptionExample
distanceSets the radius of the search from the centre position in metresdistance=50
formatSets the format of the response, xml or json (default unless "application/xml" header is detected)format=json
identifierSpecifies 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 clientsidentifier=websiteA
linesSets 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 lineslines=2
includeSpecifies the extra address fields to include within the address lines using a comma-delimited list, supported values: county, posttown, postcodeinclude=county,posttown,postcode
excludeSpecifies 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, dependentlocalityexclude=organisation
addtagsSpecifies 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 listaddtags=latitude,longitude
callbackSpecifies the name of your JSONP callback functioncallback=jsoncallback
pageSpecifies 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.

FieldDescriptionExample
summarylineA summary of the address, ideal for displaying in a drop-down listAllies Computing Ltd, 92 St. Faiths Lane, Norwich, Norfolk, NR1 1NE
addressline1The first line of the address, where the total number of address lines is defined by the lines querystring parameterAllies Computing Ltd
addressline2The second line of the address92 St. Faiths Lane
addressline3The third line of the address
addressline4The fourth line of the address
poboxThe PO Box number
organisationThe organisation name at that addressAllies Computing Ltd
departmentnameThe department name
buildingnameThe building name
subbuildingnameThe sub-building name
numberThe house or flat number92
premiseThe premise, a combination of buildingname, subbuildingname and number92
dependentstreetThe dependent street
streetThe streetSt. Faiths Lane
doubledependentlocalityThe double dependent locality
dependentlocalityThe dependent locality
posttownThe post townNorwich
countyThe countyNorfolk
postcodeThe postcodeNR1 1NE
notyetbuiltA true or false indicating whether the address is from the Royal Mail Not Yet Built datasetfalse
aliasA true or false indicating whether the address is a Royal Mail Alias recordfalse
recodesA colon-separated list of the previous postcode, previous delivery point suffix and the date it changed (YYYYMM format)CM7 8PX:1A:200112
latitudeThe ETRS89 latitude52.6299163702
longitudeThe ETRS89 longitude1.3018030246
grideastingThe Easting OS grid reference (1m precision in units of 1m)623545
gridnorthingThe Northing OS grid reference (1m precision in units of 1m)308689
morevaluesSet to true when there is at least one more page of results to requesttrue
nextpageThe page number for the next page of results to request2
totalresultsThe total number of results when there are multiple pages of results458

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

FieldDescriptionExample
Coordinate data
latitudeETRS89 latitude (ideal for use with mapping APIs)52.6299163702
longitudeETRS89 longitude (ideal for use with mapping APIs)1.3018030246
latitudeosgbOSGB36 latitude52.6294875459
longitudeosgbOSGB36 longitude1.3035999409
grideastingEasting OS Grid Reference (1m precision in units of 1m)623545
gridnorthingNorthing OS Grid Reference (1m precision in units of 1m)308689
Address fields
deliverypointsuffixDelivery Point Suffix3JS
uniquedeliverypointreferencenumberUnique Delivery Point Reference Number (UDPRN); there is no additional credit cost for including this field; you can also use addtags=udprn50959190
multipleoccupancycountMultiple Occupancy Count - count of the number of multiple occupancy addresses for the delivery point0
administrativecountyAdministrative County (top tier local government)Norfolk
postalcountyFormer Postal County
traditionalcountyTraditional CountyNorfolk
usercategoryUser Category ('R' for Residential, 'N' for Non-residential, 'L' for Large User)N
sortcodeSortcode for Royal Mail Mailsort35529
countrycodeCountry code within the United Kingdom064
countryCountry name within the United KingdomEngland
welsh_dependentstreetWelsh language alternative for dependent street field
welsh_streetWelsh language alternative for street field
welsh_doubledependentlocalityWelsh language alternative for double dependent locality field
welsh_dependentlocalityWelsh language alternative for dependent locality field
welsh_posttownWelsh language alternative for post town field
Special PAF keys
The uniquedeliverypointreferencenumber is populated across countries and is the recommended primary key. For Royal Mail PAF addresses only, the following keys can be used as a composite primary key in this order: addresskey,organisationkey,postcodetype.
addresskeyThe 8-digit PAF Address Key from Royal Mail (UK only)00001000
organisationkeyThe 8-digit PAF Organisation Key from Royal Mail (UK only, '0' for Residential Small Users and Large Users)00456120
postcodetypeThe PAF Postcode Type from Royal Mail (UK only, 'S' for Small Users, 'L' for Large Users)S
Census data
oa112011 Census Output AreaE00136551
lsoa112011 Census Lower Layer Super Output AreaE01033438
msoa112011 Census Middle Layer Super Output AreaE02006907
NHS data
commissioningregioncode_gssNHS Commissioning Region Code (ONS GSS)E40000007
commissioningregionnameNHS Commissioning Region NameNHS England East of England
areateamcode_nhsNHS Area Team Code (NHS)QMM
areateamcode_gssNHS Area Team Code (ONS GSS)E54000022
areateamnameNHS Area Team NameNHS Norfolk and Waveney Integrated Care Board
clinicalcommissioninggroupcode_nhsNHS Clinical Commissioning Group Code (NHS)26A
clinicalcommissioninggroupcode_gssNHS Clinical Commissioning Group Code (ONS GSS)E38000239
clinicalcommissioninggroupnameNHS Clinical Commissioning Group NameNHS Norfolk and Waveney ICB - 26A
Government data
localauthoritywardcodeLocal Authority Ward Code33UGGC
localauthoritycodeLocal Authority CodeE07000148
localauthoritynameLocal Authority NameNorwich
electoralwardcodeElectoral Ward CodeE05012910
electoralwardnameElectoral Ward NameThorpe Hamlet
electoralcountycodeElectoral County CodeE10000020
electoralcountynameElectoral County NameNorfolk
parliamentaryconstituencycodeWestminster Parliamentary Constituency CodeE14000864
parliamentaryconstituencynameWestminster Parliamentary Constituency NameNorwich South
europeanelectoralregioncodeEuropean Electoral Region CodeE15000006
europeanelectoralregionnameEuropean Electoral Region NameEastern
nationalparkcodeNational Park CodeS21000003
nationalparknameNational Park NameThe 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:

CountryStandard requestEnhanced request using addtags
UK1.9 credits2.3 credits
Ireland4.5 credits4.5 credits

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