Skip to main content

⚡ Gerçek zamanlı nowcast

Sürücünün bulunduğu segment her zaman canlı radar kaynaklı yıldırım, fırtına ve yağış verisi taşır — model tahmini değil.

🔭 İleriye dönük tahmin

İlerleyen segmentler saatler önceden koşulları planlamak için saatlik NWP tahmin verisiyle zenginleştirilir.

🗺️ Akıllı segmentasyon

Rota, Uber H3 altıgen hücrelerine bölünür. Her hücre kendi ETA’sını ve bağımsız hava sorgusunu alır; böylece veri her zaman taze ve konumsal olarak doğru kalır.

Enroute API nedir?

Enroute API, planlanmış bir rotayı canlı hava takip oturumuna dönüştürür. Rota geometrisini, kalkış saatini ve süresini sağlarsınız — API rotayı coğrafi segmentlere böler, her birine zamanlanmış varış saati ekler ve sonraki her sorguda tüm segmentler için hava verisi döndürür. Tüm yaşam döngüsünü iki uç nokta yönetir:
İsteklerdeki ve yanıtlardaki tüm zaman damgaları epoch milisaniyedir (64-bit tam sayı). Asla ISO string veya ondalık saniye göndermeyiniz.

Segmentasyon nasıl çalışır?

Bir rota kaydedildiğinde servis, rota geometrisini (kodlanmış polyline veya koordinat listesi) çözümler ve her noktayı çözünürlük 5’teki Uber H3 altıgen hücresine eşler. Aynı hücreye düşen ardışık noktalar birleştirilir; böylece sıralı benzersiz hücreler listesi — segmentler — elde edilir. Her segment şunları alır:
  • eta — zamanlanmış varış anı: kalkışZamanı + (girişMesafesi / toplamMesafe) × süreSniye şeklinde enterpolasyonla hesaplanır
  • etd — zamanlanmış ayrılış anı (aynı enterpolasyon, çıkışMesafesi kullanılarak)
  • distanceToEntry / distanceToExit — rota başından kümülatif metre değerleri
  • arrivalPoint / departurePoint — rotanın hücreye girdiği ve çıktığı coğrafi koordinatlar
  • h3Address — H3 hücre tanımlayıcısı (hava sorguları için kullanılır)
H3 çözünürlük 5 hücreleri yaklaşık 252 km² kapsar; orta büyüklükte bir ilçeye karşılık gelir. Tipik bir 90 dakikalık otoyol güzergahı 7–10 segmentten oluşur.
Neden segmentasyon? Hava koşulları mekânsal olarak heterojendir. Varış noktanızda yağmur yağarken 80 km geride gökyüzü açık olabilir. Segmentasyon, API’nin yolculuğun her bölümü için doğru hava modeli hücresini sorgulamasına ve bu sorguları sürücünün gerçek ETA’sına göre zamanlamasına olanak tanır — hepsini aynı anda değil.

Nowcast ve Forecast

Yanıt, segmentin zaman ufkuna bağlı olarak iki yapısal olarak farklı hava yükü içerir.

currentSegment — Nowcast + Forecast

Sürücünün şu anda bulunduğu segment (veya kayıt anında ilk segment) nowcast verisi alır: canlı radar ve sensör ağlarından türetilen gerçek zamanlı gözlemler. Bu, mevcut en zengin ve en doğru hava durumu görüntüsüdür. Nowcast, üç özel özet nesne içerir: Gelecek segmentler neden nowcast kullanamaz? Her üç nowcast servisi de bu konuda farklı ama birbirini destekleyen kısıtlara sahiptir:
  • Yıldırım: Sensör ağları yalnızca gerçekleşmiş flaşları kaydeder. Geleceğe dönük herhangi bir çıktı üretmez; sürücünün 2 saat sonra geçeceği hücre için yıldırım nowcast’i fiziksel olarak mümkün değildir.
  • Fırtına: Radar tabanlı hücre takibi, aktif fırtına hücrelerinin anlık konumunu, hızını ve yönünü izler. Yalnızca mevcut gözleme dayanır; ileriye dönük projeksiyon üretmez. Saatler sonraki bir segment için anlamlı bir tehdit değerlendirmesi yapılamaz.
  • Yağış: Radar gözlemleriyle birlikte çok kısa vadeli bir NWP projeksiyonu da mevcut olabilir; bu projeksiyon precipitationSummary içindeki expectedStartSec / expectedEndSec alanlarını besler. Ancak bu ufuk yalnızca anlık gözlem penceresini biraz aşar ve saatler sonraki bir segmentin koşullarını temsil etmez.
