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:
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
- Register on Geoapify MyProjects page
- Create a new project.
- Go to the API Keys section. One API key is generated automatically. You can generate multiple API keys per project if required.
- Optionally, you can protect the API key by listing allowed IP addresses, HTTP referrers, origins, and CORS.
- Choose "Address 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.
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
https://api.geoapify.com/v1/geocode/autocomplete?REQUEST_PARAMS
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. |
| 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:
- Step by step JavaScript Tutorial
- @geoapify/geocoder-autocomplete - npm-package for a JavaSript/TypeScript project
- @geoapify/angular-geocoder-autocomplete - npm-package for an Angular component
- @geoapify/react-geocoder-autocomplete - npm-package for a React component
Pricing
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.