Forward Geocoding API

Geoapify provides Geocoding REST API that searches addresses worldwide. The REST API works via HTTP GET and returns JSON or XML responses. The API is cross-platform and can be used with most programming languages.

On this documentation page, you find geocoding examples, including calling the geocoding with Javascript, Python, Java languages. We show you how to geocode countries, states, cities, postcodes (or zip codes). Our code samples demonstrate how to geocode addresses with filters by geometries, bias, and different languages.

Try the API and play with Geocoding parameters in the API Playground:

Forward Geocoding Live Demo



Authenfication and API key

To use the API, you'll need an API key. But don't worry! You can register and get a Geocoding API key for free without a credit card. Our free plan includes up to 3000 geocoding requests/day. For more information on our plans, visit the Pricing page.

How to get Geocoding 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 "Geocoding 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 Specification

The Geocoder API accepts both structured and free-form addresses as an input and returns JSON, GeoJSON, and XML objects as a response. In addition, you can specify location filters and preferred geographical areas to make the address search more accurate and focused.

Request URL


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


Here are Geocoding URL examples (click on a URL to test the API):

  • Simple address search (11 Av. de la Bourdonnais, 75007 Paris, France):

https://api.geoapify.com/v1/geocode/search?text=11%20Av.%20de%20la%20Bourdonnais%2C%2075007%20Paris%2C%20France&format=json&apiKey=YOUR_API_KEY

  • Search by structured address (Teatro Nuevo Apolo, Plaza de Tirso de Molina, 1, 28012 Madrid):

https://api.geoapify.com/v1/geocode/search?name=Teatro%20Nuevo%20Apolo&housenumber=1&street=%20Plaza%20de%20Tirso%20de%20Molina&postcode=28012&city=Madrid&format=json&apiKey=YOUR_API_KEY

  • Search nearby (Hannoverstr. near Nordhorn, Germany [lat: 52.4309185, lon: 7.0652029]):

https://api.geoapify.com/v1/geocode/search?text=Hannoverstr.&bias=proximity:7.0652029,52.4309185&format=json&apiKey=YOUR_API_KEY

Request parameters

Name Format Description Example
apiKey Required parameter for API key apiKey=c3da27885e3573e09e550d044bc55e22
text Free-form address Address to search. Use 'text' parameter or structured address parameters. text=38%20Upper%20Montagu%20Street%2C%20Westminster%20W1H%201LJ%2C%20United%20Kingdom
name Structured address Amenity or place name. Structured address parameters are an alternative to the 'text' parameter. name=Marin%20General%20Hospita
housenumber Structured address House number. Structured address parameters are an alternative to the 'text' parameter. housenumber=250
street Structured address Street name. Structured address parameters are an alternative to the 'text' parameter. street=Bon%20Air%20Road
postcode Structured address Postcode. Structured address parameters are an alternative to the 'text' parameter. postcode=94904
city Structured address City name. Structured address parameters are an alternative to the 'text' parameter. city=Larkspur
state Structured address State name. Structured address parameters are an alternative to the 'text' parameter. state=CA
country Structured address Country name. Structured address parameters are an alternative to the 'text' parameter. country=United%20States%20of%20America
type Location type: 'country', 'state', 'city', 'postcode', 'street', 'amenity'. type=amenity
lang Result language. 2-character ISO 639-1 language codes are supported. lang=fr
limit Maximal number of results. By default is 5 limit=10
filter Location Filters Filter places by country, boundary, circle. See the Location Filters, for more details. filter=rect:-122.569140,37.936672,-122.5324795,37.9588474
bias Location Bias Prefer places by country, boundary, circle, location. See the Location Bias, for more details. bias=proximity:-122.52985959,37.95335060
format Response object type: 'json', 'xml', or 'geojson' (default). format=json

Location Filters

You can search using the following geolocation filters to make the results even more relevant:

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.

Location Bias

You can use bias to prioritize results by proximity to the specified point, radius, bounding box, or country. For example, this can be useful when searching nearby or showing possible addresses in the view box first, but you don't want to restrict the search.

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 biases. For example, "bias=proximity:41.225714,52.971411|countrycode:de" will search places near the location, in the country, 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 search there first. Set bias to "countrycode:none" to avoid prioritization by country.

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

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, etc.

Here is a geocoding JSON object example:

