Documentation menu
geocoding
GET/geocode/reverse
API key required, sent as Authorization: Bearer snk_… or ?api_key=snk_….
Call it
bash
curl -fsS -X GET "https://api.mapmap.ai/geocode/reverse?lon=…&lat=…" \
-H "Authorization: Bearer $MAPMAP_KEY"Parameters
| Name | In | Required | Description |
|---|---|---|---|
| lon | query | yes | Longitude (WGS84), required |
| lat | query | yes | Latitude (WGS84), required |
| kinds | query | no | Restrict hits to these document kinds, comma-separated: address, street, locality, poi, postcode (e.g. kinds=poi for nearest-POI lookups). First-party index only; ignored on the Photon proxy path. |
| categories | query | no | Restrict hits to POIs of these categories, comma-separated; a category browse: the nearest cafés/fuel/parking to the point, nearest first. The index's category vocabulary is the lowercased value of the POI's first matching OSM tag (amenity, shop, tourism, railway, leisure, …), e.g. cafe, fuel, charging_station, parking, pharmacy, supermarket, hotel, restaurant, fast_food, atm, bakery, hospital, station. Common colloquial phrases are normalised to their canonical token (coffee → cafe; ev_charging, ev charging, charging station → charging_station; petrol → fuel; chemist → pharmacy); anything else is passed through lowercased, and a category the index does not carry simply matches nothing: an empty FeatureCollection, never an error. Implies kinds=poi unless kinds is given explicitly. First-party index only: on the Photon proxy path this parameter answers 501 reverse-filtering-not-enabled (Photon's reverse cannot filter by category). |
| name | query | no | Restrict hits to places of this name or brand, nearest first; the "nearest Lloyds bank" question (name=Lloyds&categories=bank), which forward text search cannot answer: GET /geocode?q=Lloyds Bank ranks every branch in the country and only biases by proximity, so a namesake in another city outranks the branch 100 m away. Matched the same way the forward search matches names: lowercased, diacritic-folded, split into words, and EVERY word must match the place's name or one of its alternative names (alt_name, short_name, official_name, name:en), with the last word also matching as a prefix so partial input works (name=Sains finds Sainsbury's). It follows that name=Lloyds matches "Lloyds Bank" but name=Lloyds Bank does not match a branch mapped as just "Lloyds": combine name with categories for that. Not a kind filter: streets and localities of that name match too unless kinds says otherwise. Brand and operator tags are NOT searchable (they are returned in details but not indexed), so a branch whose name never mentions the brand is not reachable by name. First-party index only: on the Photon proxy path this parameter answers 501 reverse-filtering-not-enabled (Photon's reverse cannot filter by name). |
| radius_m | query | no | Maximum straight-line distance of any hit from the point, in metres (1–100000; the search ladder is capped and hits beyond the radius are dropped). Without it a category or name browse expands 2.5 km → 25 km → 100 km until it fills the page. First-party index only: on the Photon proxy path this parameter answers 501 reverse-filtering-not-enabled. |
| limit | query | no | Maximum results, 1–10 (default 5). Honoured on both the first-party and Photon proxy paths. |
Responses
200Photon-compatible GeoJSON FeatureCollection. First-party hits add
distance_m, a stable id, and a details object on POI hits (whitelisted OSM display tags); the Photon proxy path passes the upstream body through verbatim400Missing or malformed
lon/lat, or a malformed kinds/categories/name/radius_m/limit401Missing or invalid API key
429Quota or rate limit exceeded
501Geocoding not enabled (neither SN_GEOCODE_DIR nor SN_PHOTON_URL set), or
categories/name/radius_m on a Photon-proxy deployment (urn:sn-gateway:problem:reverse-filtering-not-enabled; clients feature-detect on this status)502Photon upstream failed
Error bodies follow the shared problem model documented on API conventions.
Also under geocoding
Generated from https://api.mapmap.ai/openapi.json on 2026-09-17 · operationId get_geocode_reverse