Seyahat verilerini işleme

Seyahat verilerinizi aldığınızda arka uç, sürücünün seyahat ilerlemesiyle ilgili ayrıntılı JSON yükleri alır. Bu yükleri ayrıştırarak yolculuğu izleyebilir, sevk sistemlerinizi güncelleyebilir ve mevcut yolculuk durumlarını yorumlayarak sürücünün ilerlerken veya yolculuk sona erdiğinde sonraki adımlarını belirleyebilirsiniz.

Veri yükünü okuma

Google Haritalar veya Waze, sürücü navigasyonu başlattığında, rota boyunca düzenli olarak (varsayılan olarak her 60 saniyede bir) ve sürücü hedefe ulaştığında gezi verileri yüklerini Navigation Connect sunucularına gönderir. Her JSON mesajı, sürücünün yola sabitlenmiş koordinatları, gidilen mesafe ve tahmini varış zamanı (TVS) dahil olmak üzere ilgili seyahat verilerini içerir. Bu güncellemeler, sürücünün etkin ve anlık rotasını yansıttığı için arka uçunuz tarafından önceden hesaplanan rotalardan farklı olabilir (SSS bölümüne bakın).

Aşağıdaki kod örneğinde, bir sürücünün King's Cross'tan Central St. Giles'a yaptığı bir yolculuk için navigasyonu başlattığı zamana ait bir gezi verileri yükü gösterilmektedir.

{
  "name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
  "state": "ENROUTE",
  "execution": {
    "origin": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      }
    },
    "destination": {
      "point": {
        "latitude": 51.515598,
        "longitude": -0.1277623
      }
    },
    "location": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      },
      "sourceTime": "2025-05-30T12:37:26Z",
      "serverTime": "2025-05-30T12:37:26.221069Z"
    },
    "traveledDuration": "0s",
    "remainingDuration": "990s",
    "traveledDistanceMeters": 0,
    "remainingDistanceMeters": 2879,
    "stopAddedInRoute": false
  }
}

Etkin seyahat durumlarını izleme

Başlangıcın başarılı olduğunu onaylamak ve ilerlemeyi izlemek için her yükteki state alanını değerlendirin.

Durum Açıklama
NEW Seyahat oluşturuldu ancak sürücü henüz navigasyonu başlatmadı.
ENROUTE Sürücü, hedefe doğru aktif olarak rota izliyor. Bu durumu, seyahatin kimliğinin başarıyla doğrulandığını ve seyahatin başarıyla başladığını onaylamak için kullanın.

Eklenen durakları yönetme

Sürücüler, navigasyon sırasında rotalarına durak ekleyebilir. Bu durumda, Navigation Connect, JSON veri yükünde execution.stopAddedInRoute alanını true olarak ayarlar. Navigation Connect API, sürücüyü orijinal hedefe doğru takip etmeye devam eder. Tahmini varış zamanı (TVZ), mesafe ve süre gibi metrikler, eklenen durakları içerecek şekilde artar.

Durak ekleme davranışı, navigasyon uygulamasına bağlıdır ve uygulamanın standart işlevselliğiyle eşleşir:

  • Google Haritalar: Sürücüler, rotalarına birden fazla durak ekleyebilir.
  • Waze: Sürücüler yalnızca bir durak ekleyebilir. Bir sürücü başka bir durak eklemeye çalışırsa Waze, mevcut rotaya durağı eklemek yerine yeni bir navigasyon oturumu başlatmasını ister.

Bu özelliği desteklemek için arka uç girişlerinizi ayarlamanız gerekmez.

Kimlik doğrulama ve başlatma sorunlarını giderme

ENROUTE durumu almazsanız büyük olasılıkla kimlik doğrulama hatası oluşmuştur. Yaygın nedenler arasında yanlış yazılmış API parametreleri veya süresi dolmuş bir gezi jetonu yer alır. İlk CreateTrip yanıtınızdaki jeton geçerlilik bitiş zamanını kontrol edin.

