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.

Ireland and Eircode: Enable access on your API key using the Features page or by contacting us.

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: Address (suggestions with this type can used with the autocomplete/retrieve endpoint) 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	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
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.