Büyük araç rotaları ve tahmini varış zamanları oluşturma

Bu kılavuz kimler için hazırlanmıştır? Kamyon veya diğer büyük araçları kullanarak seyahat planlama ve yürütme hizmetleri geliştiren bir geliştiriciyseniz bu kılavuzu okuyun. Seyahat sürelerini ve mesafelerini hesaplama, tahmini varış zamanlarını hesaplama veya bir navigasyon uygulaması tarafından kullanılacak rotalar oluşturma gibi kullanım alanları bu duruma örnek verilebilir.

Bu kılavuzda ele alınan konular: Bu kılavuzda, ticari kamyon veya yolcu otobüsü gibi büyük bir aracın belirli özelliklerini hesaba katan rotalar, seyahat mesafesi, tahmine dayalı seyahat süresi ve TVS'ler istemek için Büyük Araç Yönlendirme ile birlikte Routes API'nin nasıl kullanılacağı açıklanmaktadır.

Rota Optimizasyonu API'sini kullanarak büyük araçlar için filo düzeyinde hesaplamalar yapma hakkında bilgi edinmek için Rota Optimizasyonu Kamyon Rotalandırma Dokümanları'na bakın.

Neler öğreneceksiniz?

Öğrenecekleriniz:

  • Geçerli bir yönlendirme isteği oluşturun.
  • Boyut, ağırlık ve diğer özellikleri kullanarak gerçek dünyadaki aracınız için bir araç profili belirtin.
  • Rota jetonu ve seyahat güvenliği işaretleri de dahil olmak üzere yanıtı yorumlayın.

Ön koşullar

  1. Google Cloud projeniz oluşturulmalı ve Routes API etkinleştirilmelidir.
  2. Projeniz Büyük Araç Rotalandırma için hazırlanmış olmalıdır. Bu adımı tamamlamak için Google temsilcinizle iletişime geçin.

Sınırlamalar

Başlamadan önce aşağıdaki sınırlamaları ve koşulları bilmeniz gerekir.

  • Coğrafi Kullanılabilirlik: Büyük araç yönlendirme yalnızca ABD'nin bitişik 48 eyaletinde kullanılabilir.
  • Büyük araç rotalandırma, önizleme aşamasında olan bir tekliftir. Sürücüler, güvenli veya yasal olmak için yalnızca bu API'nin döndürdüğü rotalara güvenmemelidir. Rotaların araca uygun olduğu garanti edilmez ve bu rotaları takip etmek sürücüleri alçak köprüler veya büyük araçların yasak olduğu yollar gibi tehlikelere maruz bırakabilir.
  • En iyi çaba rotaları. Bazı durumlarda API, seyahat kısıtlamalarına tam olarak uyan bir rota bulamaz. Bunun yerine, kısıtlanmış alanlardan geçmeye devam edebilecek bir "en iyi çaba" rotası döndürür. Routes API yanıtı, routeRestrictionsPartiallyIgnored alanında bu rotaları net bir şekilde işaretler. Bu gibi durumlarda rotanızı dikkatli bir şekilde planlayın. İdeal olarak diğer kaynak verileri kullanın. Planlama veya gezinme için işaretlenmiş bir rotayı tek doğruluk kaynağı olarak kullanmayın.
  • Desteklenmeyen Özellikler: Bu teklife daha fazla işlevsellik kazandırmak için çalışıyoruz ancak büyük araç rotalama özelliği aşağıdakileri desteklemez:
    • Kamyon geçiş ücretleri
    • Hız sınırları
    • Radyoaktif tehlikeli maddeler için rota oluşturma
  • Kullanım sınırları: Tüm istekler, standart saniyedeki sorgu sayısı (QPS) sınırlarına tabidir.

Kamyon rotası isteği oluşturma

Kamyon rotası almak için Routes API uç noktasına aracınızı tanımlayan belirli parametrelerle bir HTTPS isteği gönderirsiniz.

Uç noktalar

Kamyon rotası için iki uç nokta kullanabilirsiniz:

  • computeRoutes: Bir başlangıç noktası ile bir hedef arasında tek bir rota hesaplar.
  • computeRouteMatrix: Bir başlangıç ve hedef matrisi için mesafeyi ve süreyi hesaplar ancak rota poliline döndürmez.

Anahtar istek parametreleri

İstek gövdenize aşağıdakileri eklemeniz gerekir:

  • travelMode: Bu değeri TRUCK olarak ayarlayın.
  • routingPreference: Bu değeri TRAFFIC_AWARE_OPTIMAL olarak ayarlayın.
  • routeModifiers: Bu nesne, aracınızın özelliklerini tanımladığınız vehicleInfo nesnesini içerir. vehicleInfo nesnesi aşağıda ayrıntılı olarak açıklanmıştır.

