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:

• Authentication and Geocoding API key
• API reference
• Geocode addresses
• Geocode cities
• Geocode ZIP codes (postcodes)
• Code samples (JS, NodeJS, Python, Java)
• Pricing

Authentication 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 reference

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

Location Filters

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

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.

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:

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"
         },
         "timezone": {
            "name": "America/Los_Angeles",
            "offset_STD": "-08:00",
            "offset_STD_seconds": -28800,
            "offset_DST": "-07:00",
            "offset_DST_seconds": -25200,
            "abbreviation_STD": "PST",
            "abbreviation_DST": "PDT"
         },
         "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

• 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

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

Search for a street address within a city

You can use a place ID received by another API call (Geocoding API, Autocomplete API, Boundary API, Places API) as a filter when you search for a street address. For example, this allows getting streets within a city.

This example shows how to find the "via Cappuccio" in Milan:

https://api.geoapify.com/v1/geocode/search?text=via%20Cappuccio&format=json&filter=place:514d614ac91761224059acbe04b86abb4640f00101f90173af000000000000c00208&apiKey=YOUR_API_KEY

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

Geocode cities

Use the "type=city" parameter 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

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

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

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

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

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

2. 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.
• confidence_building_level - indicates if the building position 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_building_level === 0) {
        validationResult.validation_details.building = 'BUILDING_NOT_FOUND';
      } else if (address.rank.confidence_building_level >= ACCEPT_LEVEL) {
        validationResult.validation_details.building = 'BUILDING_POSITION_DOUBTS';
      }

      if (address.rank.confidence_street_level >= ACCEPT_LEVEL) {
        validationResult.validation_details.street = 'STREET_LEVEL_DOUBTS';
      }

      if (address.rank.confidence_city_level >= ACCEPT_LEVEL) {
        validationResult.validation_details.city = 'CITY_LEVEL_DOUBTS';
      }
    }

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

You can set different ACCEPT_LEVEL and DECLINE_LEVEL values for buildings, cities, and streets depending on the precision required for each level. For example:

• Building confidence may require a higher threshold (stricter ACCEPT_LEVEL) since accurate building identification is critical.
• Street confidence could have a slightly lower threshold, as it may not need to be as strict as the building level.
• City confidence might tolerate an even lower threshold, especially if larger regions are acceptable.

By adjusting these levels independently, you can tailor the validation process based on the specific needs of the application or service.

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:

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