API Dokümantasyonu ve Playground

Test Anahtarı:YOUR_API...

Giriş

OSRMRoute Directions API, uygulamalarınıza hızlı, yüksek performanslı coğrafi rotalama, seyahat matrisleri, adres arama (geocoding) ve rota optimizasyonu entegre etmek için oluşturulmuş RESTful bir web hizmetidir. Bu dokümantasyonda API'nin tüm yetenekleri, parametreleri ve entegrasyon adımları ayrıntılı olarak açıklanmıştır.

Kimlik Doğrulama

OSRMRoute API istekleri kimlik doğrulama için benzersiz bir API anahtarı kullanır. API anahtarınızı her isteğe sorgu parametresi olarak (?key=YOUR_KEY) veya HTTP Authorization başlığı aracılığıyla (Bearer token olarak) ekleyebilirsiniz.

GETAny endpoint

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
key	string	Zorunlu	-	Kişisel panelinizden edindiğiniz benzersiz API anahtarı. Bu anahtar isteklerinizin limitlerini belirler.

Hata Kodları

OSRMRoute, bir isteğin durumunu belirtmek için standart HTTP durum kodları ve ayrıntılı JSON hata mesajları kullanır.

Yanıt Yapısının Açıklaması

Başlıca durum kodları ve anlamları: - **200 OK**: İstek başarıyla tamamlandı. - **400 Bad Request**: Parametreler geçersiz veya eksik. - **401 Unauthorized**: API anahtarı sağlanmadı veya geçersiz. - **403 Forbidden**: API anahtarı engellenmiş veya etkin değil. - **429 Too Many Requests**: Günlük kredi limiti aşıldı. - **500 Internal Error**: Dahili bir sistem hatası oluştu.

Routing API

A noktasından B noktasına (ve ara via-noktalarıyla) en hızlı ve en kısa rotayı hesaplar. Farklı ulaşım profilleri (driving, cycling, walking) için adım adım (turn-by-turn) talimatlar ve GeoJSON geometrisi döndürür.

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

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
profile	string	Zorunlu	driving	Ulaşım türü profili. Desteklenen değerler: driving (otomobil), cycling (bisiklet), walking (yaya).
coordinates	string	Zorunlu	-	Noktaların koordinatları. Biçim: lon,lat;lon,lat;lon,lat... (en az 2 nokta).
overview	string	İsteğe bağlı	full	Döndürülen rota geometrisinin ayrıntı düzeyi: simplified (sadeleştirilmiş), full (tam geometri), false (geometrisiz).
geometries	string	İsteğe bağlı	geojson	Geometri biçimi: geojson (GeoJSON nesnesi), polyline (kodlanmış dize).
steps	boolean	İsteğe bağlı	true	Her dönüş için adım adım talimatların döndürülüp döndürülmeyeceği.

Yanıt Yapısının Açıklaması

Başarılı yanıt; rotanın toplam mesafesini (metre cinsinden), seyahat süresini (saniye cinsinden), geçiş noktalarını ve GeoJSON rota çizgisini içerir.

Matrix API

Birden fazla nokta arasında hızlı bir mesafe ve seyahat süresi matrisi hesaplar (NxM tablosu). Lojistik rotalarını optimize etmek için ideal bir araçtır.

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

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
profile	string	Zorunlu	driving	Ulaşım profili (driving, cycling, walking).
coordinates	string	Zorunlu	-	Matris noktaları. Biçim: lon,lat;lon,lat;lon,lat...
annotations	string	İsteğe bağlı	duration,distance	Hesaplanacak veri: duration (süre), distance (mesafe) veya her ikisi.

Yanıt Yapısının Açıklaması

Başarılı yanıt, her başlangıç ve bitiş noktası kombinasyonu için iki boyutlu bir distances (mesafeler) ve durations (süreler) matris tablosu döndürür.

Map Matching API

