Geocoding API

Convert addresses, place names, postal codes, and landmarks into precise latitude/longitude coordinates with full administrative hierarchy and optional demographic enrichment.

Geocoding API

The Geocoding API converts a free-text query - an address, city name, postal code, or any combination - into one or more geographic coordinates. Each result includes an address breakdown, bounding box, and importance score. Add enrich=1 for full country and city-level demographic data.

Endpoint

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

Parameters

Parameter	Type	Required	Description
`key`	string	optional	Optional in free mode. Use a key (or `X-Api-Key`) for metered usage above the free allowance.
`q`	string	required	The search query. Free-form address, place name, or postal code. URL-encode spaces as `+` or `%20`.
`limit`	integer	optional	Maximum number of results to return. Default: `5`. Max: `20`.
`country`	string	optional	Restrict results to a specific country. Accepts ISO 3166-1 alpha-2 code (e.g. `DE`, `US`).
`lang`	string	optional	Preferred language for place names. BCP-47 code (e.g. `en`, `fr`, `de`). Falls back to English.
`enrich`	0 or 1	optional	Set to `1` to include `country_data` with population, GDP, and climate fields. Counts as 1 extra request unit.
`format`	string	optional	Response format. Only `json` is currently supported (default).

Example request

bash - curl

curl "https://api.mapzena.com/v1/geocode?q=Paris,France&limit=1&enrich=1&key=YOUR_KEY"

Example response

json

{
  "status": "ok",
  "query": "Paris, France",
  "count": 1,
  "results": [
    {
      "place_id":      "mz_c3f2a19d",
      "display_name": "Paris, Île-de-France, France",
      "lat":           48.8566,
      "lon":           2.3522,
      "type":          "city",
      "importance":    0.98,
      "address": {
        "city":         "Paris",
        "county":       "Arrondissements de Paris",
        "state":        "Île-de-France",
        "country":      "France",
        "country_code": "FR",
        "postcode":     "75000"
      },
      "boundingbox": [48.8156, 48.9022, 2.2242, 2.4699],
      "country_data": {
        "name":          "France",
        "iso2":          "FR",
        "iso3":          "FRA",
        "capital":       "Paris",
        "population":    67750000,
        "gdp_bn_usd":    2780.1,
        "gdp_per_capita": 41030,
        "currency":      "EUR",
        "languages":     ["fr"],
        "hdi":           0.903,
        "climate": {
          "jan_avg_c":   5.5,
          "jul_avg_c":   25.2,
          "ann_rain_mm": 637
        }
      }
    }
  ]
}

Result types

The type field classifies the matched place:

Type	Description
`country`	Sovereign state or territory
`state`	Admin level 1 (state, province, region)
`county`	Admin level 2 (county, district)
`city`	City or municipality
`suburb`	Neighbourhood or suburb within a city
`postcode`	Postal code area
`road`	Named road or street
`poi`	Point of interest (building, landmark)

Error codes

HTTP	Code	Description
400	missing_query	The `q` parameter is absent or empty.
400	invalid_country	The `country` parameter is not a valid ISO 3166-1 alpha-2 code.
404	not_found	No places matched the query.
429	rate_limit_exceeded	Daily quota or per-second burst limit reached.

Code examples

PHP

php

<?php
$key  = 'YOUR_KEY';
$q    = urlencode('Paris, France');
$url  = "https://api.mapzena.com/v1/geocode?q={$q}&enrich=1&key={$key}";

$resp = json_decode(file_get_contents($url), true);

if ($resp['status'] === 'ok') {
    $r = $resp['results'][0];
    echo $r['lat'] . ', ' . $r['lon'];
}

Python

python

import urllib.request, json

key  = "YOUR_KEY"
q    = "Paris, France"
url  = f"https://api.mapzena.com/v1/geocode?q={q}&enrich=1&key={key}"

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

result = data["results"][0]
print(result["lat"], result["lon"])