Address autocomplete

Provides as-you-type address suggestions and then a retrieve step to return a full address.

Supports both UK and Irish addresses.

Lookup cost

Name Find suggestions /find Retrieve a full address /retrieve
UK 0 credits 2 credits
Ireland 0 credits 4.5 credits

Data sources

Country Dataset Updated
UK Royal Mail PAF + Multiple Residence Daily + Monthly
Ireland Eircode ECAD Quarterly

Log in and check your account's data options to enable your API key with Eircode data.

If you’re using an earlier version of autocomplete, we recommend you upgrade to the current version.

Example code

Example user interface on Github »

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.

Tips

  • Chrome's Auto Fill - if you're having issues with Chrome's Auto Fill blocking your suggestions, use the autocomplete="xyz" attribute in your input tag since Chrome ignores the autocomplete="off" attribute.
  • URL encoding - we recommend you URL encode the search term passed in the query parameter

Find address suggestions

Step one of the autocomplete process

Returns a list of summarised addresses and places that match an input query. Tailored to respond to individual key presses.

HTTP(S) GET request

Example: https://ws.postcoder.com/pcw/autocomplete/find

Request parameters

Name Description Required Values
query The search term (minimum of three characters required, returns empty array otherwise) Yes E.g. 1 birchwood h
pathfilter Allows you to narrow down the search using the ID of a suggestion that was not an address from a previous request (i.e. where the type was not "ADD") No E.g. UK@STATE\|Suffolk@CTY\|{Rushmere St. Andrew@LOC,Ipswich@PTN,IP@PCDA}@LOC|{Birchwood Drive@STR,IP5-1EB@PCD}@PCD
country The 2 letter ISO 3166-1 country code Yes UK or IE
apikey The API key Yes E.g. PCW45-12345-12345-1234X
format The response format; default is JSON unless an application/xml header is detected No json or xml
maximumresults The maximum number of results to return; default is 30 No 5 - 30

Response fields

Name Description
id The ID of the address or place
type The type of suggestion; see definitions below
summaryline The summary of the address or place
locationsummary The location associated with the address or place
count The number of further suggestions nested within the suggestion

Full list of type definitions for the 'type' response field

Name Description
ADD Address
BGN Building group
BNA Building name
CCN County
DST Dependent street
LAD District borough
LOC Place
LOC2 Dependent place
LOC3 Double dependent place
NUM Number
ORC Organisation
ORD Department
PCD Postcode
PCDA Postcode area
PCDD Postcode district
PCDS Postcode sector
PCDU1 Postcode unit 1
POB PO Box
SBN Sub building name
STATE State
STR Street
WORLD World

Retrieve a full address

Step two of the autocomplete process

Returns the full details for an address based on its ID.

HTTP(S) GET request

https://ws.postcoder.com/pcw/autocomplete/retrieve

Request parameters

Name Description Required Values
id The ID of a suggestion that was an address from a previous request (i.e. where the type was 'ADD') Yes 6219058
query The original search term Yes E.g. 1 birchwood h
country The 2 letter ISO 3166-1 country code Yes UK or IE
apikey The API key Yes E.g. PCW45-12345-12345-1234X
format The response format; default is JSON unless an application/xml header is detected No json or xml
lines The number of lines over which to split the address No 1 - 4
include Include extra address fields within the address lines returned No See response fields below
exclude Exclude address fields within the address lines returned No See response fields below
addtags Add extra address fields such as UDPRN to the return No See list of fields
identifier Identify your lookup to make debugging and reviewing stats easier No E.g. myform
geo Specifies whether or not to return geographic co-ordinates as part of the returned address. Increase credit cost to 2.4 credits for UK addresses, no extra cost for IE searches; default is false No true or false
callback Use to specify the name of your JSONP callback function No

Response fields

Name Description
summaryline Complete postal address in a single line with commas separating the elements
pobox PO Box
organisation Organisation
departmentname Department name
buildingname Building name
subbuildingname Sub building name
number Number
premise Composite of all premise level elements including department, building name, sub building name, number and PO Box where applicable
dependentstreet Dependent street
street Street
doubledependentlocality Double dependent locality
dependentlocality Dependent locality
posttown Post town
county County
postcode Postcode
recodes Colon separated list of the previous postcode, previous delivery point suffix and the date it changed (YYYYMM format)

