API Sənədləri və Playground

Test Key:YOUR_API...

Giriş

OSRMRoute Directions API, tətbiqlərinizə sürətli, yüksək performanslı coğrafi marşrutlaşdırma, səyahət matrisləri, ünvan axtarışı (geocoding) və marşrut optimallaşdırma imkanları inteqrasiya etmək üçün yaradılmış RESTful veb xidmətidir. Bu sənədlərdə API-nin bütün imkanları, parametrləri və inteqrasiya addımları detallı şəkildə izah edilmişdir.

Autentifikasiya

OSRMRoute API sorğuları autentifikasiya üçün unikal API Açarından istifadə edir. API açarınızı hər bir sorğuya query parametri kimi (?key=YOUR_KEY) və ya HTTP Authorization başlığı vasitəsilə (Bearer token kimi) əlavə edə bilərsiniz.

GETAny endpoint

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
key	string	Məcburi	-	Şəxsi idarəetmə panelinizdən əldə etdiyiniz unikal API açarı. Bu açar sorğularınızın limitini müəyyən edir.

Xəta Kodları

OSRMRoute, sorğunun vəziyyətini bildirmək üçün standart HTTP status kodlarından və ətraflı JSON xəta mesajlarından istifadə edir.

Cavab Strukturunun Şərhi

Əsas status kodları və onların şərhi: - **200 OK**: Sorğu uğurla yerinə yetirildi. - **400 Bad Request**: Parametrlər yanlışdır və ya çatışmır. - **401 Unauthorized**: API açarı təqdim olunmayıb və ya etibarsızdır. - **403 Forbidden**: API açarı bloklanıb və ya aktiv deyil. - **429 Too Many Requests**: Günlük kredit limiti aşıldı. - **500 Internal Error**: Sistem daxili xəta baş verdi.

Routing API

A nöqtəsindən B nöqtəsinə (və aralıq via-nöqtələrlə) ən sürətli və ən qısa marşrutu hesablayır. Fərqli nəqliyyat profilləri (driving, cycling, walking) üçün dönmə təlimatları (turn-by-turn) və GeoJSON həndəsəsini qaytarır.

GET/api/v1/osrm/route/v1/{profile}/{coordinates}

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
profile	string	Məcburi	driving	Nəqliyyat növü profili. Dəstəklənən dəyərlər: driving (avtomobil), cycling (velosiped), walking (piyada).
coordinates	string	Məcburi	-	Nöqtələrin koordinatları. Format: lon,lat;lon,lat;lon,lat... (ən azı 2 nöqtə).
overview	string	Könüllü	full	Qayıdan marşrut həndəsəsinin detalı: simplified (sadələşdirilmiş), full (tam həndəsə), false (həndəsəsiz).
geometries	string	Könüllü	geojson	Həndəsə formatı: geojson (GeoJSON obyekt), polyline (kodlaşdırılmış sətir).
steps	boolean	Könüllü	true	Hər dönmə nöqtəsi üçün addım-addım təlimatların qaytarılıb-qaytarılmaması.

Cavab Strukturunun Şərhi

Uğurlu cavab marşrutun ümumi məsafəsini (metrlə), səyahət müddətini (saniyə ilə), keçid nöqtələrini və GeoJSON marşrut xəttini ehtiva edir.

Matrix API

Çoxlu nöqtələr arasında sürətli məsafə və səyahət müddəti matrisi hesablayır (NxM cədvəl). Logistika marşrutlarının optimallaşdırılması üçün ideal alətdir.

GET/api/v1/osrm/table/v1/{profile}/{coordinates}

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
profile	string	Məcburi	driving	Nəqliyyat profili (driving, cycling, walking).
coordinates	string	Məcburi	-	Matris nöqtələri. Format: lon,lat;lon,lat;lon,lat...
annotations	string	Könüllü	duration,distance	Hesablanacaq məlumat: duration (vaxt), distance (məsafə) və ya hər ikisi.

Cavab Strukturunun Şərhi

Uğurlu cavab hər bir başlanğıc və son nöqtə kombinasiyası üçün ikiölçülü distances (məsafələr) və durations (müddətlər) matris cədvəlini qaytarır.

Map Matching API

Dəqiq olmayan GPS izlərini real yol şəbəkəsinə uyğunlaşdırır (snap to road). GPS siqnallarındakı yayınmaları təmizləmək üçün istifadə olunur.