Sonuç olarak: üç servisin ağırlıklı değeri “şu anda, tam burada” sorusuna verdiği yanıtta yatar. İlerleyen segmentler için bu sorunun cevabı anlamsız hale geldiğinden, nowcast yerine çok saatlik ufka sahip NWP tahmin modelleri devreye girer.

upcomingSegments — Yalnızca Forecast

Mevcut segmentten sonraki tüm segmentler NWP (Sayısal Hava Tahmini) saatlik tahmin verisi taşır: sıcaklık, hissedilen sıcaklık, nem, bulut örtüsü, rüzgar hızı/rüzgar hamlesi/yönü, yağış, yağış olasılığı, kar yağışı ve görüş mesafesi.
Kayıt anında, departureTime şimdiden 60 dakika içindeyse mevcut segment için de nowcast verisi alınır. Kalkış daha uzak bir geleceğe aitse, ilk segment için de yalnızca tahmin verisi döndürülür.

Rota kaydı

İstek

encodedPolyline (ile polylinePrecision) veya coordinates alanlarından biri mutlaka sağlanmalıdır. İkisi de gönderilmezse 400 hatası döner.

Yanıt

routeId değerini kaydedin — yolculuk boyunca /weather uç noktasını sorgulamak için gereken tek anahtardır. expirationTime, oturumun ne zaman sona ereceğini gösterir; ancak sürücü zamanlama dışı kalıp segmentler yeniden hesaplandığında bu değer uzatılır (bkz. Zamanlama Dışı).

Rota hava durumu sorgulama

İstek

Yanıt

GetRouteWeatherResponse, RouteRegistrationResponse’ı genişletir ve şunları ekler: Diğer tüm alanlar (routeId, expirationTime, distanceUnit, status, currentSegment, upcomingSegments) yapı olarak kayıt yanıtıyla aynıdır.

Yanıt alanı referansı

LocationStatus

expectedSegmentIndex rota zamanlamasını yansıtır, GPS konumunu değil. Sürücü segment 2’deyken zamanlama segment 3’te olmasını bekliyorsa bu alan 3 gösterir. Zamanlama kaymasını tespit etmek için currentSegment.index ile karşılaştırın.

BaseRouteSegment (currentSegment ve upcomingSegments için ortak)

ForecastWeatherEvents (tüm segmentler)


Nowcast özet alanları

currentSegment.weatherEvents nesnesi, nowcast verisi mevcut olduğunda üç ek özet nesne içerir.

LightningSummary — Yıldırım Özeti

Yer tabanlı elektromanyetik sensörlerden türetilen gerçek zamanlı yıldırım aktivitesi. Mobil uygulama kullanıcısı için anlamı: riskLevel rengine göre bir yıldırım kalkan simgesi gösterin. riskLevel HIGH veya EXTREME ise acil uyarı çıkarın. nearestFlashDistance ve lastFlashAgeSec ile bağlam sağlayın: “45 saniye önce 3,2 km uzakta yıldırım tespit edildi — araçta kalın.”

ThunderstormSummary — Fırtına Özeti

Çok katmanlı radar analizinden türetilen fırtına hücresi takibi.

summary nesnesi

activeStorms[] — fırtına başına detay

Mobil uygulama kullanıcısı için anlamı: insideAnyThreatBoundary true ise bu anlık bir güvenlik uyarısıdır — sürücü bir fırtınanın tahmin edilen etki bölgesi içindedir. approachState: APPROACHING bayrağı ve nearestThreatBoundaryDistance sürücünün durması mı yoksa devam etmesi mi gerektiğine karar vermesine yardımcı olur. Fırtınanın hangi yönden geldiğini anlamak için directionFromDriver değerini gösterin.

PrecipitationSummary — Yağış Özeti

Mevcut H3 hücresi için radar kaynaklı yağış analizi. Mobil uygulama kullanıcısı için anlamı: currentIntensity’yi hava rozeti olarak gösterin. expectedStartSec’i önceden uyarı vermek için kullanın — “8 dakika içinde şiddetli yağmur bekleniyor” — böylece sürücüler hazırlık yapabilir (silecekler, hız düşürme). HEAVY veya üzeri proaktif bir anlık bildirim gerektirir.

Rota dışı ve zamanlama dışı durumlar

Rota Dışı (Off-Route)

/weather uç noktası, sürücünün currentLocation konumunun kayıtlı rotanın herhangi bir segmentine 1.000 metre içinde olup olmadığını kontrol eder (dik mesafe). Sürücü bu eşiği aşarsa:
  • Rota oturumu önbellekten anında silinir.
  • error: "Off Route" ile 400 Bad Request döner.
  • routeId artık geçerli değildir.
  • İstemci /register’ı yeni bir rota ile tekrar çağırmalıdır.