Araç profili belirtme

İstek göndermek için aracınızı açıklayan bir vehicleInfo nesnesi içeren bir istek gövdesi sağlamanız gerekir. Bu bilgileri, gerçek dünyadaki aracınızın fiziksel özellikleriyle eşleşen bir spesifikasyon olarak düşünebilirsiniz. Hizmet, aracınızın özelliklerine göre yol kısıtlamalarını dikkate alan rotalar döndürmek için bu ayrıntıları gerektirir.

Araç ölçümleri

Alan adlarında belirtildiği gibi, araç ağırlığını kilogram cinsinden, araç boyutlarını ise milimetre cinsinden girin. Örneğin, toplam yükseklik milimetre (totalHeightMm) cinsinden sağlanmalıdır. Kamyon boyutları genellikle fit veya metre cinsinden ifade edildiğinden birim dönüştürme işlemi gerekebilir.

İngiliz birimlerinden metrik birimlere dönüştürme

İngiliz birimlerinden dönüştürürken her zaman standart yol ve alt geçit boyutu sınırlarının yanı sıra aracınızın boyutlarını da göz önünde bulundurun. Bu durum, özellikle kesirli değerlerde önemli olabilir. Gerçek aracın boyutuna bağlı olarak kesirli bir değeri yukarı yuvarlamak, araç için aşırı kısıtlayıcı bir rota oluşturulmasına neden olabilir.

Örneğin:

  • Genişlik: ABD'deki birçok treylerin genişliği 8' 6" (2.590,8 mm) olur. 2.591 mm'ye yuvarlama, aracın 8' 6"tan büyük olduğunu gösterir. Bu da aracı ABD yollarında büyük boyutlu araç olarak sınıflandırır. Bu durum, amaçlanandan anlamlı ölçüde farklı kısıtlamalara göre hesaplanan bir rotaya yol açar.
  • Yükseklik: 3,35 metre yüksekliğindeki bir köprünün altından geçen rota, 4,11 metre yüksekliğindeki normal bir tır için uygun değildir. Ancak yaklaşık 3 metre uzunluğundaki daha küçük kamyonlar alt geçitten geçebilir. Bu nedenle, araç özelliklerinizi doğru şekilde belirtmeniz çok önemlidir.

Bir kamyonun boyutlarını alt geçidin boyutlarıyla karşılaştıran bir diyagram

Aşağıda, örnek bir vehicleInfo nesnesini gösteren bir kod snippet'i verilmiştir:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

vehicleInfo nesne alanı

Aşağıdaki tabloda, istekle birlikte gönderebileceğiniz tüm araç ve yük tanımları gösterilmektedir.

Alan Açıklama Notlar / Değerler
totalHeightMm Aracın maksimum yüksekliği. Milimetre cinsinden, aşağı yuvarlanmış olarak. Yuvarlama hakkında daha fazla bilgi için İngiliz birimlerinden metrik birimlere dönüştürme başlıklı makaleyi inceleyin.
totalWidthMm Aracın maksimum genişliği. Milimetre cinsinden, aşağı yuvarlanmış olarak.
totalLengthMm Araç ve tüm römorkların toplam uzunluğu. Milimetre cinsinden, aşağı yuvarlanmış olarak.
totalWeightKg Brüt araç ağırlığı (römork ve yük dahil). Kilogram cinsinden ve aşağı yuvarlanmış olarak.
totalAxleCount Araç ve tüm römorklardaki toplam aks sayısı. Tam.
trailerInfo (İsteğe bağlı) Her fragman için bir nesne içeren bir dizi. Kamyon gibi römorku olmayan araçlar için atlayın.
hazardousGoodsTypes (İsteğe bağlı) Gemideki tehlikeli maddeleri belirten bir dizi. PATLAYICILAR, GAZLAR, YANICI, TUTUŞABİLİR, ORGANİK, ZEHİR, AŞINDIRICI, ASPİRASYON TEHLİKESİ, ÇEVRESEL TEHLİKE, DİĞER

Alan maskelerini kullanma

En iyi sonuçlar için, yanıtta istediğiniz alanları tam olarak belirtmek üzere isteğinize X-Goog-FieldMask başlığını ekleyin. Alan maskeleri, gecikmeyi azaltır ve önemli tavsiye alanlarını almanızı sağlar. Rota, aracınız için geçerli olan bir veya daha fazla kısıtlama içerip içermediğini gösterdiğinden, alan maskesine her zaman en az routes.travelAdvisory.routeRestrictionsPartiallyIgnored ekleyin.

