Places, addresses, routing and live traffic for **Mongolia**. Search understands Mongolian Cyrillic, Latin transliteration and the way Mongolian addresses are written. One REST API, one key. Place responses follow the Grab Places Partner format, so an integration built for that contract needs little adaptation. # Getting started 1. Create an account in the [developer console](https://maps.tino.mn/console) and verify your email address. 2. Create an API key in the console. The key is shown once: keep it in your server's secret store. 3. Call the API from your backend. The base URL is `https://maps.tino.mn`, and every endpoint in this reference is a `GET` that returns JSON. ```bash curl -G "https://maps.tino.mn/maps/place/v2/search" \ --data-urlencode "keywords=улсын их дэлгүүр" \ --data-urlencode "language=en" \ -H "X-API-Key: $TINO_MAPS_KEY" ``` The Free plan is self-serve: 1,000 requests a day at 1 request per second. See [Plans and limits](#section/Plans-and-limits). The playground on the [Tino Maps home page](https://maps.tino.mn/) is a demo, not part of the API. It is rate-limited per visitor, returns basic place fields only and may not be called from your own software. Build with your own key. # Authentication Every request needs an API key. | Send the key as | Status | |---|---| | `X-API-Key: ` header | Recommended. | | `Authorization: Bearer ` header | Accepted. | | `api_key=` query parameter | **Deprecated.** Still accepted so that existing integrations keep working, but a key in a URL leaks into server logs, proxies and browser history. Move to a header: this method will be removed. | **Keep keys on your server.** An API key is a secret: anyone who has it can spend your quota and read the API in your name. Do not put it in browser JavaScript or in a mobile app you distribute. Call Tino Maps from your backend and send your clients only the results. Use a separate key for each application, so that you can revoke one without touching the others, and revoke a key in the console as soon as it may have leaked. To show a map on a website, use a Map Application key instead (see [Map display](#section/Map-display)). It works only with the map SDK, and only from the website origins you list. | HTTP | `status.code` | Meaning | |---|---|---| | 401 | `UNAUTHORIZED` | No key was sent. | | 401 | `INVALID_API_KEY` | The key does not exist. | | 403 | `INVALID_API_KEY` | The key has been revoked. | | 403 | `EXPIRED_API_KEY` | The key has expired. | | 403 | `ACCOUNT_DISABLED` | The account that owns the key has been disabled. | | 403 | `MAP_APPLICATION_KEY_SCOPE` | A Map Application key was used for this API. Use a regular API key. | # Plans and limits | Plan | Requests per day | Requests per second | How to get it | |---|---|---|---| | Free | 1,000 | 1 | Self-serve in the [console](https://maps.tino.mn/console) | | Basic | 50,000 | 10 | [sales@tino.mn](mailto:sales@tino.mn) | | Pro | 500,000 | 50 | [sales@tino.mn](mailto:sales@tino.mn) | | Enterprise | Custom | Custom | [sales@tino.mn](mailto:sales@tino.mn) | - **Limits apply per account.** Every key the account holds or has held, deleted keys included, draws from the same daily quota and the same per-second limit, so creating more keys does not add capacity. - An account can hold up to 5 active keys, Map Application keys included, and can create at most 6 keys in any 24 hours; deleted keys count toward the 6. - The daily quota resets at midnight, Ulaanbaatar time (UTC+8). - A request counts toward the quota once its key is accepted and it is within the limits, whatever the endpoint then answers: `304 Not Modified` and the endpoint's own 4xx and 5xx answers count too, such as `400` for a missing parameter or `404` for an unknown place. A request refused before that does not count: the key and account refusals listed under [Authentication](#section/Authentication) (`401`, `403`) and `429`. Nor does a request to a path or with a method the API does not have (`404`, `405`). - To move to a paid plan, email [sales@tino.mn](mailto:sales@tino.mn) from your account's address with the volume you expect. Over a limit, the API answers `429 Too Many Requests` with a `Retry-After` header in seconds. The body repeats it as `data.retry_after`. | `status.code` | Meaning | `Retry-After` | |---|---|---| | `RATE_LIMIT_EXCEEDED` | Too many requests this second. | `1`. Slow down, then retry. | | `DAILY_LIMIT_EXCEEDED` | Today's quota is used up. | Seconds until the quota resets. Do not retry before then. | # Responses and errors Responses are JSON. Every response carries a `uuid`, unique to the response, and a `status`. A successful response has `status.code` `SUCCESS`: ```json { "uuid": "6f1c2d3e-8a4b-4c5d-9e6f-7a8b9c0d1e2f", "status": { "code": "SUCCESS", "message": "Request successful" }, "places": [] } ``` An error uses the same envelope, with the error in `status`: ```json { "uuid": "0b9a8c7d-6e5f-4a3b-2c1d-0e9f8a7b6c5d", "status": { "code": "INVALID_REQUEST", "message": "Parameter 'location' is required (format: latitude,longitude)" } } ``` Branch on the HTTP status and `status.code`. `status.message` is written for people and may change. | HTTP | `status.code` | Meaning | |---|---|---| | 400 | `INVALID_REQUEST` | A required parameter is missing or malformed. | | 400 | `VALIDATION_ERROR` | A parameter is out of range, such as search text longer than 200 characters. | | 401, 403 | | See [Authentication](#section/Authentication). | | 404 | `NOT_FOUND` | The place or path does not exist. | | 404 | `ROUTE_NOT_FOUND` | There is no route between the coordinates. | | 405 | `INVALID_REQUEST` | The HTTP method is not supported for this path. | | 429 | `RATE_LIMIT_EXCEEDED`, `DAILY_LIMIT_EXCEEDED` | See [Plans and limits](#section/Plans-and-limits). | | 500 | `INTERNAL_ERROR` | Something failed on our side. Retry with backoff. | | 502 | `UPSTREAM_UNAVAILABLE` | Routing is temporarily unavailable. Retry with backoff. | | 503 | `INTERNAL_ERROR`, `UPSTREAM_UNAVAILABLE` | A feature is temporarily unavailable, such as the traffic layer or one travel mode. | Every response has an `X-Request-ID` header. Include it when you contact us about a request. **Forward compatibility.** Fields and values are added without notice, for example a new field on a place or a new `business_type` value. Ignore fields you do not know, treat a `business_type` you do not know as `other`, and do not depend on the order of keys. **Place ids.** `poi_id` is an opaque string. Most ids are UUIDs, but some results carry an id in another format. Store it exactly as returned and pass it back unchanged. A result that is not a stored place, such as an address point in `nearby` or an area result of `reverse-geo` with `mode=explore`, has an empty `poi_id`: it has no detail, and must not be used as a key. **Caching.** Many read endpoints send an `ETag` and `Cache-Control: private, max-age=…`. Send the ETag back in `If-None-Match` to get `304 Not Modified` when nothing has changed; a 304 still counts toward your quota. A response belongs to the key that requested it: never serve one caller's cached response to another. # Coordinates and languages - Places, entrances and `/maps/v1/matrix` take a point as `lat,lon`, for example `location=47.918,106.917`. - `/maps/v1/direction` and `/maps/v1/directions/multi` take `coordinates=lon,lat`, unless you add `lat_first=true`. - `/maps/v1/traffic/cells` takes `bbox=minLon,minLat,maxLon,maxLat`. - Tino Maps covers Mongolia. `nearby`, `explore`, `trending` and `reverse-geo` return an empty list for a point outside Mongolia's bounding box (latitude 41.5 to 52.2, longitude 87.7 to 119.9). - The `language` parameter localizes names, addresses and `rider_label`: `mn` (the default), `en`, `ru`, `zh`, `ko` or `ja`. Any other value means `mn`. Where a place has no translation, `ru` falls back to the Mongolian Cyrillic name and the other languages to the English name or a Latin transliteration. # Custom places Publish your own places, such as branches, parcel lockers or pickup points, and the same endpoints serve them alongside every other place. **Adding places.** In the [console](https://maps.tino.mn/console), open **Places** and choose **New place**, or **Import many** to paste up to 500 places at a time. An import takes CSV with the header `name,category,lat,lon,address,phone,district,khoroo` (`city`, `name_en` and `website` columns are also read) or a JSON array of objects with the fields below. An import of more than 500 rows is rejected as a whole, so split a large file into batches. A row that fails validation is skipped and listed with the reason. | Field | Rules | |---|---| | `name` | Required, 1 to 200 characters. | | `category` | Required. One of the [business types](#tag/Places), for example `parcel_locker`. | | `lat`, `lon` | Required. Inside Mongolia. In the console, drag the marker on the map. | | `name_en`, `address`, `english_address`, `description`, `keywords` | Optional. `keywords` is a list of extra search terms. | | `city`, `district` | Optional, up to 100 characters each. | | `khoroo`, `horoolol`, `building` | Optional, up to 50 characters each. | | `phone` | Optional, up to 50 characters. | | `website`, `email` | Optional, up to 255 characters each. | | `operating_hours` | Optional. A JSON object by day, for example `{"mon": {"open": "09:00", "close": "18:00"}, "sun": {"closed": true}}`. | | `icon_url` | Optional logo. Upload it in the console: JPEG, PNG or WebP up to 2 MiB; SVG is not accepted. Save one logo as your default to reuse it on every place. | **Visibility.** The places of a verified account go live at once. A new account is unverified: its places are marked *Pending review* in the console until Tino verifies the account, which publishes them. Pending places are not hidden from every endpoint, so do not add a place before you are ready for people to see it. To ask for verification, email [sales@tino.mn](mailto:sales@tino.mn) from your account's address. **Reading your places.** Add `owner=` to [search](#operation/search) or [nearby](#operation/nearby), with `business_type` if you need it. An owner-scoped `nearby` returns every match, nearest first. The console does not show your account id yet: email [sales@tino.mn](mailto:sales@tino.mn) and we will send it. **Deleting.** A deleted place leaves search and nearby results at once. Its id keeps resolving in [detail](#operation/placeDetail), so saved references do not break, and you can restore it from the console. # Map display **Beta, by invitation.** Map Applications let a website show the Tino Maps basemap with a key that is restricted to that website. They are not open for self-serve sign-up yet: email [sales@tino.mn](mailto:sales@tino.mn) with your website's domain, and we will enable your account. Outside the beta, the map SDK refuses Map Application keys with `403 MAP_APPLICATIONS_BETA`. In the console's **Map Applications** tab, create a web application and list the origins it runs on. You get a Map Application key and this snippet: ```html

