Autocomplete Endpoint (v2)

The v2 Autocomplete API provides instant place and address suggestions based on partial user input. It is typically used in search boxes where results update in real time as the user types.

Base URL: all v2 examples on this page use https://gateway.mapmetrics-atlas.net. Auth: the token parameter is a query parameter, not a header. Trailing slash is mandatory on every v2 path — /v2/autocomplete (no trailing slash) returns 404. Always call /v2/autocomplete/.

How it Works

• Send a partial query using the q parameter, such as "Nieuwezijds Voorburgwal 147".
• The API returns a list of matching suggestions (venues, streets, addresses, localities) with no coordinates attached — see below.
• To resolve a suggestion to actual coordinates, take its ord value and call /v2/retrieve/.
• Pass a stable session_token across all keystrokes of one search so the whole typing sequence bills as a single session — see Sessions for the full billing model.

Common mistake: q, not text

The parameter is q. Sending text=Nieuwezijds Voorburgwal 147 does not error — it returns HTTP 200 with "results": [] and "q": "". It silently looks like "no matches" instead of failing loudly. This is the single most common integration mistake against this endpoint.

proximity is longitude first

proximity takes the form <lon>,<lat> — longitude before latitude. Reversing the order does not error either; it returns plausible-looking but wrong results. A query centred on Maastricht with lat/lon swapped returned hits 22–27 km away, in the wrong town entirely.

Endpoint

GET https://gateway.mapmetrics-atlas.net/v2/autocomplete/

Parameters

Parameter	Type	Req	Example	Description
q	string	✅	Nieuwezijds Voorburgwal 147	The partial search text. Not text.
token	string	✅	YOUR_API_KEY	Auth token, passed as a query parameter.
country	string	❌	nl	ISO-2 lowercase country code to restrict results.
session_token	string	❌	sess_a1b2c3	Groups keystrokes into one billable session. See Sessions.
proximity	string	❌	5.7423,50.8514	<lon>,<lat> bias point. Longitude first.

Example

curl "https://gateway.mapmetrics-atlas.net/v2/autocomplete/?q=Nieuwezijds%20Voorburgwal%20147&country=nl&session_token=sess_a1b2c3&token=YOUR_API_KEY"

Example Response

{
  "count": 1,
  "q": "Nieuwezijds Voorburgwal 147",
  "mode": "autocomplete",
  "country": "nl",
  "elapsed_ms": 4,
  "results": [
    {
      "id": "osm:ext:7f3a9c1d2e4b5a6f",
      "ord": 128371,
      "layer": "address",
      "country": "nl",
      "hn": true,
      "housenumber": "25",
      "text": "Nieuwezijds Voorburgwal 147",
      "place_name": "Nieuwezijds Voorburgwal 147, Maastricht",
      "locality": "Maastricht",
      "category": null,
      "brand": null
    }
  ]
}

Note that no result carries center, geometry, or bbox — coordinates are deliberately withheld. Suggestions are cheap to serve at every keystroke; coordinate resolution is the billable step, and it only happens when you call /v2/retrieve/ on the suggestion the user picked.