Not Yet Built address lookup

Perform lookups against Royal Mail's Not Yet Built dataset, for premises under construction but not yet available in the PAF® dataset.

This dataset is updated monthly, with the latest data from Royal Mail.

Lookup cost: 1.8 credits

Request structure

http://ws.postcoder.com/pcw/[api-key]/nyb/uk/[postcode-or-address-fragment]

Optional parameters

lines The number of lines over which to split each address
include Include extra address fields within the address lines returned (see above)
exclude Exclude address fields within the address lines returned (see above)
format xml | json (default unless header of application/xml is detected)
addtags Add extra address fields to the return
identifier Identify your lookups to make debugging and reviewing stats easier
callback Use to specify the name of your JSONP callback function
page For use with searches that return more than 100 results (first page is 0)
postcodeonly Use ?postcodeonly=true to limit your search to just the postcode field.

Notes

  • Multiple addresses may be returned depending on your search criteria

  • Empty address fields are not returned in the response, so all fields should be treated as optional

Response examples

Note: As Not Yet Built is a transient dataset, the examples below are not based on live data.

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/nyb/uk/NR147PZ?format=json

[
    {
        "summaryline":"Allies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ",
        "organisation":"Allies Computing Ltd",
        "buildingname":"Manor Farm Barns",
        "premise":"Manor Farm Barns",
        "street":"Fox Road",
        "dependentlocality":"Framingham Pigot",
        "posttown":"Norwich",
        "county":"Norfolk",
        "postcode":"NR14 7PZ",
        "notyetbuilt":"True"
    }
]

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/nyb/uk/NR147PZ?format=xml

<Addresses xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Address>
        <summaryline>
        Allies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ
        </summaryline>
        <organisation>Allies Computing Ltd</organisation>
        <buildingname>Manor Farm Barns</buildingname>
        <premise>Manor Farm Barns</premise>
        <street>Fox Road</street>
        <dependentlocality>Framingham Pigot</dependentlocality>
        <posttown>Norwich</posttown>
        <county>Norfolk</county>
        <postcode>NR14 7PZ</postcode>
        <notyetbuilt>True</notyetbuilt>
    </Address>
</Addresses>

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/nyb/uk/framingham%20pigot?format=xml

<Addresses xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Address>
        <summaryline>
        Allies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ
        </summaryline>
        <organisation>Allies Computing Ltd</organisation>
        <buildingname>Manor Farm Barns</buildingname>
        <premise>Manor Farm Barns</premise>
        <street>Fox Road</street>
        <dependentlocality>Framingham Pigot</dependentlocality>
        <posttown>Norwich</posttown>
        <county>Norfolk</county>
        <postcode>NR14 7PZ</postcode>
        <notyetbuilt>True</notyetbuilt>
    </Address>
</Addresses>

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/nyb/uk/NR147PZ?format=json&lines=3

[
    {
        "addressline1":"Allies Computing Ltd",
        "addressline2":"Manor Farm Barns, Fox Road",
        "addressline3":"Framingham Pigot",
        "summaryline":"Allies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ",
        "organisation":"Allies Computing Ltd",
        "buildingname":"Manor Farm Barns",
        "premise":"Manor Farm Barns",
        "street":"Fox Road",
        "dependentlocality":"Framingham Pigot",
        "posttown":"Norwich",
        "county":"Norfolk",
        "postcode":"NR14 7PZ",
        "notyetbuilt":"True"
    }
]

Response field descriptions

Field name Data type Description Example
summaryline String Summary Allies Computing Ltd, Manor Farm Barns, Fox Road, Framingham Pigot, Norwich, Norfolk, NR14 7PZ
pobox String PO Box
organisation String Organisation Allies Computing Ltd
departmentname String Department name
buildingname String Building name Manor Farm Barns
subbuildingname String Sub Building name
number String Number
premise String Premise name or number Manor Farm Barns
dependentstreet String Dependent street
street String Street Fox Road
doubledependentlocality String Double dependent locality
dependentlocality String Dependent locality Framingham Pigot
posttown String Post town Norwich
county String County Norfolk
postcode String Postcode NR14 7PZ
notyetbuilt Boolean Not Yet Built True
recodes String Colon separated list of the previous postcode, previous delivery point suffix and the date it changed (YYYYMM format)
morevalues Boolean Indicates at least one more page of addresses for the search
nextpage Integer Page number for the next page of results
totalresults Integer Total number of addresses for the search (only shown if more than 100 results)

Paging

Up to 100 results can be returned at a time, in response to a lookup. If there are more results beyond the current page, the last result will include a morevalues field with a value of true.
We also include a nextpage field with the number of the next page, so you can easily append ?page=[nextpage] to your request.

Notes:

  • First page = 0, second page = 1 etc...
  • If there are no more results beyond the current page, the morevalues field will not be present