Reverse Geocoding API

Reverse Geocoding is useful when you have a certain set of coordinates and want to find out the corresponding address. For example, if you need to know your customer’s address by GPS coordinates or get an address of a building a user has clicked on.

Geoapify provides a powerful and easy-to-use Reverse Geocoding API. We return you a well-formed complete address and its parts, like city, postcode, and street, for the latitude/longitude coordinates.

Try the Reverse Geocoding API in the API Playground:

Reverse Geocoding Live Demo



Authenfication 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 Reverse 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 "Reverse 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

Reverse Geocoding API works via HTTP Get request. It accepts the latitude/longitude coordinates pair and returns the corresponding address. Optionally pass the type parameter to define address level to search: city, postcode, country, etc.

Request URL


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


Here are some examples of Reverse Geocoding URLs to try out:

  • Simple lat/long to address example ("52.47944744483806, 13.213967739855434"):

https://api.geoapify.com/v1/geocode/reverse?lat=52.47944744483806&lon=13.213967739855434&format=json&apiKey=YOUR_API_KEY

  • Get postcode by lat/long ("52.55795596809756, 13.47437607244808"):

https://api.geoapify.com/v1/geocode/reverse?lat=52.55795596809756&lon=13.47437607244808&type=postcode&format=json&apiKey=YOUR_API_KEY

Request parameters

Name Description
apiKey Required API key parameter
lat, lon A location coordinates
limit Maximal number of results. By default is 1
type Location type. Possible values: 'country', 'state', 'city', 'postcode', 'street', 'amenity'.
lang Result language. 2-character ISO 639-1 language codes are supported.
format Response object type: 'json', 'xml', or 'geojson' (default).

Response Object

The response returned contains a GeoJSON FeatureCollection, JSON, or XML object. Each address contains 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 the given coordinates
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 and so on.

Code samples

We made Reverse Geocoding Examples for you to help you get started with the API:

Reverse Geocoding Javascript

Calling the API is simple. Just make an HTTP request with either the fetch() function in JavaScript or using the node-fetch library in NodeJS. The following example shows just a few parameters that are available to be sent with the location information:

  fetch(`https://api.geoapify.com/v1/geocode/reverse?lat=${lat}&lon=${lon}&apiKey=YOUR_API_KEY`)
  .then(response => response.json())
  .then(result => {
    if (result.features.length) {
      console.log(result.features[0].properties.formatted);
    } else {
      console.log("No address found");
    }
  });

Get a building address on a Leaflet map click

If you want to get a building address a user clicked on, you need to add a click event to the map and call the Reverse Geocoding API when it happens.

Let's add a Popup element with the address for this location:

const mymap = L.map('mapid').setView([51.213826, 4.453636], 16);
...

function onMapClick(e) {
  // user clicked on a map
  fetch(`https://api.geoapify.com/v1/geocode/reverse?lat=${e.latlng.lat}&lon=${e.latlng.lng}&apiKey=YOUR_API_KEY`)
  .then(response => response.json())
  .then(result => {
    if (result.features.length) {
      const address = result.features[0].properties.formatted;
      L.popup().setLatLng(e.latlng).setContent(address).openOn(mymap);
    } else {
      L.popup().setLatLng(e.latlng).setContent("No address found").openOn(mymap);
    }
  });
}

mymap.on('click', onMapClick);

Get a building address on a MapLibre GL map click

You can query an address on a MapLibre map click similar to Leaflet map way:

import { Map } from "maplibre-gl";

const map = new Map({
  container: "my-map",
  style: `https://maps.geoapify.com/v1/styles/klokantech-basic/style.json?apiKey=YOUR_API_KEY`,
});

map.on("click", "places", function (e) {
  var coordinates = [e.lngLat.lng, e.lngLat.lat];

  // on small zoom levels it could happen that a location is present multiple times on the map
  while (Math.abs(e.lngLat.lng - coordinates[0]) > 180) {
    coordinates[0] += e.lngLat.lng > coordinates[0] ? 360 : -360;
  }

  fetch(`https://api.geoapify.com/v1/geocode/reverse?lat=${coordinates[1]}&lon=${coordinates[0]}&apiKey=YOUR_API_KEY`, requestOptions)
  .then(response => response.json())
  .then(result => {
    if (result.features.length) {
      const address = result.features[0].properties.formatted;
      new mapboxgl.Popup().setLngLat(coordinates).setHTML(address).addTo(map);
    } else {
      new mapboxgl.Popup().setLngLat(coordinates).setHTML("No address found").addTo(map);
    }
  });
});