Documentation menu
GET/geocode/suggest
API key required, sent as Authorization: Bearer snk_… or ?api_key=snk_….
What it does
Search-as-you-type suggestions. What it costs: the first 5,000 suggest requests per UTC day are free, counted across every key on the calling identity rather than per key, and every suggest beyond that bills one Standard call. GET /geocode/retrieve and GET /geocode always bill one Standard call each and are never discounted, so a client that plots straight from a suggestion's lat/lon pays nothing for search at ordinary volumes. The allowance is for this endpoint alone: unused suggest calls expire at midnight UTC and never become included volume for anything else. Keys on an unverified (provisional) identity are outside the allowance and bill per call.
Call it
curl -fsS -X GET "https://api.mapmap.ai/geocode/suggest?q=…" \
-H "Authorization: Bearer $MAPMAP_KEY"Parameters
| Name | In | Required | Description |
|---|---|---|---|
| q | query | yes | Partial query, as typed. 1–256 characters. The trailing token is treated as a prefix (Downing Str reaches Downing Street); every earlier token must be a completed word. The index's minimum edge gram is two characters, so a one-character q legitimately returns an empty list rather than an error |
| limit | query | no | Maximum suggestions, 1–10 (default 5) |
| bias | query | no | Location bias as lon,lat (WGS84): the map centre for a search box. Reorders candidates towards the point; it never excludes one |
| zoom | query | no | Map zoom (0–20) scaling the bias, exactly as on GET /geocode: zoomed in favours nearby results, zoomed out favours prominence. Only meaningful with bias |
| bbox | query | no | Hard bounding-box filter as minLon,minLat,maxLon,maxLat (WGS84, GeoJSON axis order). Unlike bias this excludes anything outside the box outright |
| lang | query | no | Result language. Accepted for symmetry with GET /geocode; the first-party index that serves this endpoint stores one name per document plus its alternatives, so the value does not currently change the answer |
Responses
lat/lon: a suggestion is immediately plottable and cacheable, and picking one costs a retrieve only when the caller wants the full feature. (Mapbox's equivalent withholds coordinates from suggestions so that every pick must be followed by a retrieve; that is a billing shape, not a technical constraint, and it is not ours.)| Field | Type | Required | Description |
|---|---|---|---|
| suggestions | Suggestion[] | yes | Suggestions, best first. Empty is an ordinary answer, not an error — a one-character query cannot match the index's two-character minimum edge gram, and a nonsense query matches nothing. |
q, or a malformed limit/bias/bboxurn:sn-gateway:problem:suggest-not-enabled; clients feature-detect on this status and fall back to GET /geocode)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_suggest