Address Autocomplete API

Geoapify Address Autocomplete API (Place Autocomplete) is used to implement location autocomplete fields. It returns suggestions for address or places fields based on provided part of the address.

The API allows developing address input fields with built-in location validation. Moreover, You can use the API to autocomplete fields. For example, you can autofill city and state from zip code.

Try the Place Autocomplete field and its parameters in the API Playground:

Address autocomplete Live Demo

Authentication and API key

If you don't have an API key, create one from our registration page. Once you register, you can get a Geocoding API key for free! For an overview of our plans, please take a look at our price page.

How to get Address Autocomplete API key

  1. Register on Geoapify MyProjects page
  2. Create a new 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. Optionally, you can protect the API key by listing allowed IP addresses, HTTP referrers, origins, and CORS.
  5. Choose "Address Autocomplete API" and an API key to get an URL and programming code.
  6. Press the "Try" button to execute the API call and get the result object.

API reference

The Address Autocomplete API accepts free-form addresses and address parts as input, and delivers a JSON, GeoJSON, and XML object in response. In addition, you can specify location filters and biases to make the location search more focused.

Request URL

Here are examples of the Autocomplete URLs in action:

  • Simple address search ("Lessingstra├če 3, Regensburg"):

  • Cities suggestions for "Regen":

  • German cities suggestions for "Regen":

  • German postcodes suggestions for "123":

Request parameters

Name Description Example
apiKey Required parameter for API key apiKey=c3da27885e3573e09e550d044bc55e22
text An address or part of the address to search text=Auts
type Location type. Possible values: 'country', 'state', 'city', 'postcode', 'street', 'amenity', 'locality'. The type=locality parameter returns administrative areas including postcodes, districts, cities, counties, and states. type=postcode
lang Result language. 2-character ISO 639-1 language codes are supported. lang=de
filter Filter places by country, boundary, circle. See the Location Filters in Geocoding API, for more details. filter=rect:-122.569140,37.936672,-122.5324795,37.9588474
bias Prefer places by country, boundary, circle, location. See the Location Bias in Geocoding API, for more details. bias=proximity:-122.52985959,37.95335060
format Response object type: 'json', 'xml', or 'geojson' (default). format=json

Response Object

Depending on the format parameter, the API returns GeoJSON.FeatureCollection, JSON, or XML object as a result. Each returned address contains the following address details:

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
category A place category from the list of Places API Categories
timezone Information about timezone the place belongs to. Timezone name.
timezone.name_alt The alternative name of the timezone, if exist.
timezone.offset_STD Time offset.
timezone.offset_STD_seconds Time offset in seconds.
timezone.offset_DST Time offset for daylight saving time.
timezone.offset_DST_seconds Time offset in seconds for daylight saving time.
timezone.abbreviation_STD Timezone abbreviation. Provided when exists.
timezone.abbreviation_DST Timezone abbreviation for daylight saving time. Provided when exists.

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.

Code samples

Typically, you would have the Address Autocomplete API as a part of address input and validation forms. So in this section, we will focus more on how to implement the autocomplete functionality.

We've prepared for you Step by Step tutorial showing how to create an Address Autocomplete field from scratch and NPM-packages that let you integrate Autocomplete API into your application as a module:


Geoapify Location Platform provides APIs which have different difficulty, execution times and require different resource capacities on our servers.

To make our pricing plans easy-to-understand and unify them we introduced "credits" currency that is used to describe conditions and options of each pricing plan. All the credits used for Geoapify API calls per 24 hours accumulated to Daily API usage.

Check Geoapify Pricing Plans and choose the one that fits your needs the best.

One Geocoding API / Reverse Geocoding API / Autocomplete API request is equal to one credit:

API name Cost in credits Example
Geocoding API 1 request = 1 credit 100 requests costs 100 credits
Reverse Geocoding API 1 request = 1 credit 100 requests costs 100 credits
Address Autocomplete 1 request = 1 credit 100 requests costs 100 credits

You can save up to 50% of API call costs when you send Batch Geocoding requests.