Bu kılavuz kimler için hazırlanmıştır? Kamyon veya diğer büyük araçları kullanarak seyahat planlama ve gerçekleştirme 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, tahmini seyahat süresi ve tahmini varış zamanları istemek için Büyük Araç Rotalandırma 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 istiyorsanız Rota Optimizasyonu Kamyon Rotalandırma Dokümanları'na bakın.
Neler öğreneceksiniz?
Bu kursta şunları öğreneceksiniz:
- 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ın bilgilerini belirtin.
- Rota jetonu ve seyahat güvenliği işaretleri dahil olmak üzere yanıtı yorumlayın.
Ön koşullar
- Google Cloud projeniz oluşturulmalı ve Routes API etkinleştirilmelidir.
- Projeniz Büyük Araç Rotalandırma için hazırlanmış olmalıdır. Büyük araç rotası, sınırlı sayıda müşteri tarafından kullanılabilir. Erişim isteğinde bulunmak için bizimle 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ç rotası, ABD'nin bitişik 48 eyaletinde (genel kullanıma açık) ve Japonya'da (deneysel) kullanılabilir. Alaska, Hawaii veya ABD idari bölgelerinde kullanılamaz.
- Sürücü tavsiyesi ve güvenlik 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ı,
routeRestrictionsPartiallyIgnoredalanı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: Büyük araç rotası, 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. Bu bölümdeki kavramlar hem tek rota hem de rota matrisi istekleri için geçerlidir.
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.
Önemli istek parametreleri
Kamyon rotasını etkinleştirmek için istek gövdenize aşağıdaki parametreleri eklemeniz gerekir:
travelMode: Bu değeriTRUCKolarak ayarlayın.routingPreference: Bu değeriTRAFFIC_AWARE_OPTIMALolarak ayarlayın.routeModifiers: Bu nesne, aracınızın özelliklerini tanımladığınızvehicleInfonesnesini içerir.vehicleInfonesnesi aşağıda ayrıntılı olarak açıklanmıştır.
Araç özelliklerini 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çüleri
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, ö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 römorkun genişliği 8' 6" olup 2.590,8 mm'ye denk gelir. 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 rotayla sonuçlanacaktır.
- Yükseklik: 3,35 metre yüksekliğindeki bir köprünün altından geçen rota, 4,1 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.
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ış. 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ış. |
totalLengthMm
|
Araç ve römorkların toplam uzunluğu. | Milimetre cinsinden, aşağı yuvarlanmış. |
totalWeightKg
|
Brüt araç ağırlığı (römork ve yük dahil). | Kilogram cinsinden ve aşağı yuvarlanmış olarak. |
totalAxleCount
|
Araçtaki 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ı elde etmek için yanıtınızda 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. Alan maskesine her zaman en azından routes.travelAdvisory.routeRestrictionsPartiallyIgnored değerini ekleyin. Bu değer, rotada aracınız için geçerli olan bir veya daha fazla kısıtlama olup olmadığını gösterir.
Routes API ile FieldMasks hakkında daha fazla bilgi için bu makaleye göz atı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 belirtmek, 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.
Diğer yönlendirme davranışları
travelMode değerini TRUCK olarak ayarladığınızda API, rotayı büyük araçların manevra kabiliyetine göre otomatik olarak optimize eder. Oluşturulan rotalarda U dönüşü yapılmaz ve küçük yollar yerine eyaletler arası yollar ile otoyollar tercih edilir. Bu davranışları etkinleştirmek için ek parametreler veya değiştiriciler ayarlamanız gerekmez.
computeRoutes ile tek bir rota hesaplama
Bir başlangıç noktası ile bir varış noktası arasında kamyona özel bir rota hesaplamak için computeRoutes uç noktasını kullanın.
Örnek computeRoutes isteğ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
}]
}
}
}'
Örnek computeRoutes yanıtı
Bu, yukarıda gösterilen önceki 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 özellikleriyle tamamen uyumlu olduğu düşünüldüğünü gösterir.
{
"routes": [
{
"distanceMeters": 3426,
"duration": "312s",
"travelAdvisory": {},
"routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
}
]
}
computeRoutes yanıtını yorumlama
computeRoutes uç noktasına yapılan başarılı bir istek, bir veya daha fazla olası rota 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ç rotası 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 tahmini varış zamanını hesaplamak için de kullanılabilir. - Rotanın toplam mesafesi:
routes.distanceMeters(metre cinsinden). - Rota jetonu:
routes.routeToken. Bu, hesaplanan 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'ya iletirsiniz. Ayrıntılar için Android veya iOS için Gezinme SDK'sı kılavuzlarına bakın.
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şaretlenmedi. 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 bir "en iyi çaba" rotası döndürdü. Bu rota çok dikkatli kullanılmalıdır.
Rota matrisi hesaplama (computeRouteMatrix)
Birçok başlangıç ve varış noktası arasındaki seyahat sürelerini ve mesafeleri verimli bir şekilde karşılaştırmak için computeRouteMatrix uç noktasını kullanın. Örneğin, yeni bir teslim alma konumuna en yakın kamyonu bulmak için bu özelliği kullanabilirsiniz. Amacınız için kullanmak istediğiniz araç kaynağını belirledikten sonra, önerilen araçla ilgili rota ayrıntılarını ve rota jetonunu almak için computeRoutes isteği gönderebilirsiniz.
computeRouteMatrix özelliğini kullanmak için vehicleInfo değerini isteğin kökünde değil, her origin nesnesinde belirtirsiniz.
Örnek computeRouteMatrix isteği
{
"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 computeRouteMatrix yanıtı
Yanıt, her nesnenin bir başlangıç-hedef çifti için süreyi ve distanceMeters değerini içerdiği bir dizidir.
[
{
"originIndex": 0,
"destinationIndex": 1,
"status": {},
"distanceMeters": 392372,
"duration": "14037s",
"condition": "ROUTE_EXISTS"
},
{ ... }
]
Sonraki adımlar
- Dönüş dönüş navigasyon sağlama:
routeTokensimgesini Android veya iOS için Navigasyon SDK'sında nasıl kullanacağınızı öğrenin. - Filo düzeyinde optimizasyon gerçekleştirme: Large Vehicle Routing ile Route Optimization API'yi kullanın.
- API referansı: Olası tüm alanların ve değerlerin tam listesi için Routes API Referansı'na bakın.