{
   "results":[
      {
         "datasource":{
            "sourcename":"openstreetmap",
            "attribution":"© OpenStreetMap contributors",
            "license":"Open Database License",
            "url":"https://www.openstreetmap.org/copyright"
         },
         "housenumber":"1313",
         "street":"Broadway",
         "suburb":"G Street Neighborhood",
         "city":"Tacoma",
         "county":"Pierce County",
         "state":"Washington",
         "postcode":"98402",
         "country":"United States of America",
         "country_code":"us",
         "lon":-122.43941302945888,
         "lat":47.25094496732003,
         "formatted":"1313 Broadway, Tacoma, WA 98402, United States of America",
         "address_line1":"1313 Broadway",
         "address_line2":"Tacoma, WA 98402, United States of America",
         "state_code":"WA",
         "result_type":"building",
         "rank":{
            "importance":0.7210000000000001,
            "popularity":3.7125010705059402,
            "confidence":1,
            "confidence_city_level":1,
            "confidence_street_level":1,
            "match_type":"full_match"
         },
         "place_id":"5194bdd3571f9c5ec0591fdef5f61ea04740f00102f90188669f1000000000c00203"
      }
   ],
   "query":{
      "text":"1313 Broadway, Tacoma, WA 98402, United States of America",
      "parsed":{
         "housenumber":"1313",
         "street":"broadway",
         "postcode":"98402",
         "city":"tacoma",
         "state":"wa",
         "country":"united states of america",
         "expected_type":"building"
      }
   }
}

Geocode addresses

Geoapify Geocoding API helps you convert addresses into coordinates. It’s flexible and powerful, it returns confidence levels to help make decisions about the result correctness.

We've created a few examples to help you figure out how Geocode can be applied to your business.

Search addresses by free-form or structured address

You can geocode addresses by a free-form address string or by structured address aka separate address components like street, postcode, city, etc.

  • A free-form address geocoding URL (1214-1224 West Van Buren Street, Chicago, IL 60607, United States of America):
https://api.geoapify.com/v1/geocode/search?text=1214-1224%20West%20Van%20Buren%20Street%2C%20Chicago%2C%20IL%2060607%2C%20United%20States%20of%20America&lang=en&limit=5&format=json&apiKey=YOUR_API_KEY

Try to geocode a free-form address

  • A structured address geocoding URL for the same address (1214-1224 West Van Buren Street, Chicago, IL 60607, United States of America):
https://api.geoapify.com/v1/geocode/search?housenumber=1214-1224&street=West%20Van%20Buren%20Street&postcode=60607&city=Chicago&country=United%20States%20of%20America&lang=en&limit=5&format=json&apiKey=YOUR_API_KEY

Try to geocode a free-form address

Please consider that when you send a free-form address, the resulting quality is directly dependent on input values quality. Therefore, we highly recommend you clean up address strings from rubbish characters and non-address-related text.

Search addresses in a country

Our geocoding works worldwide, so by default you can just send a string and get corresponding addresses. Nevertheless, we recommend setting a country filter if all the addresses are located in the same country.

This can be particularly important then addresses do not contain country information. For example, the address "Main St., Berlin" can be mapped to Berlin in Germany, as well as to Berlin in the USA. You need to specify the country filter to search in the USA only:

https://api.geoapify.com/v1/geocode/search?text=Main%20St.%2C%20Berlin&filter=countrycode:us&apiKey=YOUR_API_KEY

Try to geocode with a country filter

Set a language to localize addresses

You can localize address results by setting a language parameter. For example, here is the Russian version of the address (Wolbrantskerkweg 103, 1069 CL Amsterdam, Netherlands):

https://api.geoapify.com/v1/geocode/search?text=Wolbrantskerkweg%20103%2C%201069%20CL%20Amsterdam%2C%20Netherlands&lang=ru&limit=5&apiKey=YOUR_API_KEY

Try to geocode with a country filter

Geocode cities

Use Foursquare to search for cities, towns, and villages or even find latitude and longitude coordinates or a neighborhood name.

Set type=city to lookup cities

By default, the geocoder tries to return the more relevant result when you search for a place. Use the type=city parameter value to filter your results down to cities, towns, villages, etc.

Here is a search for the Berlin city:

https://api.geoapify.com/v1/geocode/search?text=Berlin&lang=en&limit=10&type=city&apiKey=YOUR_API_KEY

Try to geocode with a country filter

Note that the result contains 10 Berlin cities in different parts of the world. However, they are sorted by popularity, such as Berlin (Germany) in the first position.

Location filters to make cities search more precise

You can narrow your search to a specific country or even geographical area. For example, you can search only for cities in Germany using this geocoder request (Waldkirchen):

https://api.geoapify.com/v1/geocode/search?text=Waldkirchen&lang=en&limit=10&type=city&filter=countrycode:de&apiKey=YOUR_API_KEY

