pafaddressbase
This endpoint returns one or more Royal Mail PAF addresses for a given postcode or part of an address, enriched with data from the property records in either AddressBase Core or AddressBase Premium where the UPDRN of the PAF address matches the UDPRN in the AddressBase property record.
Your API key determines whether you access AddressBase Core or AddressBase Premium.
AddressBase: Enable access on your API key using the Features page or by contacting us.
Request URL
https://ws.postcoder.com/pcw/{apikey}/pafaddressbase/{searchterm}Path parameters
| Parameter | Description | Example |
|---|---|---|
apikey | Your API key | PCW45-12345-12345-1234X |
searchterm | The URL-encoded postcode or part of an address that you wish to look up | nr1%201ne |
Querystring parameters
| Parameter | Description | Example |
|---|---|---|
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-9) 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=3 |
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: 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 list | addtags=addressbase |
postcodeonly | Limits 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 |
callback | Specifies the name of your JSONP callback function | callback=jsoncallback |
page | Specifies the index of the page of results to return; the first page is returned by default and has an index of 0, the second page has an index of 1 and so on; see pagination for more info | page=1 |
Example request and response
Return UK addresses from PAF with a postcode of NR1 4DH and include up to 3 address lines in the response, along with additional data from the associated property records found in AddressBase:
https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/pafaddressbase/nr1%204dh?format=json&lines=3[
{
"addressline1": "The Dean & Chapter of Norwich Cathedral",
"addressline2": "Chapter Office",
"addressline3": "65 The Close",
"summaryline": "The Dean & Chapter of Norwich Cathedral, Chapter Office, 65 The Close, Norwich, Norfolk, 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",
"county": "Norfolk",
"postcode": "NR1 4DH",
"latitude": "52.6308744",
"longitude": "1.3009883",
"grideasting": "623485.0",
"gridnorthing": "308793.0",
"uprn": "200004353841",
"usrn": "28920601"
}
]Response fields
| Field | Description | Example |
|---|---|---|
summaryline | The address given in a single field separated by commas. Where matched against PAF this is a postal address | The Dean & Chapter of Norwich Cathedral, Chapter Office, 65 The Close, Norwich, NR1 4DH |
addressline1 | The first address line, where the total number of address lines is defined by the lines querystring parameter | The Dean & Chapter of Norwich Cathedral |
addressline2 | The second address line | Chapter Office |
addressline3 | The third address line | 65 The Close |
addressline4 | The fourth address line | |
addressline5 | The fifth address line | |
addressline6 | The sixth address line | |
addressline7 | The seventh address line | |
addressline8 | The eighth address line | |
addressline9 | The ninth address line | |
organisation | Organisation name. Source: Royal Mail where matched to a PAF delivery point where there is a deliverypointaddress record shown in AddressBase Premium or council records | The Dean & Chapter of Norwich Cathedral |
departmentname | Where 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 | |
pobox | Where 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 | |
subbuildingname | Sub-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 records | Chapter Office |
buildingname | Name 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 | |
number | The 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 records | 65 |
uniquedeliverypointreferencenumber | Royal 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 point | 17308537 |
premise | A 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 premise | Chapter Office, 65 |
dependentstreet | A street that needs another one for access. For example a cul-de-sac or a named parade of shops on a main road | |
street | The 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 records | The Close |
doubledependentlocality | This 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 | |
dependentlocality | This 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 | |
townname | This 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 | |
posttown | Where 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 records | Norwich |
postcode | This is the Postcode assigned by Royal Mail | NR1 4DH |
deliverypointsuffix | The 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 | |
latitude | This is the latitude on the ETRS89 projection. See rpc | 52.6308744 |
longitude | This is the longitude on the ETRS89 projection. See rpc | 1.3009883 |
grideasting | The Easting on Ordnance Survey's British National Grid. The units are in metres to 2 decimal places. See rpc | 623485.00 |
gridnorthing | The Northing on Ordnance Survey's British National Grid. The units are in metres to 2 decimal places. See rpc | 308793.00 |
uprn | The Unique Property Reference Number – the primary key field for AddressBase data. Assigned by GeoPlace or Ordnance Survey | 200004353841 |
parentuprn | Where 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 | |
usrn | The Unique Street Reference Number – every street under council control has its own unique identifier and this is it | 28920601 |
changecode | Indicates how this record was last amended on the national hub. AddressBase Core only | |
toid | The topographical identifier which associates this record with OS MasterMap. AddressBase Core only | |
classificationcode | Describes the classification of the property according to council records | CO01 |
rpc | Tells 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 |
gsscode | Provided 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) | |
lastupdatedate | The date this record was last updated | |
morevalues | Set to true when there is another page of results beyond the current page; see pagination for more info | true |
nextpage | The index of the next page of results; see pagination for more info | 1 |
totalresults | The total number of results found; see pagination for more info | 180 |
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:
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); there is no additional credit cost for including this field; 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 ('R' for Residential, 'N' for Non-residential, 'L' for Large User) | 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 | |
| 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. | ||
addresskey | The 8-digit PAF Address Key from Royal Mail (UK only) | 00001000 |
organisationkey | The 8-digit PAF Organisation Key from Royal Mail (UK only, '0' for Residential Small Users and Large Users) | 00456120 |
postcodetype | The PAF Postcode Type from Royal Mail (UK only, 'S' for Small Users, 'L' for Large Users) | S |
| 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 | ||
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 |
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.
Postcoder will truncate large responses to 60 pages; this limit may change from time to time.
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
identifierquerystring 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 on your UK address form: addressline1, addressline2, addressline3, posttown, postcode (county is no longer required in UK addresses)
Credit cost
Each request costs 4.5 credits.
Buy a credit pack or set up a monthly plan to use with all Postcoder endpoints.