Forward geocoding

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

Parameters

Example

$ curl "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)).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}, timeout=10)
print(r.json()["results"][0])

{
  "status": "ok",
  "query": "Dam 1, Amsterdam",
  "results": [
    {
      "formatted": "Dam 1, 1012 JS Amsterdam, Netherlands",
      "lat": 52.373119,
      "lon": 4.893604,
      "type": "address",
      "precision": "house",
      "confidence": 0.98,
      "place_id": "nl.addr.c21d40e8",
      "components": {
        "house_number": "1",
        "road": "Dam",
        "neighbourhood": "Centrum",
        "city": "Amsterdam",
        "state": "North Holland",
        "state_code": "NH",
        "postcode": "1012 JS",
        "country": "Netherlands",
        "country_code": "nl"
      },
      "bounds": { "north": 52.373519, "south": 52.372719, "east": 4.894204, "west": 4.893004 }
    }
  ]
}

Response fields

Component keys

Only keys that apply are present. The same keys are used in every 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.
• When a house number cannot be found on a known street, the result has type: street and precision: street with the number interpolated where data allows. 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.

Errors

400 invalid_request when neither q, a structured field nor place_id is present, when limit is outside 1 to 10, or when bounds or proximity is malformed. See errors for the rest.