Hatalı GPS izlerini gerçek yol ağına hizalar (snap to road). GPS sinyallerindeki gürültüyü temizlemek için kullanılır.

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

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
profile	string	Zorunlu	driving	Ulaşım profili.
coordinates	string	Zorunlu	-	Hizalanacak GPS koordinatları dizisi (lon,lat;lon,lat...)
overview	string	İsteğe bağlı	full	Hizalanan rotanın geometri hassasiyeti.

Nearest API

Herhangi bir koordinatı en yakın gerçek yol segmentine hizalar (snap) ve yol adı hakkında bilgi döndürür.

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

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
profile	string	Zorunlu	driving	Ulaşım profili.
coordinates	string	Zorunlu	-	Yakınında arama yapılacak nokta. Biçim: lon,lat (tek çift).
number	integer	İsteğe bağlı	3	Bulunacak en yakın yol adaylarının sayısı.

Trip API

Gezgin Satıcı Problemini (TSP) çözer: Verilen nokta kümesini ziyaret etmek için en optimal döngüsel (veya açık) rotayı bulur ve noktaları sıralar.

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

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
profile	string	Zorunlu	driving	Ulaşım profili.
coordinates	string	Zorunlu	-	Ziyaret edilecek noktalar. Biçim: lon,lat;lon,lat...
source	string	İsteğe bağlı	any	Rotanın başlayabileceği nokta (any veya ilk nokta).
destination	string	İsteğe bağlı	any	Rotanın biteceği nokta (any veya son nokta).

Directions API

İki veya daha fazla nokta arasında adım adım navigasyon döndürür — temiz bir talimat listesiyle (metin, mesafe, süre, manevra türü ve konum). Araç, bisiklet ve yayanın yanı sıra tek çağrıda 3’e kadar alternatif rota destekler.

GET/api/1/directions

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
point	string	Zorunlu	lat,lng	Nokta: lat,lng. Her durak için parametreyi tekrarlayın (en az 2).
profile	string	İsteğe bağlı	driving	Ulaşım türü: driving, cycling veya walking.
alternatives	integer	İsteğe bağlı	0	Ayrıca döndürülecek alternatif rota sayısı (0–3).
lang	string	İsteğe bağlı	en	Talimat metni için dil kodu.

Yanıt Yapısının Açıklaması

{ code, profile, routes[], waypoints[] } döndürür. Her rotada distance (m), duration (sn), GeoJSON geometri ve instructions[] dizisi vardır; her talimat text, type, modifier, distance, duration, name ve [lat,lng] location içerir.

Snap to Road API

Ham, hatalı GPS noktalarını yol ağındaki en yakın konuma yapıştırır. Her koordinat için point parametresini tekrarlayın (en fazla 100).

GET/api/1/snap

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
point	string	Zorunlu	lat,lng	GPS noktası: lat,lng. Her nokta için parametreyi tekrarlayın (en fazla 100).
profile	string	İsteğe bağlı	driving	Yapıştırılacak yol ağı: driving, cycling veya walking.

Yanıt Yapısının Açıklaması

{ code, profile, snapped[] } döndürür. Her öğe orijinal input [lat,lng], yapıştırılmış [lat,lng] konum, metre cinsinden yapışma mesafesi ve yol adını içerir.

Geocoding API

Bir arama metnini coğrafi koordinatlara (ileri) veya koordinatları bir adrese (ters) dönüştürür. Sokakları, adresleri ve ilgi noktalarını (kafe, mağaza, otel, ofis) kapsayan hızlı, yazım hatasına toleranslı otomatik tamamlama. Yazarken arama için idealdir.

