AddressBase Premium and Islands API

AddressBase Premium is a geographic dataset of addresses, properties and land areas in England, Scotland and Wales.

AddressBase Islands extends coverage to include Northern Ireland, Isle of Man and the Channel Islands.

The following collection of routines exclusively serve data from the AddressBase Premium dataset:

To access these routines using your API key, please contact our team or call us on 01508 494488.

Query by postcode or address fragment

Returns delivery point addresses for a postcode (e.g. NR14 7PZ) or address fragment (e.g. Fox Road, Framingham Pigot).

Request structures

Search within the Delivery Point Address (DPA) record
http://ws.postcoder.com/pcw/[api-key]/addressbase/dpa/[postcode-or-address-fragment]

Search within the Local Property Identifier (LPI) record
http://ws.postcoder.com/pcw/[api-key]/addressbase/lpi/[postcode-or-address-fragment]

Search within both the DPA and LPI records
http://ws.postcoder.com/pcw/[api-key]/addressbase/dpalpi/[postcode-or-address-fragment]

Search Royal Mail PAF (refreshed daily) combined with AddressBase Premium (additional costs may apply) http://ws.postcoder.com/pcw/[api-key]/pafaddressbase/[postcode-or-address-fragment]

Optional querystring 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)
geo Include coordinates and grids in the response; true | false (default)
historic Include historic addresses (those with a populated blpu.end_date); true | false (default)
addtags Add extra address fields to the return (use ?addtags=addressbase to show all)
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)

Examples

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/dpa/NR14%207PZ?format=json&addtags=uprn - View response

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

Further examples to try with your own API key:

http://ws.postcoder.com/pcw/[api-key]/addressbase/dpa/NR14%207PZ?format=json&identifier=my-sample-lookup&addtags=addressbase

http://ws.postcoder.com/pcw/[api-key]/addressbase/dpa/NR14%207PZ?format=json&addtags=addressbase&lines=3

http://ws.postcoder.com/pcw/[api-key]/addressbase/dpa/NR14%207PZ?format=json&addtags=addressbase&lines=3&exclude=organisation

http://ws.postcoder.com/pcw/[api-key]/addressbase/dpa/NR14%207PZ?format=json&addtags=addressbase&lines=3&include=postcode

http://ws.postcoder.com/pcw/[api-key]/addressbase/dpa/NR14%207PZ?format=json&addtags=blpu

http://ws.postcoder.com/pcw/[api-key]/addressbase/dpa/NR14%207PZ?format=json&addtags=blpu.logical_status,blpu.rpc,lpis.lpi_key

Examples using our combined PAF and AddressBase Premium dataset

http://ws.postcoder.com/pcw/[api-key]/pafaddressbase/NR14%207PZ?format=json&addtags=uprn

http://ws.postcoder.com/pcw/[api-key]/pafaddressbase/NR14%207PZ?format=json&addtags=blpu,uprn

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




Query by UPRN

Returns delivery point addresses for one or more unique property reference numbers (UPRNs).

Request structure

http://ws.postcoder.com/pcw/[api-key]/addressbase/uprn/[uprns-comma-delimited]

Optional querystring 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)
geo Include coordinates and grids in the response; true | false (default)
historic Include historic addresses (those with a populated blpu.end_date); true | false (default)
addtags Add extra address fields to the return (use ?addtags=addressbase to show all)
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)

Examples

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/uprn/2630163102?format=xml&addtags=uprn - View response

<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, 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>
    <postcode>NR14 7PZ</postcode>
    <uprn>2630163102</uprn>
  </Address>
</Addresses>

Further examples to try with your own API key:

http://ws.postcoder.com/pcw/[api-key]/addressbase/uprn/2630163102?format=json&addtags=addressbase

http://ws.postcoder.com/pcw/[api-key]/addressbase/uprn/2630163102,2630160455?format=json&addtags=uprn&lines=3

http://ws.postcoder.com/pcw/[api-key]/addressbase/uprn/2630163102,2630160455?format=json&addtags=uprn&lines=3&exclude=organisation

http://ws.postcoder.com/pcw/[api-key]/addressbase/uprn/2630163102,2630160455?format=json&addtags=uprn&lines=3&include=postcode

Paging

Up to 100 results can be returned at a time, in response to a lookup - see above.




Query by radius

Returns delivery point addresses within distance of a coordinate position.

Request structure

http://ws.postcoder.com/pcw/[api-key]/addressbase/bounds/radius?latitude=[latitude]&longitude=[longitude]&distance=[radius-in-km]

Optional querystring 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)
geo Include coordinates and grids in the response; true | false (default)
historic Include historic addresses (those with a populated blpu.end_date); true | false (default)
addtags Add extra address fields to the return (use ?addtags=addressbase to show all)
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)

Examples

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/bounds/radius?format=json&latitude=52.5858290334004&longitude=1.34859473810611&distance=1.0&geo=true - View response

[
  {
    "summaryline": "Munns Cottage, The Street, Framingham Pigot, Norwich, NR14 7QJ",
    "buildingname": "Munns Cottage",
    "premise": "Munns Cottage",
    "street": "The Street",
    "dependentlocality": "Framingham Pigot",
    "posttown": "Norwich",
    "postcode": "NR14 7QJ",
    "latitude": "52.5829203037123",
    "longitude": "1.35380642053706",
    "grideasting": "627308",
    "gridnorthing": "303629"
  },
  {
    ... 
  }
]

Further examples to try with your own API key:

http://ws.postcoder.com/pcw/[api-key]/addressbase/bounds/radius?format=json&latitude=52.5858290334004&longitude=1.34859473810611&distance=1.0&addtags=addressbase

http://ws.postcoder.com/pcw/[api-key]/addressbase/bounds/radius?format=json&latitude=52.5858290334004&longitude=1.34859473810611&distance=1.0&addtags=uprn&lines=3

Paging

Up to 100 results can be returned at a time, in response to a lookup - see above.




Query by bounding box

Returns delivery point addresses within a bounding box centred on a coordinate position.

The distance specified in the request is equal to half the width of the bounding box.

Request structure

http://ws.postcoder.com/pcw/[api-key]/addressbase/bounds/boundingbox?latitude=[latitude]&longitude=[longitude]&distance=[half-the-width-of-bounding-box-in-km]

Optional querystring 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)
geo Include coordinates and grids in the response; true | false (default)
historic Include historic addresses (those with a populated blpu.end_date); true | false (default)
addtags Add extra address fields to the return (use ?addtags=addressbase to show all)
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)

Examples

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/addressbase/bounds/boundingbox?format=json&latitude=52.5858290334004&longitude=1.34859473810611&distance=1.0&geo=true - View response

[
  {
    "summaryline": "1 Caistor Lane, Poringland, Norwich, NR14 7QT",
    "number": "1",
    "premise": "1",
    "street": "Caistor Lane",
    "dependentlocality": "Poringland",
    "posttown": "Norwich",
    "postcode": "NR14 7QT",
    "latitude": "52.5816713067281",
    "longitude": "1.33531415699097",
    "grideasting": "626062",
    "gridnorthing": "303432"
  },
  {
    ... 
  }
]

Further examples to try with your own API key:

http://ws.postcoder.com/pcw/[api-key]/addressbase/bounds/boundingbox?format=json&latitude=52.5858290334004&longitude=1.34859473810611&distance=1.0&addtags=addressbase

http://ws.postcoder.com/pcw/[api-key]/addressbase/bounds/boundingbox?format=json&latitude=52.5858290334004&longitude=1.34859473810611&distance=1.0&addtags=uprn&lines=3

Paging

Up to 100 results can be returned at a time, in response to a lookup - see above.