Durum NEW'dan ENROUTE'ya değişmezse sürücünün cihazı kimlik doğrulamayı engelliyor olabilir. Navigation Connect bu durumlarda hata mesajı göndermez. Aşağıdakileri doğrulayın:

  • Sürücünün cihazında Waze 5.15.5 veya sonraki bir sürüm ya da Google Haritalar 26.14 veya sonraki bir sürüm yüklü olmalıdır.
  • Sürücü, Android Auto veya Apple CarPlay kullanmıyor.
  • Sürücünün etkin bir internet bağlantısı olmalıdır.

Kalan rota verilerini işleme (yalnızca Waze)

Seyahat oluşturma sırasında kalan rota raporlamayı etkinleştirdiyseniz arka uçunuz, sürücünün mevcut konumundan nihai varış noktasına kadar olan kalan rota çoklu çizgisini ve anlık trafik koşullarını alır.

Bu verileri alıp işleyerek uygulamalarınızdaki çeşitli özellikleri destekleyebilirsiniz. Örneğin:

  • Canlı takip haritalarını destekleme: Sürücünün yolculuğu hakkında görünürlük sağlamak için kalan rota poliline müşteriyle etkileşim kurulan bir web veya mobil haritada oluşturun.
  • Tahmini varış zamanı doğruluğunu artırma: İç lojistiği veya teslimat varış tahminlerini iyileştirmek için yola göre hizalanmış çoklu çizgi ve trafik aralığı hızlarını birleştirin.
  • Rota uyumluluğunu analiz etme: Sürücü uyumluluğunu değerlendirmek için kalan rota geometrisini beklenen dağıtım rotalarıyla karşılaştırın (anlık ve önceden hesaplanmış rotaların neden farklı olabileceğiyle ilgili ayrıntılar için SSS bölümüne bakın).

İster GetTrip isteği gönderin ister Google Cloud Pub/Sub'ı kullanarak etkinliğe dayalı güncellemeler alın, Navigation Connect kalan rota ayrıntılarını execution.remainingRoute alanında döndürür. Ancak yükün bu verileri nasıl biçimlendireceği ve yapılandıracağı, kullandığınız alma yöntemine bağlıdır.

GetTrip yöntemi

GetTrip yöntemini çağırdığınızda, çoklu çizginin yanıt biçimi, isteğinizde belirttiğiniz routePolylineFormat parametresine bağlıdır. Daha fazla bilgi için Çoklu çizgi biçimlerini özelleştirme başlıklı makaleyi inceleyin.

Tüm çoklu çizgi biçimlerinde Navigation Connect, trafiği SpeedReadingInterval execution.remainingRoute.trafficInformation alanındaki ayrı bir nesne listesi olarak döndürür. Bu nesneler, aşağıdaki değerleri kullanarak trafik kategorilerini çoklu çizgi dizinleriyle eşler:

Google Cloud Pub/Sub güncellemeleri

Pub/Sub ile seyahat verilerini aldığınızda, güncellemeler her zaman kalan rota verilerini execution.remainingRoute alanında birleştirilmiş bir GeoJSON FeatureCollection olarak döndürür.

Bu biçim, çoklu çizgi geometrisini doğrudan trafik hızlarıyla birleştirerek dizinlerin manuel olarak eşlenmesi ihtiyacını ortadan kaldırır.

Örnek bir Pub/Sub yükü görme

Aşağıdaki kod örneğinde, bir Pub/Sub mesajının updatedTrip nesnesindeki execution.remainingRoute alanında döndürülen GeoJSON yapısı gösterilmektedir:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.3934, 37.7955],
          [-122.4010, 37.7980]
        ]
      },
      "properties": {
        "speed": "SLOW"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.4010, 37.7980],
          [-122.4058, 37.8025],
          [-122.4187, 37.8021]
        ]
      },
      "properties": {
        "speed": "NORMAL"
      }
    }
  ]
}

Yük boyutunu optimize etme

