Reverse Geocoding Documentation

Reverse Geocoding API returns a location with an address by Lon/Lat coordinates. It's widely used to define user location by GPS coordinates or find a building address on a map, for example, by user click.

Example of Geocoding API request URL


https://api.geoapify.com/v1/geocode/reverse?lat=49.332184526818025&lon=11.27818147303799&lang=de&limit=10&apiKey=YOUR_API_KEY


Required parameters:

  • lat and lon - coordinates of the place

Optional parameters:

  • lang - language for results
  • limit - the maximum amount of returned results

The returned result contains a GeoJSON FeatureCollection object.

Try the Reverse 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 "Reverse 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

Similar to the Forward Geocoding API, the Reverse Geocoding API works via HTTP GET requests and returns a result in JSON format. The code samples of the Forward Geocoding API can help to implement an API call with different languages.

Lets have a look how to get a building address when a user clicks on a map:

Get a building address on a Leaflet map click

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`, requestOptions)
  .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);

MapLibre GL: Get a building address on map click

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.features[0].geometry.coordinates.slice();
  var description = e.features[0].properties.description;

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

API Specification


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


Request parameters

Name Description
apiKey Required parameter for API key
lat, lon A location coordinates
limit Maximal number of results. By default is 1
lang Result language. 2-character ISO 639-1 language codes are supported.

Response Object

The response returned contains a GeoJSON FeatureCollection object, where each feature has a "Point" type. The feature properties format is the same as for Geocoding API:

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

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.