Forward geocoding

Turn text into coordinates. Accepts full addresses, partial addresses, postcodes, place names and points of interest, in any language.

Parameters

Example

$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/forward?q=Dam+1,+Amsterdam&countries=nl&limit=1"

const url = new URL("https://api.mygeocode.com/v1/forward");
url.searchParams.set("q", "Dam 1, Amsterdam");
url.searchParams.set("countries", "nl");
url.searchParams.set("limit", "1");

const data = await (await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } })).json();
console.log(data.results[0]);

import requests

r = requests.get("https://api.mygeocode.com/v1/forward",
                 params={"q": "Dam 1, Amsterdam", "countries": "nl", "limit": 1}, headers={"X-API-Key": "YOUR_KEY"}, timeout=10)
print(r.json()["results"][0])

{
  "status": "ok",
  "query": "Dam 1, Amsterdam",
  "results": [
    {
      "formatted": "Dam 1, 1012 JS Amsterdam, The Netherlands",
      "lat": 52.373294,
      "lon": 4.893716,
      "type": "address",
      "precision": "house",
      "confidence": 0.89,
      "place_id": "-nUP3dP029QLr7V2yERn_v3RUl_wLSclXQ",
      "components": {
        "house_number": "1",
        "road": "Dam",
        "city": "Amsterdam",
        "postcode": "1012 JS",
        "country": "The Netherlands",
        "country_code": "nl"
      },
      "bounds": { "north": 52.373791, "south": 52.372791, "east": 4.894215, "west": 4.893215 },
      "codes": {
        "plus_code": "9F469VFV+8F",
        "geohash": "u173zq72xce5",
        "mgrs": "31UFU2891404245",
        "maidenhead": "JO22ki79",
        "dms": {
          "lat": "52° 22' 23.9\" N",
          "lon": "4° 53' 37.4\" E"
        },
        "mapcode": "NLD 2T.NG",
        "mapcode_international": "VHXG9.RLZZ"
      }
    }
  ]
}

Response fields

Component keys

Only keys that apply are present. The same keys are used in every country.

Annotations

Each block is added when the flag in its row is 1, or all of them with annotations=1. They cost nothing extra, but each one runs lookups of its own, so ask for the ones you use. A field we cannot fill is null or left out; it never fails the lookup. The blocks drawn from area, census and road data appear where that data is loaded for the country.

Notes

• Results are ordered by a combination of confidence, precision and proximity. The first result is the one to use unless you are showing a picker.
• A house placed along its street from the street's number range is still precision: house. When a house number cannot be found on a known street, the result has type: street and precision: street, at the street. Check precision if that matters to you.
• Postcodes alone are fine as q. For postcode-only workloads the postal code endpoint is faster and returns the postal authority's place name.
• A query in one script for a place that uses another (Cyrillic for a Japanese address, say) works, but lang decides the script of the response.

The same lookup in other providers' formats

If you already have code written against one of these providers, keep it: the drop-in host accepts the same path and parameters and answers in that provider's response shape, with this endpoint behind it. See how the drop-ins work.

Bulk lookups

Post a JSON body to the same path with queries, an array of up to 100 addresses, and the answer carries a results array with one entry per query in the order sent. Each entry counts as one request, and a batch larger than what is left of the allowance is refused whole.

Each entry holds its query and its results. The other parameters (limit, countries, lang, annotations and the rest) apply to every entry, sent either in the JSON body or in the query string.

$ curl -X POST "https://api.mygeocode.com/v1/forward" -H "Content-Type: application/json" -d '{"queries": ["Brandenburg Gate, Berlin", "Bahnhofstrasse 1, Zurich"]}'

Errors

400 invalid_request when neither q, a structured field nor place_id is present, when q is longer than 256 characters, when limit is outside 1 to 10, or when a batch holds more than 100 addresses. A malformed bounds or proximity is ignored. See errors for the rest.