Koordinat dizileri büyük olduğundan, kalan rota verilerini Pub/Sub mesajlarınıza eklemek yük boyutunu önemli ölçüde artırabilir (mesaj başına 13-14 KB'a kadar). Yüksek sıklıkta güncellemeler alıyorsanız bu hacim, arka uç işleme yükünü ve kullanım maliyetlerini artırabilir.

Akışınızı optimize etmek için gezi oluşturma sırasında TripConfig nesnenizde pubsubFieldMask parametresini kullanarak ağır alanları hariç tutun. Ayrıntılı bilgi için İsteğe bağlı yapılandırmalar başlıklı makaleyi inceleyin.

Rota sapmalarını ele alma (yalnızca Waze)

Seyahat oluşturma sırasında rota sapması raporlamasını etkinleştirdiyseniz sürücü rotadan çıktığında API, rota sapması meta verilerini döndürür. Bu verilere aşağıdaki yöntemlerle erişebilirsiniz:

  • İsteğe bağlı: GetTrip yöntemini çağırın. Sunucu, bilinen son sapma durumunu kalıcı hale getirir.
  • Anlık: Google Cloud Pub/Sub'a abone olun. Hizmet, algılamadan sonraki 5 saniye içinde mevcut updated_trip etkinliğini kullanarak sapma güncellemeleri yayınlar.

Sapma yükünü okuma

last_route_deviation nesnesi, etkinliği analiz etmenize yardımcı olmak için aşağıdaki meta verileri sağlar.

Alan Tür Açıklama
location LatLng İstemci cihazın sapmayı kaydettiği enlem ve boylam koordinatları.
source TriggerSource Sapmanın nedeni. Sürücünün beklenmedik bir işlem yapıp yapmadığını veya sistem talimatlarına uyup uymadığını belirlemek için bu bilgiyi kullanın:
  • DRIVER_INITIATED_REROUTE: Sürücü aktif bir seçim yapmıştır (örneğin, yanlış bir dönüş yapmış veya manuel olarak yeni bir rota seçmiştir).
  • SYSTEM_INITIATED_REROUTE: Navigasyon uygulaması, yeni bir rota hesapladı (ör. değişen trafik koşulları veya yol kapanmaları nedeniyle).
client_timestamp Timestamp İstemci cihazın sapmayı algıladığı zaman.
server_timestamp Timestamp Sunucunun sapma güncellemesini işlediği zaman.

Gezi bitiş durumlarını işleme

Bir sürücü hedefe ulaştığında veya navigasyonu durdurduğunda yük, aşağıdaki bitiş durumlarından birini döndürür. Uygulamanızda uygun sonraki adımları tetiklemek için bu durumları kullanın.

Durum Açıklama Önerilen işlem
ARRIVED Sürücü varış noktasına ulaştı. remainingDistanceMeters bağlantısını kontrol edin. Sürücü yakında bir yere park ettiyse ancak tam olarak koordinatlarda değilse uygulamanızda yürüme yol tarifi sağlamayı düşünebilirsiniz.
SUSPENDED Sürücü, hedefe varmadan önce adım adım rota özelliğinden manuel olarak çıktı.
Google Haritalar veya Waze, sürücüleri bir oturumdan erken çıktıklarında otomatik olarak uygulamanıza geri yönlendirmediğinden sürücünün geri dön düğmesine manuel olarak dokunması gerekir. 		Sürücülerin yolculuklarını tamamlamalarına yardımcı olmak için execution.location ile hedefi karşılaştırın. Mesafe kalırsa yolculuğa devam etmek veya yürüyüş moduna geçmek için bir düğme ya da bağlantı sağlayın.
FAILED Teknik bir hata nedeniyle bağlantı kesildi. Bu durum, uygulama bir rota hesaplayamadığında veya güvenlik uyarısı göründüğünde ortaya çıkar. Sürücü navigasyonu kullanmaya devam edebilir ancak siz güncelleme almazsınız. Uygulamanızda manuel durum izlemeye geri dönün.
CLIENT_ERROR Bu durum, aşağıdaki nedenlerden biriyle karşılaşılması durumunda gösterilir:
  • Sürücü izni iptal eder.
  • Sürücü, Android Auto veya Apple CarPlay gibi desteklenmeyen bir platform kullanıyordur.
  • Uygulamanız, ayrı seyahatlerde aynı seyahat jetonunu yeniden kullanıyor. Örneğin, Navigation Connect, gezi hedefini değiştiren veya tamamlanmış bir geziyi güncelleyen istekleri reddeder.
  • Sürücü, gezi sırasında herhangi bir noktada ABD'de bulunuyor ancak kurulum sırasında uygulamanızı doğruladığınızda uygulamanızda ABD'de veri paylaşımı etkin değil.
 Uygulamanızda manuel durum izlemeye geri dönün.