Documentation

Reference documentation for integrating Map Zena geo APIs. All endpoints return JSON. Use anonymous mode for free usage, then API keys for metered usage.

Map Zena API Overview

Map Zena is a REST API for maps and location data. All requests use HTTPS, and all responses are UTF-8 JSON. You can call endpoints anonymously for free, then switch to an API key for paid usage.

Available APIs

Geocoding

Convert addresses, place names, and postal codes into lat/lon coordinates with full admin hierarchy.

GET /v1/geocode

Reverse Geocoding

Turn lat/lon coordinates into readable addresses with structured address fields.

GET /v1/reverse

Timezone

Timezone ID, UTC offset, DST status, and local datetime for any geographic coordinate.

GET /v1/timezone

Elevation

Terrain and bathymetry values in metres or feet for any point on Earth using SRTM15+.

GET /v1/elevation

IP Lookup

Geolocate any IPv4 or IPv6 address. Returns country, city, ASN, proxy/VPN/Tor detection, and currency.

GET /v1/ip

Hosted Maps

XYZ raster tile endpoints in streets, satellite, and terrain styles. Static map image generation also available.

tiles/{z}/{x}/{y}.png GET /v1/staticmap

Authentication

Requests can be made without a key in anonymous mode (up to 500 requests/day), or with a key for usage above the free allowance.

Anonymous request

http

GET https://api.mapzena.com/v1/geocode?q=Paris

Query parameter

http

GET https://api.mapzena.com/v1/geocode?q=Paris&key=mz_live_xxxxxxxxxxxxxxxx

HTTP header

http

GET https://api.mapzena.com/v1/geocode?q=Paris
X-Api-Key: mz_live_xxxxxxxxxxxxxxxx

If you use keys, keep them secret. Never expose API keys in client-side JavaScript, mobile app binaries, or public repositories. Use server-side proxying if you need to call the API from a browser.

Rate limits

Map Zena has one free allowance and one metered overage model:

Mode	Daily usage	Burst (per second)
Anonymous (no key)	500 free requests/day	2 req/s
Registered key	Metered at $0.50 / 1,000 queries	30 req/s default

Rate limit headers are returned on every response:

response headers

X-RateLimit-Limit:     500
    X-RateLimit-Remaining: 287
X-RateLimit-Reset:     1745107200

Error codes

All errors return a JSON body with a status field of error and an error object containing code and message.

json - error response

{
  "status": "error",
  "error": {
    "code":    "rate_limit_exceeded",
    "message": "Daily request quota exhausted. Resets at 00:00 UTC."
  }
}

HTTP	Error code	Description
400	invalid_request	Missing or malformed required parameters.
401	unauthorized	API key missing or invalid.
402	insufficient_credit	API key has insufficient account credit for overage usage.
404	not_found	No results found for the given query or coordinates.
429	anonymous_quota_exceeded	Free anonymous daily quota exhausted.
429	rate_limit_exceeded	Per-second rate limit hit.
500	internal_error	Unexpected server error. Retry with exponential backoff.
503	service_unavailable	Temporary maintenance. Check status page.

Enrichment fields

Add enrich=1 to any geocoding or reverse-geocoding request to include a country_data and optionally an admin_data object in the response. Enrichment counts as one additional request unit.

Available enrichment fields:

population, population_urban, population_rural
gdp_bn_usd, gdp_per_capita, gdp_ppp_bn
area_km2, area_land_km2, area_water_km2
currency, currency_name
languages (array of BCP-47 codes)
calling_code, tld
hdi, life_expect, median_age
internet_users_pct
capital, government_type
neighbours (array of ISO2 codes)
climate.jan_avg_c … climate.dec_avg_c
climate.jan_rain_mm … climate.dec_rain_mm

Data coverage

Map Zena provides global coverage with the following approximate record counts:

Countries & territories: 250+
Admin level 1 regions (states, provinces): 4,500+
Admin level 2 regions (counties, districts): 47,000+
Populated places: 5,000,000+
Total geocodable records: 200,000,000+
Elevation: SRTM15+ with variable effective resolution and interpolation
IP geolocation: Covers IPv4 and IPv6 space globally

Data is updated on a rolling basis. Country-level enrichment data is reviewed quarterly. Geocoding data follows the OpenStreetMap update cadence.