Хурдан эхлэл
Зорилт: бүртгүүлснээс хойш 15 минутын дотор газрын зураг дэлгэцэн дээр гарах. Вэб апп-д JS SDK 3-5-р алхмыг хийнэ: түлхүүр авсны дараа газрын зураг нэг мөрөөр. Доор API-ийн шууд дуудлагууд, ямар ч хэлэнд.
1. API ажиллаж байгааг шалгах
curl https://geo.dock.mn/health
# {"status":"ok"}2. Түлхүүр авах
Үнэгүй түлхүүрийг (API key) шууд авна: dock.mn/account дээр имэйлээрээ (түлхүүр, түүнтэй арван мөр, хэрэглээний тоолуур), туршуур дээрх товчоор, эсвэл curl-ээр, {"email": ...}-тэй ч, үгүй ч:
curl -X POST https://geo.dock.mn/v1/signup
# {"key":"dk_...","prefix":"dk_01234567","plan":"free","scopes":["door:read","geocode:read","route:read","tiles:read"],...}Үнэгүй түлхүүр зөвхөн уншина: минутад 60 хүсэлт (тайлд минутын хязгаар байхгүй); өдөрт 1,000 хүсэлт, 25,000 тайл, олдоогүй 50 хаалга. Нэг хаягаас өдөрт гурван үнэгүй түлхүүр. Илүү хязгаар эсвэл changes:read хэрэгтэй бол dock-оос түншийн түлхүүр аваарай. Түлхүүр dk_ ба 32 тэмдэгттэй, зөвхөн нэг удаа харагдана, эрхтэй (scope), жишээ нь door:read. ?access_token= эсвэл Authorization: Bearer толгойгоор илгээнэ. Сервер талдаа хадгална уу.
Апп дотор түлхүүр биш, токен
Апп доторх түлхүүрийг гаргаж авч болно. Таны сервер түлхүүрээ хандалтын токеноор (OAuth2 client credentials) сольж, токеныг апп руу өгнө. Токен нэг цаг, зөвхөн таны хүссэн эрхээр ажиллана, түлхүүр шиг илгээгдэнэ.
curl -u ":$DOCK_KEY" -d grant_type=client_credentials -d "scope=door:read tiles:read" https://geo.dock.mn/v1/oauth/token
# {"access_token":"dt_...","token_type":"Bearer","expires_in":3600,"scope":"door:read tiles:read"}Түлхүүрийг биед client_secret болгон, form эсвэл JSON-оор илгээж болно. scope өгөөгүй бол токен түлхүүрийн бүх эрхийг авна. Хязгаар, өдрийн хязгаар, хэрэглээ түлхүүрийнх. Түлхүүрийг цуцлахад токенууд нь нэг минутын дотор зогсоно. Токеноор өөр токен авахгүй. Алдаа RFC 6749-ийн дагуу: invalid_request, unsupported_grant_type, invalid_scope (400), invalid_client (401), тус бүр error_description-тай. expired_token ирвэл шинийг авна.
| Төлөв | error | Утга |
|---|---|---|
| 401 | missing_key, invalid_key, revoked_key | Түлхүүргүй, танихгүй, эсвэл цуцлагдсан |
| 401 | invalid_token, expired_token | Токен танихгүй эсвэл хугацаа нь дууссан. POST /v1/oauth/token-оос шинийг авна |
| 403 | insufficient_scope | Түлхүүрт энэ замын эрх алга |
| 429 | rate_limited | Минутын хүсэлтийн хязгаар хэтэрсэн (тайлд байхгүй). Retry-After секунд хүлээнэ |
| 429 | quota_exceeded | Байгууллагын өдрийн хязгаар дууссан. Улаанбаатарын 00:00-д шинэчлэгдэнэ |
| 429 | miss_cap | Өнөөдөр олдохгүй кодын хайлт хэт олон. Улаанбаатарын 00:00-аас дахин хайна |
Түлхүүртэй хариу бүр X-Rate-Limit-Limit, X-Rate-Limit-Remaining, X-Rate-Limit-Reset (unix секунд), X-Rate-Limit-Interval (60) толгойтой.
Өдрийн хязгаар байгууллагад нэг, бүх түлхүүрт нь хамаатай, Улаанбаатарын 00:00-д (UTC 16:00) шинэчлэгдэнэ. Түншийн түлхүүрийн анхдагч: өдөрт 10,000 хүсэлт, 100,000 тайл (тайлыг тусад нь тоолно, минутын хязгааргүй), хаалга олдоогүй кодын хайлт өдөрт 200. Хариу X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset (unix секунд) толгойтой. Илүү хязгаар хэрэгтэй бол бидэнд хандана уу.
Хэрэглээгээ ямар ч түлхүүрээр харна. Энэ дуудлага үнэгүй, хязгаар дууссан ч хариу өгнө:
curl "https://geo.dock.mn/v1/usage?days=7&access_token=$DOCK_KEY"Хязгаарууд болон сүүлийн days өдөр (1-90, шинэ нь эхэндээ) тус бүрийн calls, tiles, door_misses, keys буцаана.
3. Барилгын код шалгах
Код 5 тэмдэгттэй: тоо болон гийгүүлэгч үсэг. I, L, O, U болон эгшиг ордоггүй. Кирилл гарын ижил дүрстэй үсгийг (К, М, Т, Х, Р, С, В, Н) автоматаар хөрвүүлнэ.
curl "https://geo.dock.mn/v1/door/7QSVX?access_token=$DOCK_KEY"Кодын ард зай аваад тоотоо бичвэл бүртгэлтэй бол тоотыг буцаана: 7QSVX%2017.
| Төлөв | error | Утга |
|---|---|---|
| 200 | Хаалга. | |
| 400 | invalid_code | Барилгын код биш. Шалтгаан нь message-д. |
| 404 | not_found | Ийм кодтой хаалга алга. |
| 410 | retired_code | Хаалга хасагдсан. Код дахин хэзээ ч ашиглагдахгүй. |
Хаалга буруу байвал мэдэгдээрэй. Хүн шалгаж засна, мэдэгдэл шууд юм өөрчлөхгүй.
curl -X POST "https://geo.dock.mn/v1/door/report?access_token=$DOCK_KEY" \
-H 'Content-Type: application/json' \
-d '{"kind": "wrong_location", "code": "7QSVX", "point": [106.9377, 47.9227]}'kind: wrong_location (жинхэнэ хаалганы цэг, 500 м дотор), missing (кодын заасан газар хаалга алга), duplicate (duplicate_of: нөгөө код), unmapped (кодгүй хаалга, зөвхөн point). Хариу 202. note-д утасны дугаар, нэр бичихгүй.
4. Нэрээр эсвэл цэгээр хайх
geocode:read эрхтэй түлхүүр хэрэгтэй. Кирилл, латин аль аль нь ажиллана ("Баянзүрх", "Bayanzurkh", "bayanzurh"). "3-р хороо" ба "3r khoroo" нэг. Нэг хоёр үсгийн алдааг тэвчинэ.
curl -G "https://geo.dock.mn/v1/geocode" --data-urlencode "q=Сансар А 8" -d limit=5 -d access_token=$DOCK_KEY
curl "https://geo.dock.mn/v1/reverse?lat=47.9226&lon=106.9376&radius=50&access_token=$DOCK_KEY"results хамгийн тохирох нь эхэнд (geocode), хамгийн ойр нь эхэнд (reverse). Үр дүн бүр kind-тэй: door, business, building, district, khoroo, area, street, landmark. Зөвхөн хаалга ба бүртгэлтэй бизнес code-тэй. Reverse цэгийг агуулсан дүүрэг, хороог буцаана. Хорооны полигон байхгүй бол khoroo нь null. Хүн бичиж байхад санал болгохдоо -d proximity=106.9177,47.9186 нэмнэ (lon,lat: жолооч эсвэл газрын зургийн төв): бичсэн текстээр ижил сайн эхэлсэн нэрүүдээс ойр газар эхэнд гарна. Цэг бичигдэхгүй.
Үр дүнгийн id-г хадгалаад дараа нь нэг газрыг дахин авна. Хаалга, бизнест parents нэмэгдэнэ: барилга, хороолол, гудамж, хороо, дүүргийн id.
curl "https://geo.dock.mn/v1/address/$PLACE_ID?access_token=$DOCK_KEY"| Төлөв | error | Утга |
|---|---|---|
| 200 | Үр дүн, хоосон байж болно. | |
| 400 | invalid_query | q байхгүй эсвэл 200 тэмдэгтээс урт. |
| 400 | invalid_point, invalid_radius, invalid_limit | lat -90..90, lon -180..180, radius 1..1000 м, limit 1..20. |
| 400 | invalid_proximity | geocode: proximity нь lon,lat биш (lon -180..180, lat -90..90). |
| 400 | invalid_id | address: id UUID биш. |
| 404 | not_found | address: ийм одоогийн газар алга, эсвэл хязгаарлалттай газар дотор. |
| 410 | retired | address: газар хаагдсан. id дахин ашиглагдахгүй. |
Хадгалсан газруудаа шинэчлэхдээ бүгдийг дахин татахгүй, GET /v1/changes ашиглана (changes:read, түншийн түлхүүр). Хариу нь зөвхөн id, kind, state, changed_at, хуучнаас нь эхэлнэ. state: current бол /v1/address/{id}-ээр дахин ав, retired эсвэл hidden бол устга. next null биш бол cursor=next-ээр дараагийн хуудсыг ав. Дууссаны дараа since=until-ээр дахин асуу. until бол хайлтын индексийн сүүлийн шинэчлэл (шөнө бүр). Анх удаа: since=1970-01-01T00:00:00Z.
curl "https://geo.dock.mn/v1/changes?since=2026-10-01T00:00:00Z&limit=1000&access_token=$DOCK_KEY"| Төлөв | error | Утга |
|---|---|---|
| 400 | invalid_since | since бүстэй ISO 8601 цаг биш (Z эсвэл +08:00). |
| 400 | invalid_limit, invalid_cursor | limit 1..1000; cursor өмнөх хуудасны next биш. |
| 403 | insufficient_scope | Түлхүүрт changes:read алга. |
Газар дээр очсон жолооч хаалгыг POST /v1/confirm-оор баталгаажуулна (confirm:write, түншийн түлхүүр). result: confirmed, wrong_location эсвэл missing. Хаалгыг code-оор, кодгүй хаалгыг entrance тайлын давхаргын id-гаар заана. tap бол жолоочийн газрын зураг дээр дарсан цэг; device бол утасны GPS, tap-аас 40 м дотор байна. driver бол таны өөрийн жолоочийн дугаар, утасны дугаар биш; dock зөвхөн хэшийг хадгална. Газрын зураг шууд өөрчлөгдөхгүй: confirmed хаалганы итгэлд тооцогдоно, бусдыг хүн эхлээд шалгана. Нэг цагийн дотор хаалгаас 5 м дотор дарсан confirmed хаалга ба түүний хаалгыг confidence 2 болгоно. Хоорондоо 5 м дотор, дор хаяж хоёр өөр жолооч эсвэл байгууллагын гурван ийм дарцаар 3 болно. Шинэ wrong_location эсвэл missing ирвэл дараагийн баталгаажуулалт хүртэл түвшин өсөхгүй. 5 м-ээс хол дарсан confirmed мөн түвшинг барина, wrong_location шиг шалгагдана. Цэг зөөгдөхөөс өмнөх баталгаажуулалт тооцогдохгүй.
curl -X POST "https://geo.dock.mn/v1/confirm?access_token=$DOCK_KEY" \
-H 'Content-Type: application/json' \
-d '{"result":"confirmed","code":"7QSVX","tap":[106.93763,47.92263],"device":[106.9377,47.9227],"driver":"drv-7f3a"}'| Төлөв | error | Утга |
|---|---|---|
| 200 | recorded, эсвэл already_recorded: нэг жолооч 24 цагт ижил зүйл илгээсэн. | |
| 400 | invalid_point, invalid_driver, invalid_observed_at | tap, device алга эсвэл Монголоос гадна; driver утас, имэйл шиг; observed_at 7 хоногоос өмнө. |
| 404 | not_found | Ийм кодтой хаалга эсвэл ийм id-тай хаалга алга. Олдоогүй хаалганы хязгаарт тооцогдоно. |
| 410 | retired | Хаалга эсвэл хаалга хаагдсан. Газрын зургаа дахин ачаал. |
| 422 | implausible, too_far | GPS tap-аас 40 м-ээс хол; tap хаалгаас 500 м-ээс хол (кодгүй хаалга гэж мэдээл). |
5. Вектор тайл
tiles:read эрхтэй түлхүүр хэрэгтэй. Эх үүсвэр: building (zoom 13..22), entrance (zoom 15..22). Хязгаарлалттай газрын доторх юу ч тайлд орохгүй.
curl "https://geo.dock.mn/v1/tiles/building?access_token=$DOCK_KEY" # TileJSON
curl -o t.pbf "https://geo.dock.mn/v1/tiles/building/15/26116/11401?access_token=$DOCK_KEY"MapLibre-д TileJSON хаягийг вектор эх үүсвэр болгож өгнө. Тайлын хаягууд таны түлхүүрийг агуулна. Тайл бүр түлхүүрийн хязгаарт нэг хүсэлтээр тоологдоно.
| Төлөв | error | Утга |
|---|---|---|
| 200 | Тайл, application/x-protobuf. | |
| 204 | Хоосон тайл. | |
| 400 | invalid_tile | z 0..22, x, y 0..2^z - 1. |
| 404 | not_found | Ийм эх үүсвэр байхгүй. |
Хариуны дүрэм
official_addressэхэнд,codeдараа нь.official_statusньmatchedбиш болunofficial: true. Таны апп "албан бус" гэж харуулах ёстой.- Эзэмшигч, утасны дугаар хэзээ ч буцаахгүй. Хаалга бол газрын шинж чанар.