GET/api/v1/osrm/match/v1/{profile}/{coordinates}

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
profile	string	Məcburi	driving	Nəqliyyat profili.
coordinates	string	Məcburi	-	Yola uyğunlaşdırılacaq (snap ediləcək) GPS koordinatlarının ardıcıllığı (lon,lat;lon,lat...)
overview	string	Könüllü	full	Uyğunlaşdırılmış marşrutun həndəsə dəqiqliyi.

Nearest API

İstənilən koordinatı ona ən yaxın olan real yol seqmentinə bağlayır (snap) və yolun adı haqqında məlumat qaytarır.

GET/api/v1/osrm/nearest/v1/{profile}/{coordinates}

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
profile	string	Məcburi	driving	Nəqliyyat profili.
coordinates	string	Məcburi	-	Yaxınlığı axtarılan nöqtə. Format: lon,lat (tək cüt).
number	integer	Könüllü	3	Tapılacaq ən yaxın yol namizədlərinin sayı.

Trip API

Səyyah Satıcı Problemini (TSP) həll edir: Verilmiş nöqtələr ardıcıllığını gəzmək üçün ən optimal dairəvi (və ya açıq) marşrutu tapır və nöqtələri sıralayır.

GET/api/v1/osrm/trip/v1/{profile}/{coordinates}

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
profile	string	Məcburi	driving	Nəqliyyat profili.
coordinates	string	Məcburi	-	Gəziləcək nöqtələr. Format: lon,lat;lon,lat...
source	string	Könüllü	any	Marşrutun başlaya biləcəyi nöqtə (any və ya birinci nöqtə).
destination	string	Könüllü	any	Marşrutun bitəcəyi nöqtə (any və ya sonuncu nöqtə).

Directions API

İki və ya daha çox nöqtə arasında addım-addım naviqasiya qaytarır — təmiz təlimat siyahısı ilə (mətn, məsafə, müddət, manevr növü və koordinat). Avtomobil, velosiped və piyada, həmçinin bir sorğuda 3-ə qədər alternativ marşrutu dəstəkləyir.

GET/api/1/directions

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
point	string	Məcburi	lat,lng	Nöqtə: lat,lng. Hər dayanacaq üçün parametri təkrarlayın (minimum 2).
profile	string	Könüllü	driving	Hərəkət növü: driving, cycling və ya walking.
alternatives	integer	Könüllü	0	Əlavə qaytarılacaq alternativ marşrutların sayı (0–3).
lang	string	Könüllü	en	Təlimat mətninin dil kodu.

Cavab Strukturunun Şərhi

{ code, profile, routes[], waypoints[] } qaytarır. Hər marşrutda distance (m), duration (san), GeoJSON həndəsə və instructions[] massivi var; hər təlimat text, type, modifier, distance, duration, name və [lat,lng] location daxil edir.

Snap to Road API

Xam, qeyri-dəqiq GPS nöqtələrini yol şəbəkəsindəki ən yaxın mövqeyə yapışdırır. Hər koordinat üçün point parametrini təkrarlayın (100-ə qədər).

GET/api/1/snap

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
point	string	Məcburi	lat,lng	GPS nöqtəsi: lat,lng. Hər nöqtə üçün parametri təkrarlayın (maksimum 100).
profile	string	Könüllü	driving	Yapışdırılacaq yol şəbəkəsi: driving, cycling və ya walking.

Cavab Strukturunun Şərhi

{ code, profile, snapped[] } qaytarır. Hər element orijinal input [lat,lng], yapışdırılmış [lat,lng] mövqe, metrlə yapışma məsafəsi və yol adını daxil edir.

Geocoding API

Axtarış mətnini coğrafi koordinatlara (forward) və ya koordinatları ünvana (reverse) çevirir. Sürətli, səhv-yazılışa dözümlü autocomplete — küçələr, ünvanlar və maraq obyektlərini (kafe, mağaza, otel, ofis) əhatə edir. Yazdıqca axtarış üçün idealdır.

