autocomplete/find
Postcoder address autocomplete for the UK and Ireland provides real-time suggestions as a user types in their address. It consists of two types of request: one or more find requests to narrow down a list of address suggestions, and a retrieve request to retrieve a full address.
This is the find endpoint and it returns one or more address suggestions. Repeated calls will be needed as a user types (and optionally drills-down through nested suggestions) to find their address. The ID of this suggestion can then be passed to the autocomplete/retrieve endpoint to retrieve the full address.
Request URL
GET https://ws.postcoder.com/pcw/autocomplete/find?query={query}&country={countrycode}&apikey={apikey}
Querystring parameters
Parameter | Description | Example |
---|---|---|
query | The URL-encoded search term (minimum of three characters required, returns empty list otherwise) | query=1%20birchwood |
country | The 2-character country code, use uk for UK or ie for Ireland | country=uk |
apikey | Your API key | apikey=PCW45-12345-12345-1234X |
pathfilter | Use to narrow down the search using a suggestion ID (which does not have a type of ADD for address) from a previous request | pathfilter=UK@STATE\|Suffolk@CTY\|{Rushmere St.Andrew@LOC,Ipswich@PTN,IP@PCDA}@LOC|{Birchwood Drive@STR,IP5-1EB@PCD}@PCD |
maximumresults | The maximum number of results to return, choose from 5 to 30 (default) | maximumresults=10 |
enablefacets | Groups some results together geographically when the search term is too vague to make a confident suggestion, making drilling down with pathfilter easier, true (default) or false | enablefacets=false |
format | Sets the format of the response, xml or json (default unless "application/xml" header is detected) | format=json |
Example requests and responses
Return suggestions for UK addresses that start with or match "1 birchwood":
GET https://ws.postcoder.com/pcw/autocomplete/find?query=1%20birchwood&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
}
]
Return suggestions within the "Flat 1-66, Birchwood Apartments, N4 1FR" group that was found above:
https://ws.postcoder.com/pcw/autocomplete/find?query=1%20birchwood&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
}
]
Response fields
Field | Description | Example |
---|---|---|
id | The ID of the suggestion | 52752859 |
type | The type of suggestion:
| ADD |
summaryline | The summary of the suggestion | 1 Birchwood Hall Cottages |
locationsummary | The location associated with the suggestion | Chathill, Northumberland, NE67 5LG |
count | The number of further suggestions nested within the suggestion | 50 |
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
- Treat all response fields as optional
- Use the autocomplete="xyz" attribute in your input tag if Chrome's autofill blocks your suggestions
- Requests to this endpoint are not logged within your usage history
- Use the /autocomplete/retrieve endpoint to retrieve the full address for a suggestion with type ADD
Credit cost
This endpoint is free to use providing you use it with the chargeable /autocomplete/retrieve endpoint.
Buy a credit pack or set up a monthly plan to use with all Postcoder endpoints.