`GET /geocode/suggest?q=<text>&limit=<n≤10>&bias=<lon>,<lat>&bbox=…&lang=…`.
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.
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
Query parameters
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 does not prefix-match: it returns only exact single-character matches (a place whose name is that character), often none, and an empty list is an ordinary answer rather than an error
Maximum suggestions, 1–10 (default 5)
Location bias as lon,lat (WGS84): the map centre for a search box. Reorders candidates towards the point; it never excludes one
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
Hard bounding-box filter as minLon,minLat,maxLon,maxLat (WGS84, GeoJSON axis order). Unlike bias this excludes anything outside the box outright
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
Response
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.)
Changes
No recorded changes to this operation across all 1 revision of this API.