GET/api/1/geocode

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
q	string	Məcburi	-	Axtarılan ünvan (məs: "Nizami küçəsi, Bakı").
reverse	boolean	Könüllü	false	Əks geocoding (koordinatdan ünvana axtarış) etmək üçün true olmalıdır.
point	string	Könüllü	lat,lng	Ünvana çevirmək üçün koordinat (lat,lng). reverse=true olduqda tələb olunur.
limit	integer	Könüllü	5	Qaytarılacaq nəticələrin maksimum sayı (1–20, defolt 5).
lang	string	Könüllü	en	Nəticə adları üçün üstün tutulan dil (məs. en, az, ru). Defolt en.
lat	number	Könüllü	-	Nəticələri yaxınlaşdırmaq üçün en dairəsi (yaxın nəticələr öndə). lon ilə birlikdə.
lon	number	Könüllü	-	Nəticələri yaxınlaşdırmaq üçün uzunluq dairəsi. lat ilə birlikdə.
bbox	string	Könüllü	-	Nəticələri sərhəd qutusu ilə məhdudlaşdır: minLon,minLat,maxLon,maxLat.
osm_tag	string	Könüllü	-	OSM teqinə görə filtr, məs. place (yaşayış məntəqələri) və ya amenity:cafe. İstisna üçün ! önləməsi.
city	string	Könüllü	-	Bu şəhərdəki nəticələri yuxarı çıxar (məs. Bakı), qalanlarını gizlətmədən.
elastic	boolean	Könüllü	true	Elastik (fuzzy, yüksək əhatə) axtarış — defolt true. Səhvlərə, çatışmayan diakritikaya (ə↔e), söz sırasına, ümumi sözlərə (metro, rayonu) və ev nömrələrinə dözümlüdür. Dəqiq uyğunluq üçün false verin.

Nümunələr

# Məkana yönləndir, yalnız yaşayış məntəqələri
GET /api/1/geocode?q=qala&lat=40.41&lon=49.87&osm_tag=place&key=YOUR_KEY

# Bir şəhəri yuxarı prioritetlə
GET /api/1/geocode?q=market&city=Bakı&key=YOUR_KEY

# Reverse geocode (koordinatdan ünvana)
GET /api/1/geocode?reverse=true&point=40.409,49.867&key=YOUR_KEY

Yerlər (Yaxın POI)

Bir nöqtənin yaxınlığındakı obyektləri tap — kafe, mağaza, otel, bankomat, aptek və s. — kateqoriya və radiusa görə süzülmüş, məsafəyə görə sıralı.

GET/api/1/places

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
point	string	Məcburi	lat,lng	Ətrafında axtarılacaq mərkəz koordinatı lat,lng (tələb olunur).
radius	number	Könüllü	1	Axtarış radiusu kilometrlə (0.05–20, defolt 1).
category	string	Könüllü	-	OSM teq filtri, məs. amenity:cafe, shop, tourism:hotel. İstisna üçün !. Boş = bütün POI-lər.
limit	integer	Könüllü	10	Maksimum nəticə (1–50, defolt 10).
lang	string	Könüllü	en	Adlar üçün üstün tutulan dil (məs. en, az, ru).

Autocomplete API

İstifadəçi yazdıqca sürətli, səhvə dözümlü ünvan təklifləri (məkan meyli ilə).

GET/api/1/autocomplete

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
q	string	Məcburi	-	Axtarış mətni — natamam giriş də olar.
limit	integer	Könüllü	8	Qaytarılacaq maksimum təklif sayı (1–15).
lang	string	Könüllü	en	Nəticə etiketləri üçün dil kodu.
lat	number	Könüllü	-	Nəticələri yönləndirmək üçün en dairəsi (opsional).
lon	number	Könüllü	-	Nəticələri yönləndirmək üçün uzunluq dairəsi (opsional).
osm_tag	string	Könüllü	-	Təklifləri OSM növünə görə süz, məs. place:city.

Cavab Strukturunun Şərhi

{ suggestions[], took } qaytarır. Hər təklif label, name, city, state, country, countrycode, type, osm_id və point {lat,lng} daxil edir.

Batch Geocoding API

Yüzlərlə ünvanı bir sorğuda geocode edin — data prosesləri və importlar üçün ideal.

POST/api/1/geocode/batch

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
queries	array	Məcburi	[]	Geocode ediləcək ünvan sətirləri massivi (maks 100).
lang	string	Könüllü	en	Nəticə etiketləri üçün dil kodu.
limit	integer	Könüllü	1	Hər sorğu üçün maksimum uyğunluq sayı (1–5).

