Full premise-level address lookup

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

Includes the latest address data from Royal Mail, updated daily.

Lookup cost: 2 credits

Address lookup with JavaScript example

See the Pen Address lookup with JavaScript by Allies Computing (@alliescomputing) on CodePen.

Additional example code

Useful support articles

API reference

If you want to customise our examples, create your own user interface or integrate our API on another platform, you can find all the request parameters and response details below.

If you require further help or have any questions feel free to contact our support team.

Request structure

http://ws.postcoder.com/pcw/[api-key]/address/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 such as UDPRN 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.
alias Use ?alias=true to include alternative names for addresses known to and accepted by Royal Mail

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
  • The lines, include and exclude parameters are only available with the UK, US and IE (Eircode) datasets
  • Include geodata using /addressgeo/ rather than /address/ in the request | Lookup cost: 2.4 credits
  • We recommend to URL encode the postcode or address fragment
  • You don't need to require spaces or uppercase in postcodes we handle many common typos and spelling mistakes for you

Response examples

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

[
    {
        "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"
    }
]

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/uk/NR147PZ?format=xml - View live 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, 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>
    </Address>
</Addresses>

Request: http://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/address/uk/manor%20farm%20barns?format=xml - View live 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, 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>
    </Address>
</Addresses>

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

[
    {
        "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"
    }
]

Response field descriptions

Field name Data type Description Example
summaryline String Complete postal address in a single line with commas separating the elements. 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 Composite of all premise level elements including department, building name, sub building name, number and PO Box where applicable. 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
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)
alias Boolean Indicates address is an alias record, only present when used with ?alias=true

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