nyb
This endpoint returns one or more Royal Mail Not Yet Built addresses for a given UK postcode.
Request URL
GET https://ws.postcoder.com/pcw/{apikey}/nyb/uk/{postcode}
Path parameters
Parameter | Description | Example |
---|---|---|
apikey | Your API key | PCW45-12345-12345-1234X |
postcode | The URL-encoded UK 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-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 |
postcodeonly | Limits the request to a postcode-only search rather than matching the search term on other parts of an address, UK only, true or false (default) | postcodeonly=true |
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 request and response
Return Not Yet Built addresses with a postcode of NR1 1NE and include two address lines in the response:
GET https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/nyb/uk/nr1%201ne?format=json&lines=2
[
{
"addressline1": "House-Under-Construction, 101010 St. Faiths Lane",
"summaryline": "House-Under-Construction, 101010 St. Faiths Lane, Norwich, Norfolk, NR1 1NE",
"buildingname": "House-Under-Construction",
"number": "101010",
"premise": "House-Under-Construction, 101010",
"street": "St. Faiths Lane",
"posttown": "Norwich",
"county": "Norfolk",
"postcode": "NR1 1NE"
},
...
...
]
Response fields
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 |
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); 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 | ||
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
- Use these fields to create a UK postal address: addressline1, addressline2, posttown, postcode
Credit cost
Each request costs the following number of credits:
Standard request | Enhanced request using addtags |
---|---|
1.8 credits | 2.2 credits |
Buy a credit pack or set up a monthly plan to use with all Postcoder endpoints.