``` - **Allowed origins.** A web Map Application key works only on pages served from the origins you list. An origin is a scheme, a host and, when it is not the default, a port, such as `https://www.example.mn`: no paths and no wildcards, at most 20 per application. `https://example.mn` and `https://www.example.mn` are different origins. The map SDK refuses any other origin with `403 FORBIDDEN`. - **Map SDK only.** A Map Application key works only with the map SDK. The Places, Routing and Traffic APIs refuse it with `403 MAP_APPLICATION_KEY_SCOPE`, so call them from your backend with a regular API key. - `language` is `mn` or `en`; anything else shows Mongolian. `TinoMaps.create` returns a Promise for the map, and the Promise rejects when the key or the origin is refused, so add a `.catch` that handles it. The rejection is an `Error` whose `status` is the HTTP status and whose `code` is the server's code, such as `FORBIDDEN` or `MAP_APPLICATIONS_BETA`. - `tino-maps.js` is for web pages. There is no Tino SDK for iOS or Android yet; for a native app, talk to [sales@tino.mn](mailto:sales@tino.mn). - Keep the map's logo and attribution visible. The script shows them by default. # Attribution and terms Wherever you show data from the Tino Maps API, show the attribution **© Tino Maps** near it: on a map, in a corner of the map; in a list, below the list. Keep any other attribution the API or the map display returns. The [Tino Maps API Terms of Use](https://maps.tino.mn/terms) are a draft under legal review and are not in force yet. In short, the draft asks you to use the API only through your own key; not to bulk-download, scrape or crawl the data, or use it to build a competing dataset or map; to cache only what serving your application needs (place ids may be stored, other content for at most 30 days); and not to resell or redistribute the data. Questions: [sales@tino.mn](mailto:sales@tino.mn).