Geocoding API documentation

Geoapify provides Geocoding API that searches addresses worldwide. The API works via HTTP GET API. So it's cross-platform and can be used with most of the programming languages.

Together with address, the API supports setting language, filter, and bias as an input that let you make an accurate and precise address search.

Example of Geocoding API request URL


https://api.geoapify.com/v1/geocode/search?text=Paris&lang=fr&limit=3&type=city&filter=countrycode:us,ca&bias=proximity:-95.53684,42.59813&apiKey=YOUR_API_KEY


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
  • 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 Geocoding 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 "Geocoding 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

Geoapify Geocoding API works via HTTP GET requests and returns a result in JSON format. You can execute an HTTP GET request almost with any language and any platform.

Call Geocoding API

Here code samples that help to implement Geocoding API call on different languages:

JavaScript (with fetch)

var requestOptions = {
  method: 'GET',
};

fetch("https://api.geoapify.com/v1/geocode/search?text=38%20Upper%20Montagu%20Street%2C%20Westminster%20W1H%201LJ%2C%20United%20Kingdom&apiKey=YOUR_API_KEY", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

NodeJS (with node-fetch)

Install node-fetch package with:

npm i node-fetch
var fetch = require('node-fetch');
var requestOptions = {
  method: 'GET',
};

fetch("https://api.geoapify.com/v1/geocode/search?text=38%20Upper%20Montagu%20Street%2C%20Westminster%20W1H%201LJ%2C%20United%20Kingdom&apiKey=YOUR_API_KEY", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Python

import requests
from requests.structures import CaseInsensitiveDict

url = "https://api.geoapify.com/v1/geocode/search?text=38%20Upper%20Montagu%20Street%2C%20Westminster%20W1H%201LJ%2C%20United%20Kingdom&apiKey=YOUR_API_KEY"

headers = CaseInsensitiveDict()
headers["Accept"] = "application/json"

resp = requests.get(url, headers=headers)

print(resp.status_code)

Java

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.geoapify.com/v1/geocode/search?text=38%20Upper%20Montagu%20Street%2C%20Westminster%20W1H%201LJ%2C%20United%20Kingdom&apiKey=YOUR_API_KEY"))
      .header("Content-Type", "application/json")
      .build();

HttpResponse<String> response =
      client.send(request, BodyHandlers.ofString());

System.out.println(response.body());

Search address by string or structured address

With the Geocoding API you can search addresses by string value or by structured value i.e., house number, street, city, postcode, country, and other address components:

curl --location--request GET 'https://api.geoapify.com/v1/geocode/search?housenumber=1&street=Paradeplein&postcode=2018&city=Antwerpen&country=Belgium&apiKey=YOUR_API_KEY'

Set bias and filter

With bias and proximity, you can set required or preferred search areas. For example, when you search "Paris" with no bias and filter, you get Paris in France. However, when you set bias proximity in the United States, you will first get Paris cities in the United States:

curl --location--request GET 'https://api.geoapify.com/v1/geocode/search?text=Paris&bias=proximity:-102.87153008183009,35.476207289666064|countrycode:none&apiKey=YOUR_API_KEY'

API Specification

Base URL


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


Request parameters

Name Address type Description
apiKey Required parameter for API key
text Free-form address Address to search. Use 'text' parameter or structured address parameters.
name Structured address Amenity or place name. Structured address parameters are an alternative to the 'text' parameter.
housenumber Structured address House number. Structured address parameters are an alternative to the 'text' parameter.
street Structured address Street name. Structured address parameters are an alternative to the 'text' parameter.
postcode Structured address Postcode. Structured address parameters are an alternative to the 'text' parameter.
city Structured address City name. Structured address parameters are an alternative to the 'text' parameter.
state Structured address State name. Structured address parameters are an alternative to the 'text' parameter.
country Structured address Country name. Structured address parameters are an alternative to the 'text' parameter.
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.