Cavab Strukturunun Şərhi

{ results[], count, took } qaytarır. Hər nəticə giriş query-ni hits[] massivi ilə cütləşdirir; hər uyğunluq label, city, country və point {lat,lng} daxil edir. Nəticələr giriş ardıcıllığını saxlayır.

Timezone API

Yer üzündə istənilən koordinat üçün IANA saat qurşağı, cari UTC ofset, DST statusu və yerli vaxt.

GET/api/1/timezone

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
point	string	Məcburi	lat,lng	Koordinat: lat,lng.
lat	number	Könüllü	-	En dairəsi (point əvəzinə).
lon	number	Könüllü	-	Uzunluq dairəsi (point əvəzinə).
timestamp	integer	Könüllü	now	Ofsetin hesablanacağı Unix vaxtı (saniyə) və ya ISO tarix; defolt indi.

Cavab Strukturunun Şərhi

{ timezone, point, utc_offset, utc_offset_seconds, dst, abbreviation, local_time, utc_time } qaytarır. utc_offset +HH:MM sətiridir, yay vaxtı aktivdirsə dst true olur, local_time isə qurşaq ofseti ilə ISO vaxt möhürüdür.

Elevation API

İstənilən koordinat üçün dəniz səviyyəsindən yüksəklik (metr) — bir nöqtə və ya bütöv marşrut profili.

GET/api/1/elevation

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
point	string	Məcburi	lat,lng	Koordinat: lat,lng. Hər nöqtə üçün təkrarlayın (GET-də 100-ə qədər).

Cavab Strukturunun Şərhi

{ results[], unit:"meters" } qaytarır; hər nəticə { point:{lat,lng}, elevation }. elevation dəniz səviyyəsindən metrdir (naməlumdursa null, dənizdə 0). Tək nöqtə üçün yuxarı səviyyədə elevation da daxil edilir. Böyük toplular üçün POST { points:[[lat,lng],...] } (1000-ə qədər).

Boundary Lookup API

Koordinatın hansı ölkə, əyalət, şəhər və rayona düşdüyünü tapın — istəyə görə sərhəd poliqonu ilə.

GET/api/1/boundary

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
point	string	Məcburi	lat,lng	Koordinat: lat,lng.
polygon	boolean	Könüllü	false	Sərhədi GeoJSON kimi də qaytarmaq üçün true.
lang	string	Könüllü	en	Yer adları üçün dil kodu.

Cavab Strukturunun Şərhi

{ point, display_name, country, countrycode, state, county, city, district, postcode, osm_id, osm_type } qaytarır və polygon=true olduqda GeoJSON sərhəd həndəsəsi.

Geofencing API

Bir sorğuda hər nöqtənin hansı zonalarınıza düşdüyünü yoxlayın — poliqon və ya dairəvi hasarlar.

POST/api/1/geofence

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
fences	array	Məcburi	[]	Hasarlar massivi: { id?, polygon:[[lat,lng],...] } və ya { id?, center:[lat,lng], radius_m }. 100-ə qədər.
points	array	Məcburi	[]	Yoxlanacaq [lat,lng] nöqtələri massivi (1000-ə qədər).

Cavab Strukturunun Şərhi

{ results[], count } qaytarır. Hər nəticə { point:{lat,lng}, inside:[fenceId,...] } — nöqtənin düşdüyü bütün hasarları sadalayır (heç biri yoxdursa boş).

Elevation Profile API

Yolun hər nöqtəsində yüksəklik + ümumi dırmanma, eniş və məsafə — tam marşrut profili.

POST/api/1/elevation/profile

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
points	array	Məcburi	[]	Yolu təşkil edən [lat,lng] nöqtələri massivi (>=2, 2000-ə qədər).
polyline	string	Könüllü	-	points əvəzinə encoded polyline.

Cavab Strukturunun Şərhi

{ profile[], total_ascent, total_descent, min_elevation, max_elevation, distance, unit } qaytarır. Hər element { point, elevation, distance } (metr).

Solar API

İstənilən koordinat və tarix üçün gündoğumu, günbatımı, toran, solar noon və gün uzunluğu.

GET/api/1/solar

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
point	string	Məcburi	lat,lng	Koordinat: lat,lng.
date	string	Könüllü	today	Vaxtların hesablanacağı tarix (YYYY-MM-DD); defolt bu gün.

