Forward geocoding

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

GEThttps://api.mygeocode.com/v1/forward

Parameters

Parameter	Type	Description
`q`required*	string	Free-form text to geocode. Up to 256 characters.
`street`, `city`, `state`, `postcode`, `country`	string	*Structured alternative to `q`. Use when you already have the address in fields. At least one is required if `q` is absent. `country` here is an ISO 3166-1 alpha-2 code.
`place_id`	string	*A `place_id` from autocomplete. Returns that one place with full components and bounds. Overrides `q`.
`limit`optional	integer	Maximum results, 1 to 10. Default 5.
`countries`optional	string	Comma-separated ISO 3166-1 alpha-2 codes. Only results in these countries are returned. Example: `gb,ie`.
`bounds`optional	string	`south,west,north,east` in decimal degrees. Results inside the box rank first. Add `strict=1` to exclude results outside it.
`proximity`optional	string	`lat,lon`. Results near this point rank first.
`lang`optional	string	ISO 639-1 code for names in the response. Default `en`.
`key`optional	string	API key, if not sent as the `X-API-Key` header.

Example

curlJavaScriptPython

$ 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])

Response

{
  "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

Field	Type	Description
`query`	string	The text we interpreted, after trimming.
`results`	array	Matches, best first. Empty when nothing matched.
`results[].formatted`	string	Full address in the country's conventional format.
`results[].lat`, `lon`	number	WGS 84 decimal degrees.
`results[].type`	string	`address`, `street`, `postcode`, `city`, `region`, `country`, `poi`.
`results[].precision`	string	`house`, `street`, `postcode`, `admin`. What the point represents. See coverage.
`results[].confidence`	number	0 to 1. How well the result matches the query. Below 0.5 means we guessed.
`results[].place_id`	string	Stable identifier for this place.
`results[].components`	object	Address parts. See below.
`results[].bounds`	object	`north`, `south`, `east`, `west` of the matched feature.

Component keys

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

Key	Meaning
`name`	Name of a point of interest or building, when the match is one.
`house_number`	Including letters and ranges: `221B`, `12-14`.
`road`	Street name with its type: `Baker Street`, `Avenue Anatole France`.
`neighbourhood`, `suburb`	Sub-city areas, where the country uses them.
`city`	City, town or village.
`county`	County or district.
`state`, `state_code`	State, province or region, and its ISO 3166-2 suffix where one exists.
`postcode`	Postal code, formatted as the postal authority formats it.
`country`, `country_code`	Country name and lower-case ISO 3166-1 alpha-2 code.

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.

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.