Reverse Geocoding

https://api.geocode.earth/v1/reverse

The reverse geocoding endpoint takes latitude and longitude coordinates and returns information about what is at the specified location.

There are two main ways to use our reverse geocoding endpoint:

Fine reverse geocoding #

Usually referred to as simply reverse geocoding, fine reverse geocoding returns the address or point of interest at a given latitude and longitude coordinate.

To perform reverse geocoding on a given point, specify the point.lat and point.lon parameters.

For example, a query for the latitude/longitude coordinate -22.9519173, -43.2104950 returns the famous Cristo Redentor statue in Rio de Janeiro.

Shell Ruby Node.js Python
api_key='<YOUR API KEY>'

curl --get https://api.geocode.earth/v1/reverse \
  -d api_key=$api_key \
  -d point.lat=-22.9519173 \
  -d point.lon=-43.210495

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/reverse?"\
        "api_key=#{api_key}&"\
        "point.lat=-22.9519173&" \
        "point.lon=-43.2104950"
http_response = Net::HTTP.get_response(URI(query))
response = JSON.parse(http_response.body)

puts response # print the entire response

puts response['features'][0]['properties']['name']      # Christ the Redeemer
puts response['features'][0]['properties']['label']     # Christ the Redeemer, Rio de Janeiro, Brazil
puts response['features'][0]['geometry']['coordinates'] # [ -43.210495, -22.951917 ]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/reverse?' +
              `api_key=${api_key}&` +
              'point.lat=-22.9519173&' +
              'point.lon=-43.2104950'

const req = https.get(query, (res) => {
  let body = '';
  res.on('data', data => { body += data; });

  res.on('end', () => {
    const response = JSON.parse(body);
    console.log(response); // print the entire response

    console.log(response['features'][0]['properties']['name']);      // Christ the Redeemer
    console.log(response['features'][0]['properties']['label']);     // Christ the Redeemer, Rio de Janeiro, Brazil
    console.log(response['features'][0]['geometry']['coordinates']); // [ -43.210495, -22.951917 ]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/reverse?" \
        "api_key="+api_key+"&"\
        "point.lat=-22.9519173&" \
        "point.lon=-43.2104950"

response = json.load(urllib.request.urlopen(query))

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # Christ the Redeemer
print(response['features'][0]['properties']['label'])     # Christ the Redeemer, Rio de Janeiro, Brazil
print(response['features'][0]['geometry']['coordinates']) # [ -43.210495, -22.951917 ]

If there’s no address, point of interest, or street near (within 1km) of the provided coordinates, reverse geocoding automatically falls back to coarse reverse geocoding.

Coarse reverse geocoding #

Also known as point in polygon lookup, coarse reverse geocoding answers the question “What is this location contained within?”. The answer will generally be a city, state or other administrative area.

Coarse reverse geocoding requires the point.lat and point.lon parameters, as well as the layers parameter.

Use layers=coarse to support any type of coarse result, or any other combination of administrative layers, such as layers=locality,region,country.

For example, performing coarse reverse geocoding for the coordinate 21.028430, 105.848637 returns the city of Hanoi, Vietnam.

Shell Ruby Node.js Python
api_key='<YOUR API KEY>'

curl --get https://api.geocode.earth/v1/reverse \
  -d api_key=$api_key \
  -d layers=coarse \
  -d point.lat=21.02843 \
  -d point.lon=105.848637

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/reverse?"\
        "api_key=#{api_key}&" \
        "layers=coarse&" \
        "point.lat=21.02843&" \
        "point.lon=105.848637"
http_response = Net::HTTP.get_response(URI(query))
response = JSON.parse(http_response.body)

puts response # print the entire response

puts response['features'][0]['properties']['name']      # Hanoi
puts response['features'][0]['properties']['label']     # Hanoi, Vietnam
puts response['features'][0]['geometry']['coordinates'] # [ 105.834004, 21.018587 ]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/reverse?' +
              `api_key=${api_key}&` +
              'layers=coarse&' +
              'point.lat=21.02843&' +
              'point.lon=105.848637'

const req = https.get(query, (res) => {
  let body = '';
  res.on('data', data => { body += data; });

  res.on('end', () => {
    const response = JSON.parse(body);
    console.log(response); // print the entire response

    console.log(response['features'][0]['properties']['name']);      // Hanoi
    console.log(response['features'][0]['properties']['label']);     // Hanoi, Vietnam
    console.log(response['features'][0]['geometry']['coordinates']); // [ 105.834004, 21.018587 ]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/reverse?" \
        "api_key="+api_key+"&"\
        "layers=coarse&"\
        "point.lat=21.02843&" \
        "point.lon=105.848637"

response = json.load(urllib.request.urlopen(query))

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # Hanoi
print(response['features'][0]['properties']['label'])     # Hanoi, Vietnam
print(response['features'][0]['geometry']['coordinates']) # [ 105.834004, 21.018587 ]