GET/api/1/geocode

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
q	string	Zorunlu	-	Aranacak adres (örn: "Nizami Caddesi, Bakü").
reverse	boolean	İsteğe bağlı	false	Ters geocoding (koordinattan adrese arama) yapmak için true olmalıdır.
point	string	İsteğe bağlı	lat,lng	Adrese çevirmek için koordinat (lat,lng). reverse=true olduğunda gereklidir.
limit	integer	İsteğe bağlı	5	Döndürülecek maksimum sonuç sayısı (1–20, varsayılan 5).
lang	string	İsteğe bağlı	en	Sonuç adları için tercih edilen dil (ör. en, az, ru). Varsayılan en.
lat	number	İsteğe bağlı	-	Sonuçları yönlendirmek için enlem (yakınlar önce). lon ile birlikte.
lon	number	İsteğe bağlı	-	Sonuçları yönlendirmek için boylam. lat ile birlikte.
bbox	string	İsteğe bağlı	-	Sonuçları sınırlayıcı kutuyla kısıtla: minLon,minLat,maxLon,maxLat.
osm_tag	string	İsteğe bağlı	-	OSM etiketine göre filtrele, örn. place (yerleşimler) veya amenity:cafe. Hariç tutmak için ! öneki.
city	string	İsteğe bağlı	-	Bu şehirdeki sonuçları üste çıkar (ör. Bakı), diğerlerini gizlemeden.
elastic	boolean	İsteğe bağlı	true	Esnek (bulanık, yüksek kapsam) arama — varsayılan true. Yazım hatalarına, eksik diyakritiklere (ə↔e), sözcük sırasına, genel sözcüklere (metro, rayonu) ve kapı numaralarına toleranslıdır. Katı eşleşme için false.

Örnekler

# Bir konuma yönlendir, yalnızca yerleşimler
GET /api/1/geocode?q=qala&lat=40.41&lon=49.87&osm_tag=place&key=YOUR_KEY

# Bir şehri üste önceliklendir
GET /api/1/geocode?q=market&city=Bakı&key=YOUR_KEY

# Ters geocode (koordinattan adrese)
GET /api/1/geocode?reverse=true&point=40.409,49.867&key=YOUR_KEY

Yerler (Yakın POI)

Bir konumun yakınındaki ilgi noktalarını bul — kafeler, mağazalar, oteller, ATMler, eczaneler ve daha fazlası — kategori ve yarıçapa göre süzülmüş, mesafeye göre sıralı.

GET/api/1/places

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
point	string	Zorunlu	lat,lng	Aranacak merkez koordinatı lat,lng (gerekli).
radius	number	İsteğe bağlı	1	Kilometre cinsinden arama yarıçapı (0.05–20, varsayılan 1).
category	string	İsteğe bağlı	-	OSM etiket filtresi, ör. amenity:cafe, shop, tourism:hotel. Hariç tutmak için !. Boş = tüm POIler.
limit	integer	İsteğe bağlı	10	Maks. sonuç (1–50, varsayılan 10).
lang	string	İsteğe bağlı	en	Adlar için tercih edilen dil (ör. en, az, ru).

Autocomplete API

Kullanıcı yazarken hızlı, yazım hatasına toleranslı yer önerileri (konum ağırlığı ile).

GET/api/1/autocomplete

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
q	string	Zorunlu	-	Arama metni — kısmi giriş olabilir.
limit	integer	İsteğe bağlı	8	Döndürülecek maksimum öneri sayısı (1–15).
lang	string	İsteğe bağlı	en	Sonuç etiketleri için dil kodu.
lat	number	İsteğe bağlı	-	Sonuçları ağırlıklandırmak için enlem (opsiyonel).
lon	number	İsteğe bağlı	-	Sonuçları ağırlıklandırmak için boylam (opsiyonel).
osm_tag	string	İsteğe bağlı	-	Önerileri OSM türüne göre filtrele, örn. place:city.

Yanıt Yapısının Açıklaması

{ suggestions[], took } döndürür. Her öneri label, name, city, state, country, countrycode, type, osm_id ve point {lat,lng} içerir.

Batch Geocoding API

Yüzlerce adresi tek istekte coğrafi kodlayın — veri hatları ve içe aktarmalar için ideal.

POST/api/1/geocode/batch

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
queries	array	Zorunlu	[]	Coğrafi kodlanacak adres dizisi (maks 100).
lang	string	İsteğe bağlı	en	Sonuç etiketleri için dil kodu.
limit	integer	İsteğe bağlı	1	Sorgu başına maksimum eşleşme sayısı (1–5).

Yanıt Yapısının Açıklaması

