autocomplete/find
Postcoder address autocomplete provides free real-time address suggestions as users start to type their address, and a chargeable lookup to retrieve full details of a selected address. It supports 249 countries.
This API endpoint accepts a partial address query (e.g. SW1 or 1600 Penn) and returns a list of address suggestions. Each suggestion includes a unique ID, type, summary (e.g. Churchill Gardens, Westminster, London, SW1V 3) and count of the addresses associated with it (e.g. 1500).
Results can be refined by making sequential autocomplete/find requests - for example, SW1V followed by SW1V 3 - or by applying the path filter on a suggestion to narrow the search. The full address for a suggestion can be retrieved by passing its ID to the chargeable autocomplete/retrieve endpoint.
Request URL
https://ws.postcoder.com/pcw/autocomplete/find?query={query}&country={countrycode}&apikey={apikey}
Querystring parameters
Parameter | Description | Example |
---|---|---|
apikey | Your API key | apikey=PCW45-12345-12345-1234X |
query | The URL-encoded search term (minimum of three characters required, returns empty list otherwise) | query=1%20birchwood |
country | The 2-character country code, see supported countries below; if your address form has a country selector, use the ipaddress endpoint to preset the country based on the user's IP address | country=uk |
usercategory | Filters suggestions by category; UK and Ireland only. Supported values:
| usercategory=R |
postcode | Filters suggestions by a full or partial postcode (e.g. IP5); UK only | postcode=ip5 |
pathfilter | Narrows the search using a URL-encoded suggestion ID from a previous request, provided it does not have a type of ADD (for address) | pathfilter=UK%40STATE%7CGreater%20London%40CTY%7CLondon%40LOC%7CHackney%40LAD%7C%7BWoodberry%20Grove%40STR%2CN%40PCDA%2CN4%40PCDD%7D%40STR%7C%7BN4-1FR%40PCD%2CN4-1%40PCDS%2CBirchwood%20Apartments%40BNA%7D%40BNA |
addtags | Adds extra fields into the response using a comma-delimited list. Supported values:
| addtags=usercategory |
singlesummary | Returns suggestions in a single response field (summaryline ) when true, and in two response fields (summaryline and locationsummary ) when false (default) | singlesummary=true |
maximumresults | Sets the maximum number of results to return, choose from 5 to 30 (default) | maximumresults=10 |
enablefacets | Set to false to disable grouping of geographically related suggestions in the UK and Ireland; ignored for other countries | enablefacets=false |
format | Sets the format of the response, xml or json (default unless "application/xml" header is detected) | format=json |
Supported countries and country codes
The following 249 countries are supported by this endpoint. The address and geocoding levels shown for each country reflect 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
Country | Code | Address level | Geocoding level | Updated |
---|---|---|---|---|
Afghanistan | AF | Locality | - | Quarterly |
Aland Islands | AX | Premise | - | Quarterly |
Albania | AL | Street | - | Quarterly |
Algeria | DZ | Street | - | Quarterly |
American Samoa | AS | Premise | - | Monthly |
Andorra | AD | Premise | - | Quarterly |
Angola | AO | Street | - | Quarterly |
Anguilla | AI | Street | - | Quarterly |
Antarctica | AQ | Locality | - | Quarterly |
Antigua and Barbuda | AG | Street | - | Quarterly |
Argentina | AR | Premise | Street | Quarterly |
Armenia | AM | Street | - | Quarterly |
Aruba | AW | Street | - | Quarterly |
Australia | AU | Premise | Street | Quarterly |
Austria | AT | Premise | Street | Quarterly |
Azerbaijan | AZ | Premise | - | Quarterly |
Bahamas | BS | Premise | - | Quarterly |
Bahrain | BH | Premise | - | Quarterly |
Bangladesh | BD | Street | - | Quarterly |
Barbados | BB | Street | - | Quarterly |
Belarus | BY | Street | - | Quarterly |
Belgium | BE | Premise | Street | Quarterly |
Belize | BZ | Street | - | Quarterly |
Benin | BJ | Street | - | Quarterly |
Bermuda | BM | Street | - | Quarterly |
Bhutan | BT | Street | - | Quarterly |
Bolivia | BO | Street | - | Quarterly |
Bonaire, Sint Eustatius And Saba | BQ | Locality | - | Quarterly |
Bosnia and Herzegovina | BA | Premise | - | Quarterly |
Botswana | BW | Premise | - | Quarterly |
Bouvet Island | BV | Street | - | Quarterly |
Br. Indian Ocean Ter. | IO | Locality | - | Quarterly |
Brazil | BR | Premise | Street | Quarterly |
Brunei Darussalam | BN | Premise | - | Quarterly |
Bulgaria | BG | Premise | - | Quarterly |
Burkina Faso | BF | Street | - | Quarterly |
Burundi | BI | Street | - | Quarterly |
Cambodia | KH | Street | - | Quarterly |
Cameroon | CM | Street | - | Quarterly |
Canada | CA | Premise | - | Quarterly |
Cape Verde | CV | Street | - | Quarterly |
Cayman Islands | KY | Premise | - | Quarterly |
Central African Rep. | CF | Street | - | Quarterly |
Chad | TD | Street | - | Quarterly |
Chile | CL | Premise | Street | Quarterly |
China | CN | Street | - | Quarterly |
Christmas Island | CX | Locality | - | Quarterly |
Cocos (Keeling) Islands | CC | Locality | - | Quarterly |
Colombia | CO | Premise | - | Quarterly |
Comoros | KM | Street | - | Quarterly |
Congo (Dem. Rep.) | CD | Street | - | Quarterly |
Congo (Rep.) | CG | Street | - | Quarterly |
Cook Islands | CK | Street | - | Quarterly |
Costa Rica | CR | Premise | - | Quarterly |
Côte d'Ivoire | CI | Locality | - | Quarterly |
Croatia | HR | Premise | - | Quarterly |
Cuba | CU | Street | - | Quarterly |
Curacao | CW | Street | - | Quarterly |
Cyprus | CY | Premise | - | Quarterly |
Czech Republic | CZ | Premise | - | Quarterly |
Denmark | DK | Premise | - | Quarterly |
Djibouti | DJ | Street | - | Quarterly |
Dominica | DM | Street | - | Quarterly |
Dominican Republic | DO | Street | - | Quarterly |
Ecuador | EC | Premise | - | Quarterly |
Egypt | EG | Premise | - | Quarterly |
El Salvador | SV | Street | - | Quarterly |
Equatorial Guinea | GQ | Street | - | Quarterly |
Eritrea | ER | Street | - | Quarterly |
Estonia | EE | Premise | - | Quarterly |
Ethiopia | ET | Street | - | Quarterly |
Falkland Is. (Malvinas) | FK | Street | - | Quarterly |
Faröe Islands | FO | Street | - | Quarterly |
Fiji | FJ | Street | - | Quarterly |
Finland | FI | Premise | - | Quarterly |
France | FR | Premise | Street | Quarterly |
French Guiana | GF | Premise | - | Quarterly |
French Polynesia | PF | Street | - | Quarterly |
French Southern Territories | TF | Locality | - | Quarterly |
Gabon | GA | Street | - | Quarterly |
Gambia | GM | Street | - | Quarterly |
Georgia | GE | Street | - | Quarterly |
Germany | DE | Premise | Street | Quarterly |
Ghana | GH | Street | - | Quarterly |
Gibraltar | GI | Premise | - | Quarterly |
Greece | GR | Premise | - | Quarterly |
Greenland | GL | Street | - | Quarterly |
Grenada | GD | Street | - | Quarterly |
Guadeloupe | GP | Premise | - | Quarterly |
Guam | GU | Premise | - | Monthly |
Guatemala | GT | Street | - | Quarterly |
Guernsey | GG | Premise | Street | Daily |
Guinea | GN | Street | - | Quarterly |
Guinea-Bissau | GW | Street | - | Quarterly |
Guyana | GY | Street | - | Quarterly |
Haiti | HT | Street | - | Quarterly |
Heard Island and McDonald Islands | HM | Street | - | Quarterly |
Honduras | HN | Street | - | Quarterly |
Hong Kong | HK | Premise | - | Quarterly |
Hungary | HU | Premise | - | Quarterly |
Iceland | IS | Premise | - | Quarterly |
India | IN | Premise | Street | Quarterly |
Indonesia | ID | Premise | - | Quarterly |
Iran | IR | Locality | - | Quarterly |
Iraq | IQ | Street | - | Quarterly |
Ireland | IE | Premise | Street | Quarterly |
Isle of Man | IM | Premise | Street | Daily |
Israel | IL | Premise | - | Quarterly |
Italy | IT | Premise | Street | Quarterly |
Jamaica | JM | Street | - | Quarterly |
Japan | JP | Premise | - | Quarterly |
Jersey | JE | Premise | Street | Daily |
Jordan | JO | Premise | - | Quarterly |
Kazakhstan | KZ | Premise | - | Quarterly |
Kenya | KE | Street | - | Quarterly |
Kiribati | KI | Street | - | Quarterly |
Korea (Dem. Rep.) | KP | Locality | - | Quarterly |
Korea (Rep.) | KR | Premise | - | Quarterly |
Kuwait | KW | Premise | - | Quarterly |
Kyrgyzstan | KG | Street | - | Quarterly |
Laos | LA | Locality | - | Quarterly |
Latvia | LV | Premise | - | Quarterly |
Lebanon | LB | Premise | - | Quarterly |
Lesotho | LS | Premise | - | Quarterly |
Liberia | LR | Street | - | Quarterly |
Libya | LY | Street | - | Quarterly |
Liechtenstein | LI | Premise | - | Quarterly |
Lithuania | LT | Premise | - | Quarterly |
Luxembourg | LU | Premise | - | Quarterly |
Macao | MO | Premise | - | Quarterly |
Macedonia, TFYR | MK | Premise | - | Quarterly |
Madagascar | MG | Street | - | Quarterly |
Malawi | MW | Street | - | Quarterly |
Malaysia | MY | Premise | - | Quarterly |
Maldives | MV | Street | - | Quarterly |
Mali | ML | Street | - | Quarterly |
Malta | MT | Premise | - | Quarterly |
Marshall Islands | MH | Premise | - | Monthly |
Martinique | MQ | Premise | - | Quarterly |
Mauritania | MR | Street | - | Quarterly |
Mauritius | MU | Street | - | Quarterly |
Mayotte | YT | Street | - | Quarterly |
Mexico | MX | Premise | - | Quarterly |
Micronesia | FM | Premise | - | Monthly |
Moldova | MD | Street | - | Quarterly |
Monaco | MC | Premise | - | Quarterly |
Mongolia | MN | Street | - | Quarterly |
Montenegro | ME | Premise | - | Quarterly |
Montserrat | MS | Street | - | Quarterly |
Morocco | MA | Premise | - | Quarterly |
Mozambique | MZ | Street | - | Quarterly |
Myanmar | MM | Street | - | Quarterly |
Namibia | NA | Premise | - | Quarterly |
Nauru | NR | Locality | - | Quarterly |
Nepal | NP | Street | - | Quarterly |
Netherlands | NL | Premise | Street | Quarterly |
New Caledonia | NC | Street | - | Quarterly |
New Zealand | NZ | Premise | Street | Quarterly |
Nicaragua | NI | Street | - | Quarterly |
Niger | NE | Street | - | Quarterly |
Nigeria | NG | Street | - | Quarterly |
Niue | NU | Street | - | Quarterly |
Norfolk Island | NF | Street | - | Quarterly |
Northern Mariana Islands | MP | Premise | - | Monthly |
Norway | NO | Premise | Street | Quarterly |
Oman | OM | Premise | - | Quarterly |
Pakistan | PK | Locality | - | Quarterly |
Palau | PW | Premise | - | Monthly |
Palestinian Territory | PS | Locality | - | Quarterly |
Panama | PA | Premise | - | Quarterly |
Papua New Guinea | PG | Street | - | Quarterly |
Paraguay | PY | Premise | - | Quarterly |
Peru | PE | Premise | - | Quarterly |
Philippines | PH | Premise | - | Quarterly |
Pitcairn | PN | Locality | - | Quarterly |
Poland | PL | Premise | Street | Quarterly |
Portugal | PT | Premise | Street | Quarterly |
Puerto Rico | PR | Premise | - | Monthly |
Qatar | QA | Premise | - | Quarterly |
Réunion | RE | Premise | - | Quarterly |
Romania | RO | Premise | - | Quarterly |
Russia | RU | Premise | Street | Quarterly |
Rwanda | RW | Street | - | Quarterly |
S. Georgia and S. Sandwich | GS | Locality | - | Quarterly |
Saint Helena | SH | Street | - | Quarterly |
Saint Lucia | LC | Street | - | Quarterly |
Saint Martin | MF | Street | - | Quarterly |
Saint Pierre and Miquelon | PM | Street | - | Quarterly |
Saint-Barthélemy | BL | Premise | - | Quarterly |
Samoa | WS | Street | - | Quarterly |
San Marino | SM | Premise | - | Quarterly |
Sao Tomé and Principe | ST | Street | - | Quarterly |
Saudi Arabia | SA | Premise | - | Quarterly |
Senegal | SN | Street | - | Quarterly |
Serbia | RS | Premise | - | Quarterly |
Seychelles | SC | Street | - | Quarterly |
Sierra Leone | SL | Street | - | Quarterly |
Singapore | SG | Premise | - | Quarterly |
Sint Maarten | SX | Street | - | Quarterly |
Slovakia | SK | Premise | - | Quarterly |
Slovenia | SI | Premise | - | Quarterly |
Solomon Islands | SB | Street | - | Quarterly |
Somalia | SO | Street | - | Quarterly |
South Africa | ZA | Premise | - | Quarterly |
South Sudan | SS | Street | - | Quarterly |
Spain | ES | Premise | Street | Quarterly |
Sri Lanka | LK | Street | - | Quarterly |
St. Kitts and Nevis | KN | Street | - | Quarterly |
St. Vincent and Grenadines | VC | Street | - | Quarterly |
Sudan | SD | Locality | - | Quarterly |
Suriname | SR | Premise | - | Quarterly |
Svalbard and Jan Mayen | SJ | Street | - | Quarterly |
Swaziland | SZ | Street | - | Quarterly |
Sweden | SE | Premise | - | Quarterly |
Switzerland | CH | Premise | Street | Quarterly |
Syria | SY | Locality | - | Quarterly |
Taiwan | TW | Premise | - | Quarterly |
Tajikistan | TJ | Street | - | Quarterly |
Tanzania | TZ | Street | - | Quarterly |
Thailand | TH | Premise | - | Quarterly |
Timor-Leste | TL | Locality | - | Quarterly |
Togo | TG | Street | - | Quarterly |
Tokelau | TK | Street | - | Quarterly |
Tonga | TO | Street | - | Quarterly |
Trinidad and Tobago | TT | Street | - | Quarterly |
Tunisia | TN | Premise | - | Quarterly |
Turkey | TR | Premise | - | Quarterly |
Turkmenistan | TM | Street | - | Quarterly |
Turks and Caicos Is. | TC | Street | - | Quarterly |
Tuvalu | TV | Street | - | Quarterly |
Uganda | UG | Street | - | Quarterly |
Ukraine | UA | Premise | - | Quarterly |
United Arab Emirates | AE | Premise | - | Quarterly |
United Kingdom | UK | Premise | Street and Premise | Daily |
United States Minor Outlying Islands | UM | Locality | - | Quarterly |
United States of America | US | Premise | - | Every two months |
United States Virgin Islands | VI | Premise | - | Monthly |
Uruguay | UY | Premise | - | Quarterly |
Uzbekistan | UZ | Street | - | Quarterly |
Vanuatu | VU | Street | - | Quarterly |
Vatican City | VA | Street | - | Quarterly |
Venezuela | VE | Street | - | Quarterly |
Viet Nam | VN | Premise | - | Quarterly |
Virgin Islands, British | VG | Street | - | Quarterly |
Wallis and Futuna | WF | Street | - | Quarterly |
Western Sahara | EH | Locality | - | Quarterly |
Yemen | YE | Locality | - | Quarterly |
Zambia | ZM | Street | - | Quarterly |
Zimbabwe | ZW | Premise | - | Quarterly |
Example requests and responses
Return UK suggestions for "1 birchwood" in a single summaryline
:
https://ws.postcoder.com/pcw/autocomplete/find?query=1%20birchwood&country=uk&apikey=PCW45-12345-12345-1234X&singlesummary=true&format=json
[
{
"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
:
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,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
:
https://ws.postcoder.com/pcw/autocomplete/find?query=1%20birchwood&pathfilter=UK%40STATE%7CGreater%20London%40CTY%7CLondon%40LOC%7CHackney%40LAD%7C%7BWoodberry%20Grove%40STR%2CN%40PCDA%2CN4%40PCDD%7D%40STR%7C%7BN4-1FR%40PCD%2CN4-1%40PCDS%2CBirchwood%20Apartments%40BNA%7D%40BNA&country=uk&apikey=PCW45-12345-12345-1234X&singlesummary=true&format=json
[
{
"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
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
- 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.