Cookie

We use cookies to improve your experience on our site, and to provide a live chat feature. To find out more please read our privacy policy.

Skip to content

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

ParameterDescriptionExample
queryThe URL-encoded search term (minimum of three characters required, returns empty list otherwise)query=1%20birchwood
countryThe 2-character country code, use uk for UK or ie for Irelandcountry=uk
apikeyYour API keyapikey=PCW45-12345-12345-1234X
pathfilterUse to narrow down the search using a suggestion ID (which does not have a type of ADD for address) from a previous requestpathfilter=UK@STATE\|Suffolk@CTY\|{Rushmere St.Andrew@LOC,Ipswich@PTN,IP@PCDA}@LOC|{Birchwood Drive@STR,IP5-1EB@PCD}@PCD
maximumresultsThe maximum number of results to return, choose from 5 to 30 (default)maximumresults=10
enablefacetsGroups 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 falseenablefacets=false
formatSets 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

FieldDescriptionExample
idThe ID of the suggestion52752859
typeThe 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
summarylineThe summary of the suggestion1 Birchwood Hall Cottages
locationsummaryThe location associated with the suggestionChathill, Northumberland, NE67 5LG
countThe number of further suggestions nested within the suggestion50

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.