Tips

  • Empty address fields - these are not returned in the response so all fields should be treated as optional
  • URL encoding - we recommend you URL encode the search term passed in the query parameter

Find and retrieve examples

Show suggestions for "1 birchwood h"

https://ws.postcoder.com/pcw/autocomplete/find?query=1%20birchwood%20h&country=UK&apikey=PCW45-12345-12345-1234X&format=json

[
    {
        id: "16291869",
        type: "ADD",
        summaryline: "1 Birchwood Hall Cottages",
        locationsummary: "Chathill, Northumberland, NE67 5LG",
        count: 1
    },
    ...
    {
        id: "UK@STATE|Greater London@CTY|London@LOC|Hackney@LAD|{Woodberry Grove@STR,N4@PCDD}@STR|{N4-1FR@PCD,Birchwood Apartments@BNA,Flat 1-66@RNG}@PCD",
        type: "PCD",
        summaryline: "Flat 1-66, Birchwood Apartments, N4 1FR",
        locationsummary: "Woodberry Grove, London, Hackney",
        count: 66
    }
]

Expand the "Flat 1-66, Birchwood Apartments, N4 1FR" suggestion found above

https://ws.postcoder.com/pcw/autocomplete/find?query=1%20birchwood%20h&pathfilter=UK@STATE|Greater%20London@CTY|London@LOC|Hackney@LAD|{Woodberry%20Grove@STR,N4@PCDD}@STR|{N4-1FR@PCD,Birchwood%20Apartments@BNA,Flat%201-66@RNG}@PCD&country=UK&apikey=PCW45-12345-12345-1234X&format=json

[
    {
        id: "52752859",
        type: "ADD",
        summaryline: "Flat 1",
        locationsummary: "Birchwood Apartments, Woodberry Grove, London, Hackney, N4 1FR",
        count: 1
    },
    ...
    {
        id: "52752397",
        type: "ADD",
        summaryline: "Flat 64",
        locationsummary: "Birchwood Apartments, Woodberry Grove, London, Hackney, N4 1FR",
        count: 1
    }
]

Retrieve full address for the "Flat 1, Birchwood Apartments" suggestion found above

https://ws.postcoder.com/pcw/autocomplete/retrieve?id=52752859&query=1%20birchwood%20h&country=UK&apikey=PCW45-12345-12345-1234X&format=json&lines=2

[
    {
        addressline1: "Flat 1, Birchwood Apartments",
        addressline2: "Woodberry Grove",
        summaryline: "Flat 1, Birchwood Apartments, Woodberry Grove, London, Greater London, N4 1FR",
        subbuildingname: "Flat 1",
        buildingname: "Birchwood Apartments",
        premise: "Flat 1, Birchwood Apartments",
        street: "Woodberry Grove",
        posttown: "London",
        county: "Greater London",
        postcode: "N4 1FR"
    }
]

Chain lookups to other endpoints

Combine autocomplete lookup with other API lookups, such as AddressBase Premium for premise-level co-ordinates.

Show suggestions for "8 Mendham Close"

https://ws.postcoder.com/pcw/autocomplete/find?query=8%20Mendham%20Close&country=UK&apikey=PCW45-12345-12345-1234X&format=json

[
    {
        "id": "11657135",
        "type": "ADD",
        "summaryline": "8 Mendham Close",
        "locationsummary": "Harleston, Norfolk, IP20 9DF",
        "count": 1
    },
  ...
    {
        "id": "15912670",
        "type": "ADD",
        "summaryline": "8 Mendham Close",
        "locationsummary": "Gateshead, Tyne and Wear, NE10 9BJ",
        "count": 1
    }
]

Pass the id to the /pafaddressbase/ endpoint as a UDPRN lookup

https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/pafaddressbase/8%20Mendham%20Close?udprn=11657135&addtags=latitude,%20longitude&format=json

[
    {
        "summaryline": "8 Mendham Close, Harleston, Norfolk, IP20 9DF",
        "number": "8",
        "premise": "8",
        "street": "Mendham Close",
        "posttown": "Harleston",
        "county": "Norfolk",
        "postcode": "IP20 9DF",
        "latitude": "52.4004397551638",
        "longitude": "1.30091477564852",
        "grideasting": "624654.0",
        "gridnorthing": "283174.0"
    }
]