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


https://api.geoapify.com/v1/geocode/autocomplete?text=Berlin&limit=5&apiKey=YOUR_API_KEY


The API has similar to Geocoding API input and output parameters.

Required parameters:

  • text - search string
  • apiKey - your Geoapify key

Optional parameters:

  • 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:

Live demo

Quick start

  1. Register on Geoapify MyProjects
  2. Create a project.
  3. Go to the API Keys section. One API key is generated automatically. You can generate multiple API keys per project if required.
  4. Choose "Autocomplete API" and an API key to get an URL and programming code.
  5. Press the "Try" button to execute the API call and get the result object.

Code samples

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:

API Specification

Base URL


https://api.geoapify.com/v1/geocode/autocomplete


Request parameters

Name Description
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

Filters

The API allows to set the following types of filters for results:

Name Format Description Examples
By circle circle:lon,lat,radiusMeters Search places inside of the circle filter=circle:-87.770231,41.878968,5000
By rectangle rect:lon1,lat1,lon2,lat2 Search places inside of the rectangle filter=rect:-89.097540,39.668983,-88.399274,40.383412
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. filter=countrycode:de,es,fr

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.

Bias

Name Format Description Examples
By circle circle:lon,lat,radiusMeters First, search places inside of the circle, then worldwide bias=circle:-87.770231,41.878968,5000
By rectangle rect:lon1,lat1,lon2,lat2 First, search places inside of the rectangle, then worldwide bias=rect:-89.097540,39.668983,-88.399274,40.383412
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 bias=countrycode:de,es,fr
By location bias=proximity:lon,lat Prioritize results by farness from the location bias=proximity:41.2257145,52.971411

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.

Response Object

The response returned contains a GeoJSON FeatureCollection object, where each feature has a "Point" type. Feature properties have the following fields:

Name Description
name Location name
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
formatted Display address
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 [unknown, amenity, building, street, suburb, district, postcode, city, county, state, country]
distance Distance in meters to given bias:proximity
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 [ full_match, inner_part, match_by_building match_by_street, match_by_postcode, match_by_city_or_disrict, match_by_country_or_state]
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.