Retrieve Endpoint (v2)

The v2 Retrieve API resolves one autocomplete suggestion into full coordinates. This is the billable step in the v2 autocomplete flow — see Sessions for how retrieve closes a session.

How it Works

• Take the ord value from an autocomplete suggestion the user picked.
• Call /v2/retrieve/ with that ord, plus the suggestion's country and layer, to get back a center coordinate pair.
• Pass the same session_token used during autocomplete so the session is closed correctly and billed once.

ord is the handle — id 404s

Retrieval is keyed on ord, not id. Retrieving by id returns 404 on every layer, with no exception. Always take ord straight from the autocomplete suggestion you're resolving — never construct or reuse an id.

Endpoint

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

Parameters

Parameter	Type	Req	Example	Description
country	string	✅	nl	ISO-2 lowercase country code, from the suggestion.
layer	string	✅	address	Layer of the suggestion, from the suggestion.
ord	integer	✅	128371	The suggestion handle from /v2/autocomplete/. Not id.
hn	boolean	❌	true	Housenumber flag, from the suggestion.
session_token	string	❌	sess_a1b2c3	Same token used during autocomplete; closes the session.
token	string	✅	YOUR_API_KEY	Auth token, passed as a query parameter.

Example

curl "https://gateway.mapmetrics-atlas.net/v2/retrieve/?country=nl&layer=address&ord=128371&hn=true&session_token=sess_a1b2c3&token=YOUR_API_KEY"

Example Response

{
  "center": [5.7423, 50.8514],
  "country": "nl",
  "layer": "address",
  "locality": "Maastricht",
  "id": ""
}

center is [lon, lat]

center is [longitude, latitude], in that order — easy to swap by mistake. id in the response is currently a placeholder empty string; don't rely on it for anything.

Retrieve Batch

/v2/retrieve-batch/ resolves several suggestions in one call.

Endpoint

GET https://gateway.mapmetrics-atlas.net/v2/retrieve-batch/

Parameters

Parameter	Type	Req	Example	Description
items	string	✅	[{"country":"nl","layer":"address","ord":128371,"hn":true}] (URL-encoded)	URL-encoded JSON array of {country, layer, ord, hn?} objects.
token	string	✅	YOUR_API_KEY	Auth token, passed as a query parameter.

Only items works — no repeated params

/v2/retrieve-batch/ takes one parameter, items, holding a URL-encoded JSON array. It does not accept repeated params: ord=128371&ord=128372, ords=128371,128372, and ids=... all silently return HTTP 200 with count: 0 — no error, no results.

Example

curl "https://gateway.mapmetrics-atlas.net/v2/retrieve-batch/?items=%5B%7B%22country%22%3A%22nl%22%2C%22layer%22%3A%22address%22%2C%22ord%22%3A128371%2C%22hn%22%3Atrue%7D%2C%7B%22country%22%3A%22nl%22%2C%22layer%22%3A%22address%22%2C%22ord%22%3A128372%7D%5D&token=YOUR_API_KEY"

The decoded items value in the example above is:

[
  { "country": "nl", "layer": "address", "ord": 128371, "hn": true },
  { "country": "nl", "layer": "address", "ord": 128372 }
]

Example Response

{
  "count": 2,
  "results": [
    { "center": [5.7423, 50.8514], "id": "" },
    { "center": [5.7431, 50.8519], "id": "" }
  ]
}

See Also

• Autocomplete — produces the ord values retrieve consumes.
• Sessions — retrieve closes the session it belongs to.