Reverse Geocoding API

Convert latitude/longitude coordinates into a readable address, from country level down to street level, with optional country enrichment.

Reverse Geocoding API

The Reverse Geocoding API accepts a latitude and longitude and returns the best-matching address for that point on Earth. Responses include a structured address object with each administrative level named separately, making it easy to extract exactly the component you need.

Endpoint

GET https://api.mapzena.com/v1/reverse

Parameters

Parameter	Type	Required	Description
`key`	string	optional	Optional in free mode. Required for metered usage above the free allowance.
`lat`	float	required	Latitude in decimal degrees. Range: `-90` to `90`.
`lon`	float	required	Longitude in decimal degrees. Range: `-180` to `180`.
`zoom`	integer	optional	Controls the detail level of the result. `3`=country, `8`=state, `10`=city, `14`=suburb, `18`=building. Default: `18`.
`lang`	string	optional	Preferred language for place names. BCP-47 code. Default: `en`.
`enrich`	0 or 1	optional	Include full `country_data` enrichment. Counts as 1 extra request unit.

Example request

bash - curl

curl "https://api.mapzena.com/v1/reverse?lat=48.8566&lon=2.3522&enrich=1&key=YOUR_KEY"

Example response

json

{
  "status":       "ok",
  "lat":          48.8566,
  "lon":          2.3522,
  "display_name": "Palais du Louvre, Rue de Rivoli, 1st Arrondissement, Paris, Île-de-France, France",
  "address": {
    "building":      "Palais du Louvre",
    "road":          "Rue de Rivoli",
    "neighbourhood": "1st Arrondissement",
    "suburb":        "1st Arrondissement",
    "city":          "Paris",
    "county":        "Arrondissements de Paris",
    "state":         "Île-de-France",
    "postcode":      "75001",
    "country":       "France",
    "country_code":  "FR"
  },
  "country_data": {
    "name":          "France",
    "iso2":          "FR",
    "iso3":          "FRA",
    "capital":       "Paris",
    "population":    67750000,
    "gdp_bn_usd":    2780.1,
    "gdp_per_capita": 41030,
    "area_km2":      551695,
    "currency":      "EUR",
    "languages":     ["fr"],
    "calling_code":  "+33",
    "tld":           ".fr",
    "hdi":           0.903,
    "life_expect":   82.5,
    "neighbours":   ["ES", "IT", "CH", "DE", "LU", "BE"]
  }
}

Address fields

Not all fields are present for every location - availability depends on data density for that area. All available fields are always included; absent fields are omitted (never null).

Field	Description
`building`	Named building or venue
`house_number`	House or unit number
`road`	Street or road name
`neighbourhood`	Neighbourhood or quarter
`suburb`	Suburb or borough
`city`	City or town
`town`	Town (smaller than city)
`village`	Village
`county`	County or district
`state`	State, province, or region
`state_code`	ISO 3166-2 state/province code
`postcode`	Postal or ZIP code
`country`	Country name
`country_code`	ISO 3166-1 alpha-2 code

Error codes

HTTP	Code	Description
400	missing_coordinates	`lat` or `lon` parameter missing.
400	invalid_coordinates	Coordinates out of valid range.
404	not_found	No address data available for this location.
429	rate_limit_exceeded	Quota reached.

Code examples

PHP

php

<?php
$key = 'YOUR_KEY';
$lat = 48.8566;
$lon = 2.3522;
$url = "https://api.mapzena.com/v1/reverse?lat={$lat}&lon={$lon}&key={$key}";

$data = json_decode(file_get_contents($url), true);
echo $data['display_name'];

Python

python

import urllib.request, json

key = "YOUR_KEY"
url = f"https://api.mapzena.com/v1/reverse?lat=48.8566&lon=2.3522&key={key}"

with urllib.request.urlopen(url) as r:
    data = json.load(r)

print(data["display_name"])