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	✅	276363	The suggestion handle from /v2/autocomplete/. Not id.
hn	string	❌	147	The house number, copied verbatim from the suggestion's hn. Not a flag — see below.
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.

hn is a house number, not a boolean

Despite the name, hn carries the house number itself (147), matching the string | null hn field on the autocomplete suggestion. Sending hn=true does not error — it is silently discarded, and you get the street centroid instead of the building. On Nieuwezijds Voorburgwal 147 that is a ~146 m error, with nothing in the response to signal it:

request	center	housenumber in response
…&ord=276363&hn=147	[4.890890, 52.373158]	"147"
…&ord=276363&hn=true	[4.890498, 52.371864]	absent
…&ord=276363 (omitted)	[4.890498, 52.371864]	absent

Always pass through the suggestion's own hn value. Never construct one.

Example

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

Example Response

{
  "center": [4.890890121459961, 52.3731575012207],
  "country": "nl",
  "housenumber": "147",
  "layer": "address",
  "locality": "Amsterdam",
  "name": "Nieuwezijds Voorburgwal",
  "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.

Not every suggestion can be retrieved

Rows that carry no ord at all (the key is absent, not null) cannot be resolved — see Non-retrievable rows. Filter them out before you get here.

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":276363,"hn":"147"}] (URL-encoded)	URL-encoded JSON array of {country, layer, ord, hn?} objects. hn is a string house number — see the warning above.
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%3A276363%2C%22hn%22%3A%22147%22%7D%2C%7B%22country%22%3A%22nl%22%2C%22layer%22%3A%22address%22%2C%22ord%22%3A276362%7D%5D&token=YOUR_API_KEY"

The decoded items value in the example above is:

[
  { "country": "nl", "layer": "address", "ord": 276363, "hn": "147" },
  { "country": "nl", "layer": "address", "ord": 276362 }
]

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.