GET /v1/reverse

Overview

Reverse geocoding converts geographic coordinates (latitude, longitude) into a human-readable address. Unlike /v1/geocode which returns an array of results, this endpoint returns a single best-match result.

Request

GET https://api.geocodeme.net/v1/reverse

Required header: X-Api-Key: gm_YOUR_API_KEY

Parameters

Parameter	Type	Required	Default	Description
lat	float	Yes	n/a	Latitude of the location (-90 to 90)
lon	float	Yes	n/a	Longitude of the location (-180 to 180)
zoom	integer	No	18 (building)	Level of address detail (3 to 18). Defaults to building-level precision; see zoom levels below
addressdetails	integer	No	1	Include structured address breakdown in the response (1 = yes, 0 = no)
format	string	No	json	Response format: json or geojson

Zoom Levels

The zoom parameter controls the granularity of the returned address:

Zoom	Granularity
3	Country
5	State / Region
8	County
10	City
14	Neighbourhood
16	Street
18	Building (default)

For example, the coordinates 48.8566, 2.3522 (central Paris) return different results at each zoom level:

• zoom=3 (Country) → "France"
• zoom=5 (State) → "Île-de-France, France"
• zoom=10 (City) → "Paris, Île-de-France, France"
• zoom=14 (Neighbourhood) → "4e Arrondissement, Paris, Île-de-France, 75004, France"
• zoom=18 (Building) → "3, Rue de Rivoli, 4e Arrondissement, Paris, Île-de-France, 75004, France"

tip

Use zoom=18 (default) for precise building-level results. Use lower zoom values for administrative boundaries.

Code Examples

cURL

curl -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/reverse?lat=48.8566&lon=2.3522"

Python

import os
import requests

api_key = os.environ["GEOCODEME_API_KEY"]

response = requests.get(
    "https://api.geocodeme.net/v1/reverse",
    params={"lat": 48.8566, "lon": 2.3522},
    headers={"X-Api-Key": api_key},
)
response.raise_for_status()

data = response.json()
print(data["result"]["display_name"])

JavaScript

const apiKey = process.env.GEOCODEME_API_KEY;

const response = await fetch(
  "https://api.geocodeme.net/v1/reverse?lat=48.8566&lon=2.3522",
  { headers: { "X-Api-Key": apiKey } }
);

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}

const data = await response.json();
console.log(data.result.display_name);

PHP

<?php
$apiKey = getenv('GEOCODEME_API_KEY');

$url = 'https://api.geocodeme.net/v1/reverse?' . http_build_query([
    'lat' => 48.8566,
    'lon' => 2.3522,
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: $apiKey"]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    throw new \RuntimeException("HTTP $httpCode: $response");
}

$data = json_decode($response, true);
echo $data['result']['display_name'] . "\n";

Response

info

All responses include rate limiting headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Monthly-Remaining, etc.).

warning

Unlike /v1/geocode which returns "results" (an array), this endpoint returns "result" (a single object).

JSON Response

{
  "result": {
    "lat": 48.8566,
    "lon": 2.3522,
    "name": null,
    "display_name": "3, Rue de Rivoli, 4e Arrondissement, Paris, Île-de-France, 75004, France",
    "address": {
      "house_number": "3",
      "road": "Rue de Rivoli",
      "city": "Paris",
      "state": "Île-de-France",
      "postcode": "75004",
      "country": "France",
      "country_code": "fr"
    }
  },
  "attribution": "© OpenStreetMap contributors",
  "meta": {
    "took_ms": 28,
    "cache_hit": true
  }
}

GeoJSON Response

When format=geojson:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [2.3522, 48.8566]
  },
  "properties": {
    "name": null,
    "display_name": "3, Rue de Rivoli, 4e Arrondissement, Paris, Île-de-France, 75004, France",
    "address": {
      "house_number": "3",
      "road": "Rue de Rivoli",
      "city": "Paris",
      "state": "Île-de-France",
      "postcode": "75004",
      "country": "France",
      "country_code": "fr"
    }
  },
  "attribution": "© OpenStreetMap contributors",
  "meta": {
    "took_ms": 28,
    "cache_hit": true
  }
}

Schema

Top-level response

Field	Type	Description
result	object | null	A single ReverseResult object, or null when no address is found at the given coordinates
attribution	string	Always "© OpenStreetMap contributors"
meta	object	Request metadata
meta.took_ms	integer	Server processing time in milliseconds
meta.cache_hit	boolean	Whether the response was served from cache

ReverseResult

Field	Type	Description
lat	float	Latitude of the result
lon	float	Longitude of the result
name	string | null	Proper name of the place, from the OpenStreetMap name tag; null when the object has no name. See The name field
display_name	string	Full human-readable address
address	object	Structured address components; may be null

The name field

name is a top-level field carrying the OpenStreetMap name tag of the object found at the given coordinates: "Musée du Louvre", "École élémentaire Jules Ferry", "Boulangerie Chez Momo". It is not an address component and never appears inside address.

{
  "result": {
    "lat": 48.8606,
    "lon": 2.3376,
    "name": "Musée du Louvre",
    "display_name": "Musée du Louvre, Rue de Rivoli, 1er Arrondissement, Paris, Île-de-France, 75001, France"
  }
}

• null when the object has no name tag: the usual case when the coordinates resolve to a plain street or a numbered address. The field is always present, with the JSON value null, never an empty string.
• Use it as the title of what you display, with display_name as the address line underneath; never split display_name on its first comma to obtain a title; on 3, Rue de Rivoli, … that yields 3.

The same field, with the same contract, is returned by /v1/geocode and /v1/autocomplete. With format=geojson it sits in properties, just before display_name.

Address

All fields are optional and depend on the location:

Field	Type	Description
house_number	string	House or building number
road	string	Street name
city	string	City name
town	string	Town name (alternative to city for smaller settlements)
village	string	Village name (alternative to city for rural areas)
county	string	County or district
state	string	State or region
postcode	string	Postal or ZIP code
country	string	Country name
country_code	string	ISO 3166-1 alpha-2 country code (e.g. fr)

Error Responses

The most common errors for this endpoint:

Missing coordinates

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Required parameter 'lat' is missing",
    "field": "lat"
  }
}

Invalid coordinate range

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Parameter 'lat' must be between -90 and 90",
    "field": "lat"
  }
}

For the full error reference, see Error Codes.

info

Cache TTL for /v1/reverse is 24 hours, like /v1/geocode and /v1/autocomplete. Responses for recently queried coordinates are served from the Redis cache; meta.cache_hit tells you which ones.