Forward Geocode (v2)

The v2 Forward Geocode API matches a full free-text query to its corresponding geographic coordinates and administrative context.

How it Works

• Send the text you want to match using the q parameter, such as "Nieuwezijds Voorburgwal 147".
• Restrict results to a country with country, and cap the number of results with size.
• Pass format=pelias to get back a full GeoJSON FeatureCollection — see the trap below.

format=pelias is required for the GeoJSON envelope

Without format=pelias — or with any other value — the endpoint silently returns a different, flat shape instead of the documented FeatureCollection. This is not an error; it's a different response contract. Always pass format=pelias explicitly.

Endpoint

GET https://gateway.mapmetrics-atlas.net/v2/forward-geocode/

Parameters

Parameter	Type	Req	Example	Description
q	string	✅	Nieuwezijds Voorburgwal 147	The search query text. Not text.
country	string	❌	nl	ISO-2 lowercase country code to restrict search.
size	integer	❌	10	Number of results to return.
format	string	✅	pelias	Must be pelias to get the GeoJSON FeatureCollection shape.
token	string	✅	YOUR_API_KEY	Auth token, passed as a query parameter.

Example

curl "https://gateway.mapmetrics-atlas.net/v2/forward-geocode/?q=Nieuwezijds%20Voorburgwal%20147&country=nl&size=10&format=pelias&token=YOUR_API_KEY"

Example Response

{
  "geocoding": {
    "version": "0.2",
    "attribution": "http://localhost:4000/attribution",
    "query": {
      "q": "Nieuwezijds Voorburgwal 147",
      "country": "nl",
      "size": 10
    },
    "engine": {
      "name": "Pelias",
      "author": "Mapzen",
      "version": "1.0"
    }
  },
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [5.7423, 50.8514]
      },
      "properties": {
        "id": "osm:ext:7f3a9c1d2e4b5a6f",
        "gid": "osm:address:7f3a9c1d2e4b5a6f",
        "layer": "address",
        "name": "Nieuwezijds Voorburgwal 147",
        "label": "Nieuwezijds Voorburgwal 147, Maastricht, Netherlands",
        "housenumber": "25",
        "street": "Nieuwezijds Voorburgwal",
        "locality": "Maastricht",
        "country": "Netherlands",
        "country_a": "NLD"
      }
    }
  ],
  "bbox": [5.7423, 50.8514, 5.7423, 50.8514]
}

region and postalcode are frequently absent

Unlike the v1 Pelias response, region and postalcode are frequently missing from v2 properties — do not assume either field is always present.

Attribution must be surfaced

geocoding.attribution is the ODbL licence credit. Any client displaying results must surface this attribution.