{ results[], count, took } döndürür. Her sonuç giriş sorgusunu hits[] dizisiyle eşleştirir; her eşleşme label, city, country ve point {lat,lng} içerir. Sonuçlar giriş sırasını korur.

Timezone API

Dünyadaki herhangi bir koordinat için IANA saat dilimi, güncel UTC farkı, DST durumu ve yerel saat.

GET/api/1/timezone

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
point	string	Zorunlu	lat,lng	Koordinat: lat,lng.
lat	number	İsteğe bağlı	-	Enlem (point yerine).
lon	number	İsteğe bağlı	-	Boylam (point yerine).
timestamp	integer	İsteğe bağlı	now	Farkın çözüleceği Unix zamanı (saniye) veya ISO tarih; varsayılan şimdi.

Yanıt Yapısının Açıklaması

{ timezone, point, utc_offset, utc_offset_seconds, dst, abbreviation, local_time, utc_time } döndürür. utc_offset bir +HH:MM dizesidir, yaz saati aktifse dst true olur, local_time ise dilim farkıyla ISO zaman damgasıdır.

Elevation API

Herhangi bir koordinat için deniz seviyesinden yükseklik (metre) — tek nokta ya da tüm rota profili.

GET/api/1/elevation

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
point	string	Zorunlu	lat,lng	Koordinat: lat,lng. Her nokta için tekrarlayın (GET’te en fazla 100).

Yanıt Yapısının Açıklaması

{ results[], unit:"meters" } döndürür; her sonuç { point:{lat,lng}, elevation }. elevation deniz seviyesinden metredir (bilinmiyorsa null, denizde 0). Tek nokta için üst düzeyde elevation da bulunur. Büyük yığınlar için POST { points:[[lat,lng],...] } (1000’e kadar).

Boundary Lookup API

Bir koordinatın hangi ülke, eyalet, şehir ve ilçeye düştüğünü bulun — istenirse sınır poligonuyla.

GET/api/1/boundary

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
point	string	Zorunlu	lat,lng	Koordinat: lat,lng.
polygon	boolean	İsteğe bağlı	false	Sınırı GeoJSON olarak da döndürmek için true.
lang	string	İsteğe bağlı	en	Yer adları için dil kodu.

Yanıt Yapısının Açıklaması

{ point, display_name, country, countrycode, state, county, city, district, postcode, osm_id, osm_type } döndürür ve polygon=true olduğunda GeoJSON sınır geometrisi.

Geofencing API

Tek çağrıda her noktanın hangi bölgelerinize düştüğünü test edin — poligon veya dairesel çitler.

POST/api/1/geofence

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
fences	array	Zorunlu	[]	Çit dizisi: { id?, polygon:[[lat,lng],...] } veya { id?, center:[lat,lng], radius_m }. En fazla 100.
points	array	Zorunlu	[]	Test edilecek [lat,lng] noktaları dizisi (en fazla 1000).

Yanıt Yapısının Açıklaması

{ results[], count } döndürür. Her sonuç { point:{lat,lng}, inside:[fenceId,...] } — noktanın düştüğü tüm çitleri listeler (yoksa boş).

Elevation Profile API

Yolun her noktasında yükseklik + toplam tırmanma, iniş ve mesafe — tam rota profili.

POST/api/1/elevation/profile

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
points	array	Zorunlu	[]	Yolu oluşturan [lat,lng] noktaları dizisi (>=2, en fazla 2000).
polyline	string	İsteğe bağlı	-	points yerine kodlanmış polyline.

Yanıt Yapısının Açıklaması

{ profile[], total_ascent, total_descent, min_elevation, max_elevation, distance, unit } döndürür. Her öğe { point, elevation, distance } (metre).

Solar API

Herhangi bir koordinat ve tarih için gün doğumu, gün batımı, alacakaranlık, öğle ve gün uzunluğu.

GET/api/1/solar

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
point	string	Zorunlu	lat,lng	Koordinat: lat,lng.
date	string	İsteğe bağlı	today	Sürelerin hesaplanacağı tarih (YYYY-MM-DD); varsayılan bugün.

