Endpoints

Geocoding

One endpoint in two directions: a place name or address to coordinates (q), or coordinates to the nearest place (lat & lon).

Request

GET/v1/geocode

Requires an API key in the Authorization header. See Authentication.

Parameters

Parameters
Name	Type	Description
`q`optional	`string`	Forward geocoding: place name or address, 2 to 200 characters, with at least 2 letters or digits. Latin and Cyrillic are both supported, for example `Sukhbaatar Square` or `Сүхбаатарын талбай`.
`limit`optional	`integer`	Forward geocoding: maximum number of results, 1 to 20. Default `5`.
`lat`optional	`number`	Reverse geocoding: latitude in decimal degrees (WGS84), −90 to 90.
`lon`optional	`number`	Reverse geocoding: longitude in decimal degrees (WGS84), −180 to 180.

Example

curl -G "https://developers.ubhub.mn/v1/geocode" \
  --data-urlencode "q=Sukhbaatar Square" \
  -d limit=5 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

200 OK

{
  "query": "Sukhbaatar",
  "results": [
    {
      "id": "loc_3f2a9c1d8e7b6a50",
      "name": "Sukhbaatar District",
      "address": "7-р хороо, Сүхбаатар, Mongolia",
      "latitude": 47.92662,
      "longitude": 106.929681,
      "type": "poi"
    },
    {
      "id": "loc_9b1e4d7c2a6f3e81",
      "name": "Sukhbaatar District General Hospital",
      "address": "11-р хороо, Сүхбаатар, Mongolia",
      "latitude": 47.931345,
      "longitude": 106.928361,
      "type": "poi"
    }
  ],
  "count": 2
}

Response fields
Field	Type	Description
`query`	`string`	The search text, with whitespace normalized.
`results`	`array`	Matches, best first.
`results[].id`	`string`	Opaque, stable identifier of the place.
`results[].name`	`string`	Display name.
`results[].address`	`string \| null`	Address or area the place is in.
`results[].latitude`	`number`	Latitude (WGS84), up to 6 decimals.
`results[].longitude`	`number`	Longitude (WGS84), up to 6 decimals.
`results[].type`	`string`	Result category in lower case, for example `poi` for a point of interest, or `place` when no category is known.
`count`	`integer`	Number of results in this response.

No match is not an error: you get 200 OK with an empty list.

200 OK (no match)

{
  "query": "Nowhere Street",
  "results": [],
  "count": 0
}

Ranking

Results are ordered by how well the name matches the query:

Exact name matches.
Names that start with the query.
Names where every word of the query starts a word.
Names that contain every word of the query.

Within each group, more prominent places come first, then shorter names.

Building autocomplete

Wait about 300 ms after the last keystroke before sending a request, cancel the previous request when a new one starts (in JavaScript, pass an AbortController signal to fetch), and do not search until the user has typed at least 2 characters.

Reverse geocoding

Send lat and lon instead of q to turn a coordinate into the nearest meaningful place. The response is the same shape as a forward search, with one result: type is the match kind (address, place or street) and distance_meters is how far the match is from your point. Nothing found nearby is 200 OK with an empty results list, not an error. Send either q or both lat and lon, never both and never neither.

curl -G "https://developers.ubhub.mn/v1/geocode" \
  -d lat=47.9184 \
  -d lon=106.9177 \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

Errors
Status	Code	Meaning
400	`INVALID_REQUEST`	A parameter is missing or invalid. `details.field` names it. Also used with status 405 for a wrong HTTP method and 413 for an oversized body.
401	`INVALID_API_KEY`	The Authorization header is missing or malformed, the key does not exist, or it has expired (`details.reason` is `expired`).
403	`API_KEY_REVOKED`	The key was revoked in the dashboard.
403	`ENDPOINT_NOT_ALLOWED`	The key is not allowed to call this endpoint. Each key is limited to the endpoints chosen when it was created; `details.allowed_endpoints` lists them.
408	`REQUEST_TIMEOUT`	The data service behind the API did not answer in time.
429	`RATE_LIMIT_EXCEEDED`	The key used up its requests for the current one-minute window.
500	`INTERNAL_ERROR`	An unexpected error in the API.
502	`UPSTREAM_ERROR`	The data service behind the API failed or returned an invalid answer.
503	`SERVICE_UNAVAILABLE`	The service is temporarily unavailable, for example while a data source is being configured or loaded.

See Errors for the response format and how to handle each code.

Try it

Send a real request with one of your keys.

GET/v1/geocodePlayground

Request

GET /v1/geocode?q=Sukhbaatar%20Square&limit=5

curl "https://developers.ubhub.mn/v1/geocode?q=Sukhbaatar%20Square&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Send a request to see the response.