@optadesolutions/map-sdk

Türkiye için harita ve rota SDK'sı. MapLibre GL üzerine ince bir katmandır: harita stili, tile'lar ve rota servisi tek bir API anahtarıyla Optade sunucusundan gelir.

• Vektör harita, açık ve koyu tema
• Rota hesaplama ve çizme (araç, yürüyüş)
• İşaret (marker), baloncuk, sürüklenebilir işaret
• TypeScript tipleri pakette

İçindekiler

• Kurulum
• Hızlı başlangıç
• API anahtarı
• Nerede çalışır
• Harita seçenekleri
• İşaretler
• Rota
• Ortam ayarı
• Hata yönetimi
• API başvurusu

Kurulum

npm install @optadesolutions/map-sdk
# ya da
pnpm add @optadesolutions/map-sdk
yarn add @optadesolutions/map-sdk

MapLibre GL paketin bağımlılığı olarak gelir; ayrıca kurmanız gerekmez.

Hızlı başlangıç

Haritanın çizileceği bir element ekleyin. Elementin yüksekliği olmalıdır, yoksa harita görünmez:

<div id="harita" style="width: 100%; height: 480px"></div>

import { OptadeMap } from '@optadesolutions/map-sdk'
import '@optadesolutions/map-sdk/style.css'

const map = new OptadeMap({
  container: 'harita', // element kimliği ya da HTMLElement
  apiKey: 'opt_map_...',
  center: [29.02, 40.98], // [boylam, enlem]
  zoom: 13,
})

await map.ready()

map.addMarker({ lng: 29.02, lat: 40.98, popupText: 'Kadıköy' })

Koordinatlar her yerde [boylam, enlem] ([lng, lat]) sırasındadır.

style.css dosyasını unutmayın; harita kontrolleri bu stille çizilir.

API anahtarı

Anahtarı Optade verir; opt_map_ ile başlar.

Anahtar tarayıcıda görünür; gizli değildir. Şimdilik anahtarda alan adı kısıtı yoktur: geçerli bir anahtar her yerden çalışır. Anahtarı yalnızca kendi uygulamanızda kullanın; başka yerde kullanıldığını fark ederseniz Optade'den iptal edip yenisini vermesini isteyin.

• Üretim ve geliştirme için ayrı anahtar kullanın. Böylece birini iptal etmeniz gerektiğinde diğeri etkilenmez.

Nerede çalışır

Paket tarayıcıda çalışır ve ek ayar gerektirmez:

• Web sitesi / SPA
• iframe
• Mobil uygulamada WebView (React Native WebView, webview_flutter, Capacitor vb.)
• Flutter Web (paket dart:js_interop ile kullanılır)

Harita seçenekleri

new OptadeMap({
  container: 'harita',          // zorunlu: element kimliği ya da HTMLElement
  apiKey: 'opt_map_...',        // configureOptade ile verildiyse gerekmez
  baseUrl: undefined,           // varsayılan maps.optade.online, bkz. Ortam ayarı
  theme: 'light',               // 'light' | 'dark'
  center: [35.2, 39.0],         // varsayılan: Türkiye
  zoom: 5,
  minZoom: undefined,
  maxZoom: undefined,
  interactive: true,            // false: kaydırma/yakınlaştırma kapalı
  hideNavigationControl: false, // true: zoom ve pusula düğmeleri gizli
})

Temayı sonradan değiştirmek için:

map.setTheme('dark')

İşaretler

const marker = map.addMarker({
  lng: 29.02,
  lat: 40.98,
  color: '#e11d48',
  popupText: 'Teslimat noktası', // tıklanınca açılan baloncuk
  onClick: ({ lng, lat }) => console.log('tıklandı', lng, lat),
})

popupText düz metin olarak işlenir, HTML olarak yorumlanmaz; kullanıcı verisini doğrudan verebilirsiniz.

Sürüklenebilir işaret, ör. kullanıcının konumu elle düzeltmesi için:

map.addMarker({
  lng: 29.02,
  lat: 40.98,
  draggable: true,
  onDragEnd: ({ lng, lat }) => {
    console.log('yeni konum', lng, lat)
  },
})

Haritaya tıklanan koordinatı almak için:

const off = map.onClick(({ lng, lat }) => {
  map.addMarker({ lng, lat })
})

off() // dinleyiciyi kaldırır

addMarker MapLibre Marker nesnesi döner; tüm işaretleri kaldırmak için map.clearMarkers().

Rota

const result = await map.route({
  Coordinates: [
    [29.02, 40.98],
    [29.06, 41.01],
  ],
  Profile: 'driving', // 'driving' | 'walking'
  Steps: true,        // adım adım manevralar
})

const [best] = result.Routes
console.log(`${(best.Distance / 1000).toFixed(1)} km, ${Math.round(best.Duration / 60)} dk`)

• En az 2, en çok 100 nokta gönderilebilir; ara noktalar sırayla ziyaret edilir.
• Distance metre, Duration saniyedir. İlk rota en iyisidir.
• Alternatives: true alternatif rotaları da döndürür.
• Overview: 'none' yalnızca mesafe/süre gerekiyorsa çizgiyi atlar; bu durumda haritaya bir şey çizilmez.