Yanıt Yapısının Açıklaması

{ point, date, sunrise, sunset, solar_noon, dawn, dusk, golden_hour, night_start, night_end, day_length_seconds } döndürür. Süreler UTC ISO; kutup gece/gündüzünde null.

Geometry Utilities API

Mesafe, kerteriz, alan, merkez, sadeleştirme ve polyline encode/decode — mekânsal matematik servis olarak.

POST/api/1/geometry

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
op	string	Zorunlu	distance	İşlem: distance, bearing, destination, midpoint, length, area, centroid, simplify, polyline_encode veya polyline_decode.
from	array	İsteğe bağlı	[lat,lng]	Başlangıç noktası [lat,lng].
to	array	İsteğe bağlı	[lat,lng]	Bitiş noktası [lat,lng].
path	array	İsteğe bağlı	[]	[lat,lng] dizisi (length/simplify/polyline_encode).
polygon	array	İsteğe bağlı	[]	[lat,lng] halkası (area).

Yanıt Yapısının Açıklaması

{ op, ... } döndürür — seçilen işlemin sonucuyla, örn. { distance, unit }, { bearing_deg }, { point }, { area, unit }, { path } veya { polyline }.

Coordinate Conversion API

Enlem/boylamı UTM ve MGRS ızgara referanslarına ve tersine dönüştür.

GET/api/1/convert

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
point	string	Zorunlu	lat,lng	UTM/MGRS’e dönüştürülecek koordinat: lat,lng.
mgrs	string	İsteğe bağlı	-	Koordinata geri dönüştürülecek MGRS dizesi.

Yanıt Yapısının Açıklaması

{ point, mgrs, utm:{ zone, band, easting, northing, hemisphere } } döndürür. mgrs= verildiğinde { mgrs, point }.

Country Info API

Herhangi bir ülke için para birimi, arama kodu, diller, başkent ve bayrak — ISO kodu veya adıyla.

GET/api/1/country

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
code	string	Zorunlu	AZ	ISO 3166 alpha-2 veya alpha-3 ülke kodu (örn. AZ veya AZE).
name	string	İsteğe bağlı	-	Kod yerine ülke adı.

Yanıt Yapısının Açıklaması

{ name, official_name, cca2, cca3, capital, region, subregion, currency:{code,name,symbol}, calling_code, languages[], flag, latlng, population } döndürür.

Isochrone API

Belirli bir noktadan belirli bir süre veya mesafede ulaşılabilen coğrafi bölgelerin poligonlarını döndürür.

GET/api/1/isochrone

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
point	string	Zorunlu	-	Merkez nokta. Biçim: lat,lon.
time_limit	integer	İsteğe bağlı	600	Seyahat süresi limiti (saniye cinsinden).

Route Optimization API

Bir araç filosunun rotalarını optimize eder (Vehicle Routing Problem). Araçların teslimat ve taşıma planını en düşük maliyetle hesaplar.

POST/api/1/vrp

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
vehicles	array	Zorunlu	[]	Araç listesi — her biri id, isteğe bağlı kapasite ve [lon, lat] dizisi (önce boylam) olarak bir başlangıç konumu içerir.
services	array	Zorunlu	[]	Hizmet verilecek duraklar — her biri id, [lon, lat] dizisi (önce boylam) olarak konum ve isteğe bağlı hizmet süresi içerir. Koordinat sırası diğer tüm uç noktalarımızla aynıdır.

Location Clustering API

Verilen koordinatları coğrafi yakınlıklarına ve yoğunluklarına göre gruplar (kümelere ayırır).

POST/api/1/cluster

Parametreler (Query Params)

Parametre	Tür	Durum	Varsayılan	Açıklama
customers	array	Zorunlu	[]	Kümelenecek müşteri koordinatları ve ağırlıkları.

Resmî SDK’lar

Sıfır bağımlılık, tam tip desteği, tüm uç noktalar. İlk isteğinizi bir dakikadan kısa sürede atın.

osrmrouteosrmrouteSDK’lara göz at