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.

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 Data Options 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.5859714116
longitudeThe ETRS89 longitude of the centre of the search area1.3492192897

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

Reverse geocode to find UK streets within 50m of (52.5859714116, 1.3492192897)

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

[
	{
		"summaryline": "Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ",
		"street": "Fox Road",
		"dependentlocality": "Framingham Pigot",
		"posttown": "Norwich",
		"county": "Norfolk",
		"postcode": "NR14 7PZ",
		"latitude": "52.5859730797",
		"longitude": "1.3491603533",
		"grideasting": "626976",
		"gridnorthing": "303951"
	}
]

Reverse geocode to find Irish addresses within 50m 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, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ
addressline1The first line of the address, where the total number of address lines is defined by the lines querystring parameterManor Farm Barns
addressline2The second line of the addressFox Road
addressline3The third line of the addressFramingham Pigot
addressline4The fourth line of the addressAllies Computing Ltd
poboxThe PO Box number 
organisationThe organisation name at that addressAllies Computing Ltd
departmentnameThe department name
buildingnameThe building nameManor Farm Barns
subbuildingnameThe sub-building name
numberThe house or flat number8
premiseThe premise, a combination of buildingname, subbuildingname and numberManor Farm Barns
dependentstreetThe dependent street
streetThe streetFox Road
doubledependentlocalityThe double dependent localityEagle Road Industrial Estate
dependentlocalityThe dependent localityFramingham Pigot
posttownThe post townNorwich
countyThe countyNorfolk
postcodeThe postcodeNR14 7PZ
notyetbuiltA true or false indicating whether the address is from the Royal Mail Not Yet Built datasettrue
aliasA true or false indicating whether the address is a Royal Mail Alias recordtrue
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.5859730797
longitudeThe ETRS89 longitude1.3491603533
grideastingThe Easting OS grid reference (1m precision in units of 1m)626976
gridnorthingThe Northing OS grid reference (1m precision in units of 1m)303951
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

These additional fields can be included in the response by using the addtags querystring parameter to specify a comma-delimited list of field names.

Example: addtags=latitude,longitude,udprn,deliverypointsuffix,usercategory

FieldDescriptionQuerystring parameter to use
Coordinate data
latitudeLatitude (ETRS89)addtags=latitude
longitudeLongitude (ETRS89)addtags=longitude
latitudeosgbLatitude (OSGB36)addtags=latitudeosgb36
longitudeosgbLongitude (OSGB36)addtags=longitudeosgb36
grideastingEasting OS Grid Reference (1m precision in units of 1m)addtags=grideast1metre
gridnorthingNorthing OS Grid Reference (1m precision in units of 1m)addtags=gridnorth1metre
Address fields
deliverypointsuffixDelivery Point Suffixaddtags=deliverypointsuffix
uniquedeliverypointreferencenumberUnique Delivery Point Reference Number (UDPRN)addtags=udprn
multipleoccupancycountMultiple Occupancy Count - count of the number of multiple occupancy addresses for the delivery pointaddtags=multipleoccupancycount
administrativecountyAdministrative County (top tier local government)addtags=administrativecounty
postalcountyFormer Postal Countyaddtags=postalcounty
traditionalcountyTraditional Countyaddtags=traditionalcounty
usercategoryUser Category (residential 'R', Non-residential 'N', or Large 'L')addtags=usercategory
sortcodeSortcode for Royal Mail Mailsortaddtags=sortcode
countrycodeCountry code (within the United Kingdom)addtags=countrycode
countryCountry name (within the United Kingdom)addtags=country
welsh_dependentstreetWelsh language alternative for dependent street fieldaddtags=welsh_dependentstreet
welsh_streetWelsh language alternative for street fieldaddtags=welsh_street
welsh_doubledependentlocalityWelsh language alternative for double dependent locality fieldaddtags=welsh_doubledependentlocality
welsh_dependentlocalityWelsh language alternative for dependent locality fieldaddtags=welsh_dependentlocality
welsh_posttownWelsh language alternative for post town fieldaddtags=welsh_posttown
Census data
oa112011 Census Output Areaaddtags=oa11
lsoa112011 Census Lower Layer Super Output Areaaddtags=lsoa11
msoa112011 Census Middle Layer Super Output Areaaddtags=msoa11
censusoutputarea_20012001 Census Output Areaaddtags=censusoutputarea_2001
censuslowerlayersuperoutputarea_20012001 Census Lower Layer Super Output Areaaddtags=censuslowerlayersuperoutputarea_2001
censusmiddlelayersuperoutputarea_20012001 Census Middle Layer Super Output Areaaddtags=censusmiddlelayersuperoutputarea_2001
censusareastatisticswardcode2001 Census Area Statistics (CAS) Wardaddtags=censusareastatisticswardcode
statisticalwardcode_20052005 Statistical Wardaddtags=statisticalwardcode_2005
NHS data
commissioningregioncode_gssNHS Commissioning Region Code (ONS GSS)addtags=commissioningregioncode_gss
commissioningregionnameNHS Commissioning Region Nameaddtags=commissioningregionname
areateamcode_nhsNHS Area Team Code (NHS)addtags=areateamcode_nhs
areateamcode_gssNHS Area Team Code (ONS GSS)addtags=areateamcode_gss
areateamnameNHS Area Team Nameaddtags=areateamname
clinicalcommissioninggroupcode_nhsNHS Clinical Commissioning Group Code (NHS)addtags=clinicalcommissioninggroupcode_nhs
clinicalcommissioninggroupcode_gssNHS Clinical Commissioning Group Code (ONS GSS)addtags=clinicalcommissioninggroupcode_gss
clinicalcommissioninggroupnameNHS Clinical Commissioning Group Nameaddtags=clinicalcommissioninggroupname
Government data
localauthoritywardcodeLocal Authority Ward Codeaddtags=localauthoritywardcode
localauthoritycodeLocal Authority Codeaddtags=localauthoritycode
localauthoritynameLocal Authority Nameaddtags=localauthorityname
electoralwardcodeElectoral Ward Codeaddtags=electoralwardcode
electoralwardnameElectoral Ward Nameaddtags=electoralwardname
electoralcountycodeElectoral County Codeaddtags=electoralcountycode
electoralcountynameElectoral County Nameaddtags=electoralcountyname
parishcodeParish Codeaddtags=parishcode
parliamentaryconstituencycodeWestminster Parliamentary Constituency Codeaddtags=parliamentaryconstituencycode
parliamentaryconstituencynameWestminster Parliamentary Constituency Nameaddtags=parliamentaryconstituencyname
europeanelectoralregioncodeEuropean Electoral Region Codeaddtags=europeanelectoralregioncode
europeanelectoralregionnameEuropean Electoral Region Nameaddtags=europeanelectoralregionname
nationalparknameNational Park Nameaddtags=nationalparkname
nationalparkcodeNational Park Codeaddtags=nationalparkcode

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.