UX rehberi: HTTP 400 ve error: "Off Route" kombinasyonunu dinleyin. Kullanıcıya bir iletişim kutusu gösterin: “Rotadan çıktınız. Hava durumu takibini sürdürmek için yeni güzergahınızda navigasyonu başlatın.” Aynı routeId ile /weather’ı yeniden denemeyin.

Zamanlama Dışı (Off-Schedule)

Sürücünün GPS konumu beklenenden önemli ölçüde geride kalıyorsa — özellikle now, sürücünün mevcut segmentinden sonraki segmentin zamanlanmış ETA’sından 10 dakikadan fazla geçtiyse — servis kalan rota segmentlerini sürücünün mevcut konumundan sessizce yeniden hesaplar. Yeniden hesaplama gerçekleştiğinde:
  • Yanıtta segmentsRecalculated: true ayarlanır.
  • warning, kullanıcı dostu bir açıklama içerir.
  • Segment indeksleri, ETA’lar ve mesafeler sürücünün mevcut konumundan sıfırlanır.
  • currentSegment, sürücünün şu anda bulunduğu konumdan başlayan yeni segment 0’ı yansıtır.
  • expirationTime, yeni ETA + 2 saat olarak uzatılır.
segmentsRecalculated true olduğunda, önceki yanıtlardan önbelleğe alınan tüm segment verilerini atın ve yeni yanıttaki tam segment listesini yeniden oluşturun.

Hata referansı

Yinelenen Rota (409)

Süresi Dolmuş veya Bulunamadı (400)

Veri Tedarik Hatası (500)

Altta yatan hava durumu servislerinden (yıldırım, gök gürültülü fırtına, yağış veya tahmin) birine ulaşılamadığında döner. message alanı hangi kaynak ve servisin başarısız olduğunu belirtir; loglama ve kullanıcı dostu geri dönüş mesajı gösterimi için kullanabilirsiniz.

Geliştirici notları

API’deki tüm Instant tipli alanlar 64-bit tam sayı epoch milisaniye olarak serileştirilir — expirationTime, eta, etd, estimatedArrivalTime. Bu değerleri asla saniye olarak yorumlamayın. JavaScript’te doğrudan new Date(value), Java’da Instant.ofEpochMilli(value) kullanın.
API (kullanıcıId, başlangıçH3, varışH3) üzerinde tekilleştirme uygular. Sürücü aktif bir oturum varken aynı rotayı kaydetmeye çalışırsa 409 Conflict döner; messages dizisinde mevcut routeId ve expirationTime bulunur. 409’u fatal hata olarak ele almak yerine messages dizisini ayrıştırarak mevcut routeId’yi çıkarın ve sorgulamaya devam edin.
Oturumlar ETA + 2 saat sonra sona erer. Süresi dolduktan sonra eski routeId ile /weather çağrısı 400 döndürür. Sona erme süresini proaktif olarak takip etmek için her yanıttaki expirationTime ile karşılaştırma yapın.
Sunucu tarafı push yoktur; tüm güncellemeler istemci tarafından başlatılan /weather sorgusu gerektirir. Araç hareket halindeyken önerilen yoklama aralığı: her 30–60 saniyede bir. Araç durakken (örn. trafik durması) 5 dakikaya düşürülebilir.
segmentsRecalculated: true olduğunda segment listesi sürücünün mevcut konumundan yeniden oluşturulmuştur. Segment index değerleri 0’dan yeniden başlar. Önceki segment indekslerini önbelleğe alan UI öğelerinin (ilerleme çubukları, segment listesi kaydırma) yeni yanıt kullanılarak yeniden başlatılması gerekir.
Yanıttaki distanceUnit alanı her zaman "m" değerini alır. distanceToEntry, distanceToExit ve remainingDistance değerlerinin tümü metredir. Km veya mil’e dönüşümü UI katmanında yapın.

Postman ile test

Aşağıdaki Postman görselleştirme scripti, her /register veya /weather isteğinden sonra Visualize sekmesinde okunabilir bir rota özeti render eder — rota durumunu anlamak için ham JSON okumaya gerek kalmaz. Kullanımı:
  1. İsteği Postman’de açın (POST /v1/enroute/register veya POST /v1/enroute/weather).
  2. ScriptsPost-response bölümüne gidin ve aşağıdaki scripti yapıştırın.
  3. İsteği gönderin, ardından Visualize sekmesine geçin.