Skip to content
Ubhub Location Service
Getting started

Overview

Getting started

From zero to your first geocoding result in five steps.

1. Create an account

Create a developer account with your name, email and a password of at least 10 characters. You are signed in right away and land on the developer dashboard.

2. Create an API key

  1. Open API keys in the dashboard.
  2. Choose Create API key, give it a name that says where it is used (for example "Production backend"), choose the endpoints it may call and when it expires, and confirm.
  3. Copy the key or download it. It looks like geo_ followed by 32 letters and digits.

The key is shown only once

Only a hash of the key is stored, so it cannot be displayed again. If you lose it, regenerate the key or create a new one.

3. Make your first request

Search for a place with the geocoding endpoint. Replace YOUR_API_KEY with your key:

Terminal
curl "https://developers.ubhub.mn/v1/geocode?q=Ulaanbaatar" \
  -H "Authorization: Bearer YOUR_API_KEY"

The same request in other languages:

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

4. Read the response

A successful request returns 200 OK with a JSON body like this:

200 OK
{
  "query": "Ulaanbaatar",
  "results": [
    {
      "id": "loc_ff6ee5b78230a6a5",
      "name": "Ulaanbaatar OU School",
      "address": "18-р хороо, Хан-Уул, Mongolia",
      "latitude": 47.89872,
      "longitude": 106.92998,
      "type": "poi"
    },
    {
      "id": "loc_868bb41091d20580",
      "name": "Ulaanbaatar 2 Station",
      "address": "29-р хороо, Баянгол, Mongolia",
      "latitude": 47.908137,
      "longitude": 106.844495,
      "type": "poi"
    }
  ],
  "count": 2
}
Response fields
FieldTypeDescription
querystringThe search text, with whitespace normalized.
resultsarrayMatches, best first. Empty when nothing matched (still 200).
results[].latitude / longitudenumberWhere the place is (WGS84).
countintegerNumber of results returned.

Also look at the response headers: X-RateLimit-Remaining tells you how many requests you have left in the current minute, and X-Request-ID identifies the request if you need support.

5. Integrate into your application

  • Keep the key on your server and call the API from there. Browser or mobile apps should call your own backend, which adds the key. See Keeping keys safe.
  • Set a timeout on every request and cancel stale ones (for example with an AbortController in JavaScript). See Code examples for each language.
  • Handle errors by their code, and back off when you get 429. See Errors and Rate limits.
  • For search-as-you-type, wait about 300 ms after the last keystroke before calling /v1/geocode, and cancel the previous request when a new one starts.
  • Watch your traffic on the Usage page of the dashboard.