Cavab Strukturunun Şərhi

{ point, date, sunrise, sunset, solar_noon, dawn, dusk, golden_hour, night_start, night_end, day_length_seconds } qaytarır. Vaxtlar UTC ISO; qütb gecə/gündüzündə null.

Geometry Utilities API

Məsafə, bearing, sahə, mərkəz, sadələşdirmə və polyline encode/decode — məkan riyaziyyatı xidmət kimi.

POST/api/1/geometry

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
op	string	Məcburi	distance	Əməliyyat: distance, bearing, destination, midpoint, length, area, centroid, simplify, polyline_encode və ya polyline_decode.
from	array	Könüllü	[lat,lng]	Başlanğıc nöqtə [lat,lng].
to	array	Könüllü	[lat,lng]	Son nöqtə [lat,lng].
path	array	Könüllü	[]	[lat,lng] massivi (length/simplify/polyline_encode üçün).
polygon	array	Könüllü	[]	[lat,lng] halqası (area üçün).

Cavab Strukturunun Şərhi

{ op, ... } qaytarır — seçilmiş əməliyyatın nəticəsi ilə, məs. { distance, unit }, { bearing_deg }, { point }, { area, unit }, { path } və ya { polyline }.

Coordinate Conversion API

Enlik/uzunluğu UTM və MGRS grid işarələrinə və əksinə çevir.

GET/api/1/convert

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
point	string	Məcburi	lat,lng	UTM/MGRS-ə çevriləcək koordinat: lat,lng.
mgrs	string	Könüllü	-	Koordinata geri çevriləcək MGRS sətiri.

Cavab Strukturunun Şərhi

{ point, mgrs, utm:{ zone, band, easting, northing, hemisphere } } qaytarır. mgrs= verildikdə { mgrs, point }.

Country Info API

İstənilən ölkə üçün valyuta, telefon kodu, dillər, paytaxt və bayraq — ISO kod və ya ad ilə.

GET/api/1/country

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
code	string	Məcburi	AZ	ISO 3166 alpha-2 və ya alpha-3 ölkə kodu (məs. AZ və ya AZE).
name	string	Könüllü	-	Kod əvəzinə ölkə adı.

Cavab Strukturunun Şərhi

{ name, official_name, cca2, cca3, capital, region, subregion, currency:{code,name,symbol}, calling_code, languages[], flag, latlng, population } qaytarır.

Isochrone API

Müəyyən edilmiş nöqtədən müəyyən edilmiş vaxt və ya məsafədə çatılması mümkün olan coğrafi zonaların poliqonlarını qaytarır.

GET/api/1/isochrone

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
point	string	Məcburi	-	Mərkəz nöqtə. Format: lat,lon.
time_limit	integer	Könüllü	600	Səyahət vaxt limiti (saniyə ilə).

Route Optimization API

Nəqliyyat donanmasının marşrutlarını optimallaşdırır (Vehicle Routing Problem). Avtomobillərin yükdaşıma, çatdırılma planını ən az xərclə hesablayır.

POST/api/1/vrp

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
vehicles	array	Məcburi	[]	Nəqliyyat vasitələrinin siyahısı — hər biri id, ixtiyari tutum və başlanğıc nöqtəsi ilə; nöqtə [lon, lat] massividir (əvvəl uzunluq).
services	array	Məcburi	[]	Xidmət göstəriləcək dayanacaqlar — hər biri id, [lon, lat] massivi kimi nöqtə (əvvəl uzunluq) və ixtiyari xidmət müddəti ilə. Koordinat sırası bütün digər endpoint-lərimizlə eynidir.

Location Clustering API

Verilmiş koordinatları coğrafi yaxınlıqlarına və sıxlıqlarına görə qruplaşdırır (klasterlərə ayırır).

POST/api/1/cluster

Parametrlər (Query Params)

Parametr	Tip	Status	Default	Təsvir
customers	array	Məcburi	[]	Klasterləşdiriləcək müştəri koordinatları və çəkiləri.

Rəsmi SDK-lar

Sıfır asılılıq, tam tipli, bütün endpointlər. İlk sorğunu bir dəqiqədən az vaxtda at.

osrmrouteosrmrouteSDK-lara bax