Routes API ile FieldMasks hakkında daha fazla bilgi için bu makaleye bakın.

Ücretli geçişler

Ücretli olmayan yolları tercih etmek için bir isteğin routeModifiers özelliğinde avoidTolls değerini belirtin. Rota değiştiriciler hakkında daha fazla bilgi için Kaçınılacak rota özelliklerini belirtme başlıklı makaleyi inceleyin.

avoidTolls belirtilmesi, yanıtta ücretsiz rotaların yer alacağını garanti etmez. Bazı durumlarda, başlangıç noktası ile hedef arasında seyahat etmek için paralı yol kullanmak gerekir. Routes API isteğinizin fieldmask'ine routes.warnings eklediyseniz ücretli yollar içeren rotalar bu alanda buna göre açıklama eklenerek belirtilir.

Tam curl isteği örneği

Tipik bir yarı römorklu kamyon için tam bir curl isteği aşağıda verilmiştir. Bu örnekte uç nokta, üstbilgiler ve istek gövdesi yer almaktadır.

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

computeRoutes yanıtını yorumlama

Routes API'ye yapılan başarılı bir istek, bir veya daha fazla olası rotayı içeren bir JSON yanıt nesnesi döndürür.

Önemli yanıt alanları

  • Kodlanmış rota geometrisi: routes.polyline. Bu, rotayı haritada oluşturmak için kullanılabilir.
  • Tahmini gezi süresi: routes.duration (saniye cinsinden). Büyük araçlar için rota oluşturma yolculuk süresi, yol ağındaki gerçek kamyonların gözlemlenen seyahat hızları üzerinde eğitilmiş yeni bir model kullanır. Ayrıca, tahmini yolculuk süresini beklenen kalkış zamanına ekleyerek TVS'yi hesaplamak için de kullanılabilir.
  • Rotanın toplam mesafesi: routes.distanceMeters (metre cinsinden).
  • Rota jetonu: routes.routeToken. Bu, hesaplanmış rotayı tam olarak temsil eden opak bir jetondur. Sürücüye aynı kamyona özel rotanın gösterilmesini sağlamak için bu jetonu Navigation SDK'sına iletirsiniz. Bunu nasıl yapacağınız hakkında daha fazla bilgi için Adım adım navigasyon sağlama kılavuzunu inceleyin.

Rota güvenliği işaretlerini kontrol etme

Yanıt aldığınızda yapmanız gereken ilk şey, rota güvenliği işaretlerini kontrol etmektir. Sağlanan bir rota, araca uygun olmamasına neden olan bir veya daha fazla kısıtlama içeriyorsa travelAdvisory.routeRestrictionsPartiallyIgnored alanı true olarak ayarlanır.

Bu alan, "Bu rota olası bir sorun için işaretlendi mi?" sorusunu yanıtlamak üzere işaret görevi görür.

  • false(veya yanıttan çıkarıldı): Rota işaretlenmemiştir. Sistem, istekte sağladığınız parametrelerle tamamen uyumlu olduğuna inanılan bir rota buldu.
  • true: Rota işaretlenmiştir. Sistem, tamamen uygun bir rota bulamadı ve güvenli veya yasal olmayabilecek "en iyi çaba" rotasını döndürdü. Bu rota çok dikkatli kullanılmalıdır.

Örnek: computeRoutes yanıtı

Bu, yukarıda gösterilen isteğe ilişkin örnek bir yanıttır. travelAdvisory nesnesinde routeRestrictionsPartiallyIgnored işaretinin yer almadığını unutmayın. Bu, rotanın işaretlenmediğini ve aracın profiline tamamen uygun olduğuna inanıldığını gösterir.

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

Kamyon rotalarının matrisini alma

Birçok olası seyahatin seyahat sürelerini aynı anda hesaplamak için computeRouteMatrix uç noktasını kullanarak birçok başlangıç ve hedef arasındaki seyahat sürelerini ve mesafeleri verimli bir şekilde karşılaştırmak üzere üst düzey planlama yapın. Örneğin, yeni bir teslim alma konumuna en yakın kamyonu bulmak için bu işlevden yararlanabilirsiniz. Amacınız için kullanmak istediğiniz araç kaynağını belirledikten sonra, önerilen aracın rota ayrıntılarını ve rota jetonunu almak için computeRoutes isteği gönderebilirsiniz.

computeRouteMatrix kullanmak için her kaynak nesnesinde vehicleInfo belirtirsiniz.

Örnek istek

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

Örnek yanıt

Yanıtta, her nesnenin bir başlangıç-hedef çifti için süreyi ve distanceMeters değerini içerdiği bir dizi yer alır.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

Sonraki adımlar