--- title: "`GET /geocode/suggest?q=&limit=&bias=,&bbox=…&lang=…`." method: GET path: "/geocode/suggest" tags: ["geocoding"] --- # \`GET /geocode/suggest?q=&limit=&bias=,&bbox=…&lang=…\`. `GET /geocode/suggest` ## Request - Base URL: `https://api.mapmap.ai` - URL: `https://api.mapmap.ai/geocode/suggest` - Auth: one of: - HTTP bearer - API key in query parameter `api_key` 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. **UK postcodes:** when the whole query is a British postcode, the postcode leads the list. A full unit (`BN14 7RY`, `BN147RY`, `bn14 7ry`) comes first whenever the index or the forward geocoder knows that exact unit, followed by places inside it and then other units of its sector; when no source knows it, the nearest units of its sector are listed and no position is invented. A bare outward code (`BN14`) leads with its district, and an outward code with the start of an inward code (`BN14 7`, `BN14 7R`) leads with the units of that sector, nearest the `bias` or the district centre first. A postcode row that no index document holds carries a reserved id starting `ukpc:` (for example `ukpc:BN147RY` or `ukpc:BN14`), which `GET /geocode/retrieve` resolves like any other id. **Irish Eircodes and Dutch postcodes:** an Eircode (`D02 X285`, `d02x285`) or a Dutch postcode (`1012 JS`, `1012JS`, with or without a place name after it) leads the list when a source knows it, and a Dutch postcode with a house number (`1012 JS 1`, `1012JS 1`) leads with that address. The response then carries a `postcode` object whose `match` says `exact`, `area` or `none`. Full Eircodes are held in a licensed database this service does not use, so an Eircode is found exactly only where OpenStreetMap carries it; otherwise its routing area leads (`D02`, Dublin 2, from GeoNames, CC BY 4.0) and `match` is `area`, and a code whose routing key does not exist is reported as `none`. Ids `iepc:` (`iepc:D02X285`, `iepc:D02`) and `nlpc:` (`nlpc:1012JS`) are reserved for these rows. **House numbers:** when the whole query is a house number and a street with a place after a comma (`10 rue de Rivoli, Paris`), or with a `bias` within 10 km, and no indexed address is exactly that, the forward geocoder's exact match leads the list under a reserved `photon:` id (for example `photon:n703432291@48.8554814,2.3604077`), which `GET /geocode/retrieve` resolves. ## Query parameters - `q` string, required - `limit` integer - `bias` string - `zoom` integer - `bbox` string - `lang` string ## Response `200` Suggestions, best first. Each carries `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.) - SuggestResponse: The `GET /geocode/suggest` response. - `postcode` SuggestPostcode: How a typed postcode was matched (`GET /geocode/suggest`). - `code` string, required: The postcode as read, in its canonical form: `D02 X285`, `1012 JS`, or `1012 JS 1` with a house number. - `country` string, required: The postcode system's country (ISO 3166-1 alpha-2): `IE` or `NL`. - `match` string, required: `exact`: the first suggestion is exactly this postcode or address. `area`: only a larger area containing it is known, and the first suggestion is that area (an Eircode's routing area such as `D02`, Dublin 2, or the postcode of a Dutch address whose number is not known); no position is claimed for the code itself. `none`: no source knows it and no suggestion is for it. Full Eircodes are held in a licensed database this service does not use, so an Eircode is found exactly only where OpenStreetMap carries it. - `suggestions` Suggestion[], required: Suggestions, best first. Empty is an ordinary answer, not an error. A one-character query cannot prefix-match the index's two-character minimum edge gram, so it returns only exact single-character matches, often none; a nonsense query matches nothing. - `context` string, required: The secondary line, street, city, region, postcode, country, in that order, minus anything already said by `name`. Empty when the document carries no context at all. - `id` string, required: Stable document id. Pass it to `GET /geocode/retrieve` for the full feature, and to `POST /geocode/selection` to record the pick. - `kind` string, required: Document kind: `poi`, `address`, `street`, `postcode`, or a locality's own `place=` tier (`city`, `town`, `suburb`, …). - `lat` number, double, required: Latitude (WGS84). - `lon` number, double, required: Longitude (WGS84). - `name` string, required: The primary line: what to render in bold. ## Other responses - `400`: Missing or over-long `q`, or a malformed `limit`/`bias`/`bbox` - `401`: Missing or invalid API key - `429`: Quota or rate limit exceeded - `501`: This deployment has no first-party geocode index (`urn:sn-gateway:problem:suggest-not-enabled`; clients feature-detect on this status and fall back to `GET /geocode`) --- [API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)