autocomplete/find

Request URL

Querystring parameters

Supported countries and country codes

The following 249 countries are supported by this endpoint. The address level shown for each country reflects the highest level of data supported. There are three levels:

• Premise: delivery points and buildings
• Street: streets and similar levels of geography
• Locality: villages, towns and cities

Example requests and responses

Return UK suggestions for "1 birchwood" in a single summaryline:

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

Return UK suggestions for "1 birchwood" across 2 response fields, summaryline and locationsummary:

[
	{
		"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,N@PCDA,N4@PCDD}@STR|{N4-1FR@PCD,N4-1@PCDS,Birchwood Apartments@BNA}@BNA",
		"type": "BNA",
		"summaryline": "Birchwood Apartments",
		"locationsummary": "Woodberry Grove, Hackney, London, N4 1FR",
		"count": 66
	}
]

Return suggestions from the "Birchwood Apartments" group found above in a single summaryline:

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

Response fields

Integration advice

• For best performance, implement debouncing to wait for a pause in user activity (e.g. 300ms) before making a request, and consider using a JavaScript AbortController (or an equivalent in other languages) to cancel in-flight requests when a new query is triggered
• 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
• If your address form has a country selector, use the ipaddress endpoint to preset the country based on the user's IP address

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.