Varsayılan olarak rota haritaya çizilir, başlangıç ve bitişe işaret konur ve görünüm rotaya sığdırılır. İkinci parametreyle değiştirilebilir:

await map.route(request, {
  color: '#dc2626',
  width: 8,
  opacity: 0.9,
  markers: false,   // başlangıç/bitiş işareti koyma
  fitBounds: false, // görünümü değiştirme
})

Tekrar çağrıldığında önceki çizginin yerine yenisi çizilir, ancak başlangıç ve bitiş işaretleri birikir. Rotayı yenilerken eski işaretleri map.clearMarkers() ile kaldırın ya da markers: false verin. Son sonuç için map.getLastRoute(), çizgiyi kaldırmak için map.clearRoute() (işaretlere dokunmaz).

Ortam ayarı

SDK varsayılan olarak https://maps.optade.online sunucusuna bağlanır. Bu adres pakete gömülüdür, ayar gerekmez.

Anahtarı her OptadeMap çağrısına yazmak istemiyorsanız uygulama açılışında bir kez verin:

import { configureOptade, OptadeMap } from '@optadesolutions/map-sdk'

configureOptade({ apiKey: 'opt_map_...' })

const map = new OptadeMap({ container: 'harita' })

Sunucu adresini değiştirmek

Adres değiştirilebilir. Optade size ayrı bir test sunucusu verdiyse ya da istekleri kendi proxy'nizden geçiriyorsanız baseUrl ile verin; diğer durumlarda dokunmayın.

configureOptade({ baseUrl: 'https://test-sunucusu.ornek' })

Adresi projenizin kendi yapılandırmasından (ortam değişkeni, config dosyası vb.) okuyup buraya vermek her framework'te aynı şekilde çalışır.

Birden çok yerde verilmişse ilk bulunan kazanır:

1. new OptadeMap({ baseUrl })

2. configureOptade({ baseUrl })

3. process.env.OPTADE_BASE_URL (ayrıca NEXT_PUBLIC_OPTADE_BASE_URL, VITE_OPTADE_BASE_URL). Yalnızca derleme aracınız process.env.* ifadelerini derleme anında değere çeviriyorsa çalışır; emin değilseniz

   1. ya da 2. yolu kullanın.

4. globalThis.OPTADE_BASE_URL. Derleme adımı olmayan sayfalarda paketten önce çalışan bir <script> ile atanır:

   <script>window.OPTADE_BASE_URL = 'https://test-sunucusu.ornek'</script>

5. https://maps.optade.online

Hangi sunucuya gidildiğini map.getBaseUrl() söyler. resetOptadeDefaults() configureOptade ile verilenleri siler; testlerde her senaryo arasında temiz başlamak için kullanılır.

Hata yönetimi

Sunucu hataları OptadeApiError olarak fırlatılır; status HTTP durum kodunu taşır.

import { OptadeApiError } from '@optadesolutions/map-sdk'

try {
  await map.route({ Profile: 'driving', Coordinates: [[29.02, 40.98], [29.1, 41.0]] })
} catch (error) {
  if (error instanceof OptadeApiError && error.status === 404) {
    // Noktalar arasında rota bulunamadı
  }
}

| Durum | Olası sebep | |---|---| | 400 | İstek geçersiz, ör. 2'den az ya da 100'den çok nokta | | 401 | Anahtar geçersiz, iptal edilmiş ya da süresi dolmuş | | 403 | Özellik (ör. rota) anahtar için kapalı | | 404 | Verilen noktalar arasında rota bulunamadı |

Harita stili yüklenemezse map.ready() reddedilir.

API başvurusu

OptadeMap

| Metod | Açıklama | |---|---| | ready() | Stil ve ilk tile'lar yüklenince çözülür | | route(request, draw?) | Rota hesaplar ve çizer | | getLastRoute() | En son hesaplanan rota | | clearRoute() | Çizili rotayı kaldırır | | addMarker(options) | İşaret ekler, Marker döner | | clearMarkers() | Eklenen tüm işaretleri kaldırır | | onClick(handler) | Tıklanan koordinatı verir; dönen işlev dinleyiciyi kaldırır | | flyTo(lng, lat, zoom?) | Konuma uçar (varsayılan zoom 16) | | fitBounds([batı, güney, doğu, kuzey], padding?) | Sınırları kapsayan görünüme geçer | | setTheme(theme) | Açık/koyu tema | | getBaseUrl() | Kullanılan sunucu adresi | | getMapLibreMap() | Alttaki MapLibre örneği, ileri seviye kullanım için | | destroy() | Haritayı ve işaretleri temizler |

Diğer dışa aktarılanlar

| Ad | Açıklama | |---|---| | OptadeApiError | Sunucu hatası, status alanıyla | | configureOptade, getOptadeDefaults, resetOptadeDefaults | Varsayılan ayarlar | | DEFAULT_BASE_URL | Üretim sunucu adresi | | SDK_VERSION | Paket sürümü |

Tüm istek ve yanıt tipleri (OptadeRouteRequest, OptadeRouteResult vb.) paketten import edilebilir.

Lisans

MIT