Try to geocode with a country filter

You can get sorted cities by the proximity to the bias location. When you provide the bias parameter, the result also contains a distance in meters between found location and bias:

https://api.geoapify.com/v1/geocode/search?text=Waldkirchen&lang=en&limit=5&type=city&filter=countrycode:de&bias=proximity:13.1934588,48.633274&apiKey=YOUR_API_KEY

Try to geocode with a country filter

Geocode ZIP codes (or postcodes)

Whether you’re looking for a specific address or a ZIP code lookup api, we make it easy to find the information you need. Set the type parameter to "postcode" to geocode zip codes and postcodes.

Converting ZIP to lat long with api

Get lat and long coordinates for a ZIP code:

https://api.geoapify.com/v1/geocode/search?text=B27&lang=en&limit=10&type=postcode&filter=countrycode:gb&apiKey=YOUR_API_KEY

Try to geocode with a country filter

Note that ZIP codes are unique within a country only. Therefore, we strongly recommend you specify a country filter to get the correct latitude/longitude coordinates for the given ZIP code.

Get a list of ZIP codes starting with

Get postcodes starting with "864" near Augsburg, Germany [lon: 10.898337, lat: 48.365755]:

https://api.geoapify.com/v1/geocode/search?text=864&lang=en&limit=10&type=postcode&filter=countrycode:de&bias=proximity:10.898337637235045,48.365755557934364&apiKey=YOUR_API_KEY

Try to geocode with a country filter

Geocoding API examples

Our API is easy to use, as it works via HTTP Get protocol. All you need to do to call our API is generate a URL and run HTTP Get request.

Here you will find geocode examples demonstrating how to integrate the API into your JavaScript, Python, or Java application using a simple HTTP request.

Geocoding API JavaScript example

Simply use the fetch() method to call Geocoding in JavaScript browser applications or in the Frontend part of your projects.

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));

The fetch() returns a promise that is resolved when the geocoder does its part of the job, then ​response.json() will parse geocoding results into a JSON or GeoJSON object.

Call geocoder with NodeJS (with node-fetch)

You can easily call GET requests with the node-fetch module. Node-fetch is a node.js server side toolkit for the Fetch API. It allows you to make http requests from node.js applications, just as if it was a browser request.

  1. Install node-fetch package with:S
npm i node-fetch
  1. Call Gecooding API:
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));

Geocoding Python

Here is another script to geocode addresses and print the result. This time with 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=d548c5ed24604be6a9dd0d989631f783"

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

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

print(resp.status_code)
print(resp.json())

Geocoding API java example

Java has many ways to send an HTTP GET request. In this example, we show you how to call Geocoding with Java 9’s HttpClient, HttpRequest, and HttpResponse.

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());

You can send both synchronous and asynchronous geocoding requests with HTTPClient.

Working with geocoding confidence

Our geocoding API returns 3 levels of confidence, giving you the information you need to make an informed decision:

  • confidence - indicates if the complete address is correct;
  • confidence_street_level - indicates if the street is correct;
  • confidence_city_level - indicates if the city is correct.

Please note that when the result has low confidence, it doesn't mean that it's incorrect, but it means that we doubt whether it indeed corresponds to the input address.

For example, you can receive the correct addresses with low confidence if some non-common abbreviations are used, or the original address has a misspelling.

Here is an example of how you can process the confidence values:

const ACCEPT_LEVEL = 0.95;
const DECLINE_LEVEL = 0.2;

const validationResult = {};

 return fetch(url).then(response => response.json())
  .then(result => {

    if (results.length === 0) {
      validationResult.validation = 'NOT_CONFIRMED';
      return validationResult;
    }

    const address = results[0];

    if (address.rank.confidence >= ACCEPT_LEVEL) {
      validationResult.validation = 'CONFIRMED';
    } else if (address.rank.confidence < DECLINE_LEVEL) {
      validationResult.validation = 'NOT_CONFIRMED';
    } else {
      validationResult.validation = 'PARTIALLY_CONFIRMED';
      if (address.rank.confidence_street_level >= ACCEPT_LEVEL) {
        validationResult.validation_details = 'BUILDING_NOT_FOUND';
      } else if (address.rank.confidence_city_level >= ACCEPT_LEVEL) {
        validationResult.validation_details = 'STREET_LEVEL_DOUBTS';
      } else {
        validationResult.validation_details = 'CITY_LEVEL_DOUBTS';
      }
    }

    return validationResult;
  })
  .catch(error => console.log('error', error));