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.

addressbase

This endpoint provides you with access to either AddressBase Core or AddressBase Premium, and returns one or more property records that match a given postcode or part of an address.

For AddressBase Premium, only property records with an associated Delivery Point Address (DPA) record that matches the search term will be returned. A DPA record is one that has been matched by Ordnance Survey against a Royal Mail PAF address; not every property record will have an associated DPA record.

Your API key determines whether you access AddressBase Core or AddressBase Premium.

AddressBase: Enable access on your API key using the Data Options page or by contacting us.

Request URL

GET https://ws.postcoder.com/pcw/{apikey}/addressbase/{searchterm}

Path parameters

ParameterDescriptionExample
apikeyYour API keyPCW45-12345-12345-1234X
searchtermThe URL-encoded postcode or part of an address that you wish to look upnr1%201ne

Querystring parameters

ParameterDescriptionExample
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: addressbase (for all fields), uprn, deliverypointaddress, lpis, blpu, classifications, organisations, applicationcrossreferences, tile, latitude, longitude. You can also include a selection of non-AddressBase fields, see additional response fields below for the full listaddtags=addressbase
postcodeonlyLimits the request to a postcode-only search rather than matching the search term on other parts of an address, true or false (default)postcodeonly=true
callbackSpecifies the name of your JSONP callback functioncallback=jsoncallback

Example request and response

Return property records with an associated Delivery Point Address (DPA) record that matches a postcode of NR1 4DH and include two address lines in the response:

GET https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/nr1%204dh?format=json&lines=2

[
	...
	...
	{
		"addressline1": "The Dean & Chapter of Norwich Cathedral",
		"addressline2": "Chapter Office, 65 The Close",
		"summaryline": "The Dean & Chapter of Norwich Cathedral, Chapter Office, 65 The Close, Norwich, NR1 4DH",
		"organisation": "The Dean & Chapter of Norwich Cathedral",
		"subbuildingname": "Chapter Office",
		"number": "65",
		"uniquedeliverypointreferencenumber": "17308537",
		"premise": "Chapter Office, 65",
		"street": "The Close",
		"posttown": "Norwich",
		"postcode": "NR1 4DH",
		"latitude": "52.6308744",
		"longitude": "1.3009883",
		"grideasting": "623485.0",
		"gridnorthing": "308793.0",
		"uprn": "200004353841",
		"usrn": "28920601"
	},
	...
	...
]

Response fields

The following fields are returned in the response for AddressBase Core:

FieldDescriptionExample
summarylineThe address given in a single field separated by commas. Where matched against PAF this is a postal addressThe Dean & Chapter of Norwich Cathedral, Chapter Office, 65 The Close, Norwich, NR1 4DH
organisationOrganisation name. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council recordsThe Dean & Chapter of Norwich Cathedral
departmentnameWhere there is a distinct delivery point for receipt of mail for a department, the department name is indicated here. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
poboxWhere linked to a PAF PO Box holder, this is the PO Box number. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
subbuildingnameSub-building name – usually a unit number or flat number. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council recordsChapter Office
buildingnameName of the building. For instance Nelson House. May or may not be further sub-divided. Often contains what Royal Mail would class as a Dependent Street. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
numberThe street number. Note that this may be alpha numeric. E.g. 1A. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records65
uniquedeliverypointreferencenumberRoyal Mail's unique identifier for a Delivery Point (i.e. where postal delivery staff go to deliver mail). Assigned by Royal Mail and only available where an address record has been matched against PAF. Provides a unique identifier and designed to be unique over the life time of a delivery point17308537
premiseA concatenation of the Department, PO Box, Sub-building Name, Building Name and Number (in that order). Useful if you have a single field in your database for storing the premiseChapter Office, 65
dependentstreetA street that needs another one for access. For example a cul-de-sac or a named parade of shops on a main road
streetThe main street on which a property is situated. Commonly seems to be a main road especially in rural and remote settings. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council recordsThe Close
doubledependentlocalityThis is a smaller industrial estate or sub-division of a town or village. The data in this field comes from Royal Mail if the record has been matched to a delivery point but the equivalent data from council records goes into Dependentlocality
dependentlocalityThis is analogous to Royal Mail's Double Dependent Locality and is generally representative of retail parks or industrial estates. Source: Council records or, if PAF matched, Royal Mail
townnameThis is analogous to Royal Mail's Dependent Locality and represents a suburb or small town. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records
posttownWhere an address record has been matched against PAF, this is the post town responsible for mail sorting. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council recordsNorwich
postcodeThis is the Postcode assigned by Royal MailNR1 4DH
deliverypointsuffixThe Delivery Point Suffix used by Royal Mail. This, along with a Postcode, provides a unique identifier for a delivery point at a point in time. Source: Royal Mail
latitudeThis is the latitude on the ETRS89 projection. See rpc52.6308744
longitudeThis is the longitude on the ETRS89 projection. See rpc1.3009883
grideastingThe Easting on Ordnance Survey's British National Grid. The units are in metres to 2 decimal places. See rpc623485.00
gridnorthingThe Northing on Ordnance Survey's British National Grid. The units are in metres to 2 decimal places. See rpc308793.00
uprnThe Unique Property Reference Number – the primary key field for AddressBase data. Assigned by GeoPlace or Ordnance Survey200004353841
parentuprnWhere a particular property is part of another one (for example a flat in a block of flats or a unit on a business park) the owning property's UPRN is indicated here. Please note that this is not the same as Royal Mail's multiple residence indicator for postal purposes but is a good indicator that this is not a stand-alone property
usrnThe Unique Street Reference Number – every street under council control has its own unique identifier and this is it28920601
changecodeIndicates how this record was last amended on the national hub. AddressBase Core only
toidThe topographical identifier which associates this record with OS MasterMap. AddressBase Core only
classificationcodeDescribes the classification of the property according to council recordsCO01
rpcTells you how accurate the coordinates are. For safety critical applications this may be a particularly important field:


1 – Central Internal Position – The address is contained within an OS MasterMap Topography Later building and within 2.5m of its calculated centre. Or the coordinates represent the best possible position based on the nature of the premises

2- General Internal Position – The address is contained within an OS MasterMap Topography Later building but is more than 2.5m away from its calculated centre. Or the seed is in an internal position based on the nature of the premises

3 – Transitional Position – The address has been changed from Under Development to Live within the last 6 months. It has been captured to a high level of positional accuracy but pending large scale mapping updates still may be moved

4 – Street Location – The address is plotted in accordance with the declared street start and end coordinates

5 – Postcode Unit position – The address has been captured to Postcode Unit level and will be updated when more information becomes available. It is likely that every property on the Postcode will be sharing these same coordinates

9 – Low Accuracy – The address has been captured to a lower level of accuracy and will be updated as a priority over the coming months
1
gsscodeProvided by the Office for National Statistics and used for official records. Codes are structured: the first three characters are an Entity Code and the remaining 6 characters are the particular instance. Entity Codes are: E06 (Unitary Authority); E07 (Local Authority District Council); E08 (Metropolitan Borough Council); and E09 (London Borough)
lastupdatedateThe date this record was last updated

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
  • Use these fields to create a UK postal address: addressline1, addressline2, posttown, postcode

Credit cost

Each request costs 3.5 credits.

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