Documentation

Everything is a GET request to https://api.mygeocode.com/v1/ with query parameters, answered with JSON. This page covers the parts every endpoint shares. The endpoint pages cover the parameters and fields of each one.

Your first request

No account is needed. Run this from any machine:

$ curl "https://api.mygeocode.com/v1/forward?q=Brandenburg+Gate,+Berlin&limit=1"

{
  "status": "ok",
  "query": "Brandenburg Gate, Berlin",
  "results": [
    {
      "formatted": "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany",
      "lat": 52.516275,
      "lon": 13.377704,
      "type": "poi",
      "precision": "house",
      "confidence": 0.99,
      "components": {
        "name": "Brandenburger Tor",
        "road": "Pariser Platz",
        "suburb": "Mitte",
        "city": "Berlin",
        "state": "Berlin",
        "postcode": "10117",
        "country": "Germany",
        "country_code": "de"
      },
      "bounds": { "north": 52.516441, "south": 52.516107, "east": 13.377862, "west": 13.377538 }
    }
  ]
}

That request counted as 1 of the 2,500 your IP address gets today. The response headers tell you where you stand:

HTTP/2 200
content-type: application/json; charset=utf-8
x-quota-limit: 2500
x-quota-used: 1
x-quota-reset: 1756339200
x-request-id: 01J6F3ZK9W2R8Q5V7N4M1B0CXE

Base URL and endpoints

Endpoint	Path	Required parameters
Forward geocoding	`GET /v1/forward`	`q` (or structured fields)
Reverse geocoding	`GET /v1/reverse`	`lat`, `lon`
Address autocomplete	`GET /v1/autocomplete`	`q`
IPv4 lookup	`GET /v1/ipv4`	none (`ip` optional)
IPv6 lookup	`GET /v1/ipv6`	none (`ip` optional)
Timezone lookup	`GET /v1/timezone`	`lat`, `lon`
Elevation lookup	`GET /v1/elevation`	`lat`, `lon` or `locations`
Postal code lookup	`GET /v1/postcode`	`code`

Only HTTPS is served. Plain HTTP requests are refused with 400 rather than redirected, so that a key is never sent in the clear by accident. HTTP/2 and HTTP/3 are supported. Responses are compressed when the client accepts gzip or br.

The response envelope

Every response is a JSON object with a status of ok or error.

On ok, the payload follows: results (an array) for endpoints that can return several matches, result (an object or null) for reverse geocoding, and flat fields for IP and timezone lookups.
On error, there is an error object with a code string, a message sentence and, when relevant, the param that caused it. The HTTP status matches. See errors.

A query that is valid but matches nothing is ok with an empty results array or a null result. That is not an error, and it counts as a request.

Parameters every endpoint accepts

Parameter	Description
`key`	Your API key, if you prefer a query parameter to the `X-API-Key` header. The header is better because query strings end up in logs.
`lang`	ISO 639-1 language code for place names, where we have them. Default `en`. Address formatting always follows the country's convention.
`pretty`	`1` to indent the JSON. Handy in a browser; leave it off in code.

Parameter names are case-sensitive and lower case. Unknown parameters are ignored, and empty parameters are treated as absent, so an HTML form can submit optional fields blank. Coordinates are decimal degrees; lat from -90 to 90 and lon from -180 to 180. Text is UTF-8 and should be URL-encoded.

Authentication in one paragraph

Without a key, usage is counted against the calling IP address (or the /40 block for IPv6) and stops at 2,500 a day. Everything on this site can be tried that way, with no account. With an account, which needs only an email address, either whitelist your server IPs in the dashboard so their traffic is attributed to you automatically, or send a key in the X-API-Key header. Requests above 2,500 a day use prepaid credits, or are covered by the Unlimited plan. A key may be used from at most two IP addresses in any 24 hour period. The full rules are on the authentication page.

Quota and rate limit headers

Header	Meaning
`X-Quota-Limit`	Free requests per day for this IP or account: 2,500. On the Unlimited plan, `-1`.
`X-Quota-Used`	Requests counted so far today, including this one.
`X-Quota-Billable`	Accounts only: requests above the free allowance today, paid from credits.
`X-Credits-Remaining`	Accounts with credits: the balance after this request, in credits (one credit is one request). Absent on Unlimited.
`X-Quota-Reset`	Unix time of the next midnight UTC, when the counter resets.
`X-RateLimit-Limit`	Burst limit in requests per second: 10 anonymous, 50 for accounts.
`X-RateLimit-Remaining`	Requests left in the current second.
`X-Request-Id`	A unique ID for the request. Quote it when you write to support.

Calling from browsers

CORS is enabled on every endpoint with Access-Control-Allow-Origin: *, and the quota headers are exposed. A page can call the API directly, in which case the visitor's own IP address is what gets counted. Do not ship an API key in page source; see keys and browsers.

Versioning

The path prefix /v1/ is the version. Within a version we add fields and parameters but never remove or rename them, and never change the meaning of an existing field. If we ever need to break something, it goes in /v2/ and /v1/ keeps working for at least six months after the announcement. Additions are listed in the changelog.

Your JSON parser should ignore fields it does not know. That is the only forward-compatibility requirement.

Other formats

If you already have code written against Google, Bing, HERE, Mapbox, Nominatim or another provider, you may not need any of the above. The drop-in hosts accept those providers' request formats and answer in their response formats, and the JavaScript drop-ins do the same for map libraries.