Address Autocomplete API
The Address Autocomplete API is used to implement location autocomplete fields. In general, the API is called when a user presses a key in the address field to show address suggestions in a dropdown list.
The main difference to the Geocoding API is that Geocoding API tries to find the provided address, whereas the Autocomplete API returns suggestions for entered part of the address.
Example of Geocoding API request URL
The API has similar to Geocoding API input and output parameters.
- text - search string
- apiKey - your Geoapify key
- filter - filter places by country, boundary, circle
- bias - prefer addresses close to a country, boundary, a circle with a given radius, location. For example, with bias, you can search addresses near the customer location
- lang - language for results
- limit - the maximum amount of returned results
- type - type of the results
The response returned contains a GeoJSON FeatureCollection object, where all features have a "Point" type and represent a place suggestion. Properties of each feature contain address components, location components, and data source information.
Try the Address Autocomplete API in the Playground:
- Register on Geoapify MyProjects
- Create a project.
- Go to the API Keys section. One API key is generated automatically. You can generate multiple API keys per project if required.
- Choose "Autocomplete API" and an API key to get an URL and programming code.
- Press the "Try" button to execute the API call and get the result object.
Usually, the Autocomplete API is used to process user input and display address suggestions in the dropdown list.
We've prepared for you Step by Step tutorial showing how to implement an Address Autocomplete field from scratch and NPM-packages that let you integrate Autocomplete API into your application as a module:
|apiKey||Required parameter for API key|
|text||An address or part of the address to search|
|type||Location type. Possible values: 'country', 'state', 'city', 'postcode', 'street', 'amenity'.|
|lang||Result language. 2-character ISO 639-1 language codes are supported.|
|limit||Maximal number of results. By default is 5|
|filter||Filter places by country, boundary, circle|
|bias||Prefer places by country, boundary, circle, location|
The API allows to set the following types of filters for results:
||Search places inside of the circle||
||Search places inside of the rectangle||
|By country||Comma-separated ISO 3166-1 Alpha-2 country codes (in lower case). Use 'auto' to detect the country by IP address. Use 'none' to skip (default value).||Search places in the countries.||
You can combine several filters (but only one of each type) in one request. Separate filters with
| (pipe) character. The AND logic is applied to the multiple filters. For example, "filter=rect:-115.548725,20.337831,-75.558490,44.866306|countrycode:us" will search places inside the rectangle and filter them by country.
||First, search places inside of the circle, then worldwide||
||First, search places inside of the rectangle, then worldwide||
|By country||Comma-separated ISO 3166-1 Alpha-2 country codes (in lower case). Use 'auto' to detect the country by IP address. Use 'none' to skip (default value).||First, search places in the countries, then worldwide||
||Prioritize results by farness from the location||
You can combine several bias parameters (but only one of each type) in one request. Separate filters with
| (pipe) character. The OR logic is applied to the multiple bias. For example, "bias=proximity:41.225714,52.971411|countrycode:de" will search places near the location, in the counry and then worldwide.
NOTE! The default bias for the geocoding requests is "countrycode:auto", the API detects a country by IP address and provides the serach there first. Set bias to "countrycode:none" to avoid prioritization by country.
The response returned contains a GeoJSON FeatureCollection object, where each feature has a "Point" type. Feature properties have the following fields:
|country||Country component of the address|
|country_code||ISO 3166-1 alpha-2 country code|
|state||State component of the address|
|state_code||State shortcode, the shortcode might be missing for some countries and languages|
|county||County component of the address|
|county_code||County shortcode, the shortcode might be missing for some countries and languages|
|postcode||Postcode or ZIP code of the address|
|city||City component of the address|
|street||Street component of the address|
|housenumber||House number component of an address|
|lat, lon||Coordinates of the location|
|address_line1||Main part of the display address, contains building street and house number or amenity name|
|address_line2||The second part of the display address, contains address parts not included to address_line1|
|result_type||Found location type. Can take values from [
|distance||Distance in meters to given
|rank||Calculated rank for the result|
|rank.confidence||Confidence value, takes values from 0 to 1|
|rank.confidence_city_level||City-level confidence, takes values from 0 to 1. Evaluates if the city is correct.|
|rank.confidence_street_level||Street-level confidence, takes values from 0 to 1. Evaluates if the street is correct.|
|rank.match_type||Match type between requested address and result address. Can take values from [
|datasource||Contains name of data source and data specific for the data source|
Note! Depending on the type of returned location some fields may be missing. For example, the "Asia" continent doesn't have a specific country, state and so on.