nyb

This API endpoint returns a list of Royal Mail Not Yet Built addresses for a given UK postcode. Alternatively, Not Yet Built addresses can be included alongside regular UK addresses by using the address endpoint with the querystring parameter nyb=true.

Request URL

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-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: 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 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 Not Yet Built addresses with a postcode of NR1 1NE and include up to 3 address lines in the response:

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/nyb/uk/nr1%201ne?format=json&lines=3

[
	{
		"addressline1": "101010 St. Faiths Lane",
		"summaryline": "101010 St. Faiths Lane, Norwich, Norfolk, NR1 1NE",
		"number": "101010",
		"premise": "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 address line, where the total number of address lines is defined by the `lines` querystring parameter	Allies Computing Ltd
`addressline2`	The second address line	92 St. Faiths Lane
`addressline3`	The third address line
`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
`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 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 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 on your UK address form: addressline1, addressline2, addressline3, posttown, postcode (county is no longer required in UK addresses)

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.