Rota çizgisi isteğinde bulunma

Hem computeRoutes yöntemi (REST) hem de ComputeRoutes yöntemi (gRPC), yanıtın parçası olarak çoklu çizgiyle temsil edilen rotayı döndürür. Bu API'ler iki tür çoklu çizgi döndürür:

  • Temel çoklu çizgi (varsayılan), bir rotayı temsil eder ancak çoklu çizgiye yerleştirilmiş trafik bilgileri içermez. Temel bir çoklu çizgi döndüren istekler Temel Rotalar ücreti üzerinden faturalandırılır. Routes API'nin faturalandırması hakkında daha fazla bilgi edinin.

  • Trafiğe duyarlı çoklu çizgi, rota üzerindeki trafik koşulları hakkında bilgi içerir. Trafik koşulları, belirli bir çoklu çizgi aralığında geçerli olan hız kategorileri (NORMAL, SLOW, TRAFFIC_JAM) cinsinden ifade edilir. Trafiğe duyarlı çoklu hat istekleri, Tercih Edilen Rotalar ücretine göre faturalandırılır. Rotalar API'sinin faturalandırması hakkında daha fazla bilgi edinin. Ayrıntılar için Çoklu çizgi kalitesini yapılandırma bölümüne göz atın.

Çoklu çizgiler hakkında daha fazla bilgi edinmek için:

Bir rota, bacak veya adım için temel bir çoklu çizgi isteme

Çoklu çizgi, Çoklu Çizgi (REST) veya Çoklu Çizgi (gRPC) nesnesiyle temsil edilir. Yanıtta rota, bacak ve adım seviyesinde bir çoklu çizgi döndürebilirsiniz.

Yanıt alanı maskesini kullanarak hangi çoklu çizginin döndürüleceğini belirtin:

  • Rota düzeyinde, yanıt alanı maskesine routes.polyline ekleyerek yanıtta bir çoklu çizgi döndürün.

  • Bacak seviyesinde, rotanın her bir ayağını routes.legs.polyline ekleyerek yanıtta bir çoklu çizgi döndürün.

  • Adım seviyesinde, bacağın her adımına routes.legs.steps.polyline ekleyerek yanıtta bir çoklu çizgi döndürün.

Örneğin, rotanın tamamı, her ve her bacak için bir çoklu çizgiyi döndürmek üzere:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Bu istek; rotanın her bir ayağı ve yolun her adımı için rotanın çoklu çizgisini içeren aşağıdaki yanıtı döndürür:

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
              "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
          }
        },
          "steps": [
              {
                  "polyline": {
                      "encodedPolyline": "kclcF...@sC@YIOKI"
                  }
              },
              {
                  "polyline": {
                      "encodedPolyline": "wblcF~...SZSF_@?"
                  }
              },
              ...
      ],
      "distanceMeters": 56901,
      "duration": "2420s",
      "polyline": {
        "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
      }
    }
  ]
}

Bu istek yalnızca bir başlangıç ve hedef içerdiğinden, döndürülen rota yalnızca tek bir ayak içerir. Dolayısıyla, bacak ve rotanın çoklu çizgisi aynı.

İsteğe bir ara ara nokta eklerseniz döndürülen rota iki ayak içerir:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "intermediates": [
    { "address": "450 Serra Mall, Stanford, CA 94305, USA"},
  ],
  "travelMode": "DRIVE",
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Bu istek, her biri benzersiz bir çoklu çizgiye ve rotanın tamamı için bir çoklu çizgiye sahip iki ayak döndürür:

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
            "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "kclcFfqch...YIOKI"
                }
            },
        ...
        },
        {
          "polyline": {
            "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "uypeFbo`jVgJq...PoBiC"
                }
            },
        ...
        }
      ],
      "distanceMeters": 68403,
      "duration": "3759s",
      "polyline": {
          "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE"
      }
    }
  ]
}

Çoklu çizgi kalitesi

Bir çoklu çizginin kalitesi aşağıdaki terimlerle açıklanabilir:

  • Noktaların kayan nokta hassasiyeti

    Noktalar, tek duyarlıklı kayan nokta biçiminde gösterilen enlem ve boylam değerleri olarak belirtilir. Bu, küçük değerler için iyi sonuç verir (tam olarak temsil edilebilir) ancak kayan nokta yuvarlama hataları nedeniyle değerler arttıkça hassasiyet azalır.

    computeRoutes yöntemi (REST) ve ComputeRoutes'da polylineEncoding tarafından kontrol edilir.

  • Çoklu çizgiyi oluşturan noktaların sayısı

    Noktalar ne kadar fazla olursa çoklu çizgi o kadar düzgün olur (özellikle eğrilerde).

    computeRoutes yöntemi (REST) ve ComputeRoutes'da polylineQuality tarafından kontrol edilir.

Çoklu çizgi kodlama türünü yapılandırın

Çoklu çizgi türünü kontrol etmek için polylineEncoding istek seçeneğini kullanın. polylineEncoding özelliği, çoklu çizginin ENCODED_POLYLINE (varsayılan) olarak mı kodlanacağını, yani Kodlanmış Çok Çizgili Algoritma Biçimi'nin mi kullanılacağını, GEO_JSON_LINESTRING (GeoJSON Çizgi Dizesi biçimi) mi kullanılacağını kontrol eder.

Örneğin, istek gövdesinde:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "polylineEncoding": "ENCODED_POLYLINE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Poyline kalitesini yapılandırın

polylineQuality, çoklu çizginin kalitesini HIGH_QUALITY veya OVERVIEW (varsayılan) olarak belirtir. OVERVIEW ile çoklu çizgi, az sayıda nokta kullanılarak oluşturulur ve HIGH_QUALITY ile karşılaştırıldığında daha düşük bir istek gecikmesine sahiptir.

Örneğin, istek gövdesinde:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "polylineQuality": "HIGH_QUALITY",
  "polylineEncoding": "ENCODED_POLYLINE",
  "departureTime": "2023-10-15T15:01:23.045123456Z",
  ...
}

Trafiğe duyarlı çoklu çizgi isteme

Yukarıda gösterilen tüm örnekler temel çoklu çizgileri, yani trafik bilgisi içermeyen çoklu çizgileri döndürür. Ayrıca çoklu çizginin, rota ve rotanın her bir ayağı için trafik bilgilerini içermesini de isteyebilirsiniz.

Trafiğe duyarlı çoklu çizgiler, rota üzerindeki trafik koşulları hakkında bilgi içerir. Trafik koşulları, belirli bir yanıt çoklu çizgi aralığı için hız kategorileri (NORMAL, SLOW, TRAFFIC_JAM) ile ifade edilir. Aralıklar, başlangıç (dahil) ve bitiş (hariç) çoklu çizgi noktalarının dizinleriyle tanımlanır.

Örneğin, aşağıdaki yanıtta 2 ve 4. çoklu çizgi noktaları arasındaki NORMAL trafiği gösterilmektedir:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

Trafiğe duyarlı çoklu çizgi hesaplama isteğinde bulunmak için istekte aşağıdaki özellikleri ayarlayın:

  • Trafik hesaplamasını etkinleştirmek için extraComputations dizisi alanını TRAFFIC_ON_POLYLINE olarak ayarlayın.

  • travelMode öğesini DRIVE veya TWO_WHEELER olarak ayarlayın. Diğer ulaşım şekilleriyle ilgili istekler hata döndürür.

  • İstekte TRAFFIC_AWARE veya TRAFFIC_AWARE_OPTIMAL yönlendirme tercihini belirtin. Daha fazla bilgi için Kalite ve gecikmeyi yapılandırma bölümüne bakın.

  • Yanıt özelliklerini döndüreceğini belirten bir yanıt alanı maskesi ayarlayın:

    • Rota düzeyinde, yanıt alanı maskesine routes.travelAdvisory ekleyerek yanıtta tüm seyahat bilgilerini döndürün. Yalnızca trafik bilgilerini döndürmek için routes.travelAdvisory.speedReadingIntervals değerini belirtin

    • Bacak düzeyinde, routes.legs.travelAdvisory ekleyerek rotanın her ayağı için yanıttaki tüm seyahat bilgilerini döndürün. Yalnızca trafik bilgilerini döndürmek için routes.legs.travelAdvisory.speedReadingIntervals değerini belirtin.

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "extraComputations": ["TRAFFIC_ON_POLYLINE"],
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Trafiğe duyarlı çoklu çizgi için örnek yanıt

Yanıtta, trafik verileri çoklu çizgide kodlanır ve RouteLegTravelAdvisory nesnesi (her bacak) ve RouteTravelAdvisory nesnesi (rota) türündeki travelAdvisory alanında bulunur.

Örneğin:

{
  "routes": [
    {
      "legs": {
        "polyline": {
          "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
        },
        // Traffic data for the leg.
        "travelAdvisory": {
          "speedReadingIntervals": [
            {
              "endPolylinePointIndex": 1,
              "speed": "NORMAL"
            },
            {
              "startPolylinePointIndex": 1,
              "endPolylinePointIndex": 2,
              "speed": "SLOW"
            },
            {
              "startPolylinePointIndex": 2,
              "endPolylinePointIndex": 4,
              "speed": "NORMAL"
            }
          ] 
        }
      },
      "polyline": {
        "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
      },
      // Traffic data for the route.
      "travelAdvisory": {
        "speedReadingIntervals": [
          {
            "endPolylinePointIndex": 1,
            "speed": "NORMAL"
          },
          {
            "startPolylinePointIndex": 1,
            "endPolylinePointIndex": 2,
            "speed": "SLOW"
          },
          {
            "startPolylinePointIndex": 2,
            "endPolylinePointIndex": 4,
            "speed": "NORMAL"
          }
        ] 
      }
    }
  ]
}

Hem RouteTravelAdvisory hem de RouteLegTravelAdvisory, trafik hızı bilgilerini içeren speedReadingIntervals adlı bir dizi alanı içerir. Dizideki her nesne, bir SpeedReadingInterval (REST) veya SpeedReadingInterval (gRPC) nesnesiyle temsil edilir.

Bir SpeedReadingInterval nesnesi, NORMAL, SLOW veya TRAFFIC_JAM gibi bir rota aralığı için hız okuması içerir. Nesne dizisinin tamamı, rotanın çoklu çizgisini üst üste bindirmeden bütünüyle kaplar. Belirtilen bir aralığın başlangıç noktası, kendisinden önce gelen aralığın bitiş noktasıyla aynıdır.

Her aralık, startPolylinePointIndex, endPolylinePointIndex ve ilgili hız kategorisiyle tanımlanır. Aralık içinde başlangıç dizini eksikliğinin, proto3 uygulamalarına göre dizin 0'a karşılık geldiğine dikkat edin.

startPolylinePointIndex ve endPolylinePointIndex değerleri her zaman ardışık değildir. Örneğin:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

Bu durumda, trafik koşulları dizin 2 ile dizin 4 arasında aynıdır.

Haritalar SDK'sı ile trafiğe duyarlı çoklu çizgiler oluşturma

Google Haritalar SDK'ları tarafından sunulan, çoklu çizgi uzantıları boyunca özel renklendirme, çizgi ve desenler gibi çeşitli özellikleri kullanarak haritada trafiğe duyarlı çoklu çizgiler görüntülemenizi öneririz. Çoklu çizgileri kullanma hakkında daha fazla bilgi için Android için Çoklu Çizgi Özellikleri ve iOS için Çoklu Çizgi Özellikleri bölümlerine bakın.

Çoklu çizgi oluşturma örneği

Haritalar SDK'sı kullanıcıları, hız kategorileri ile çoklu çizgi oluşturma şemaları arasında özelleştirilmiş bir eşleme mantığı tanımlama olanağına sahiptir. Örneğin, "NORMAL" hızı haritada kalın mavi bir çizgi olarak gösterilirken "YAVAŞ" hız kalın turuncu bir çizgi şeklinde gösterilebilir.

Aşağıdaki snippet'ler, Melbourne'dan Perth'e jeodezik segmentlere sahip kalın mavi bir çoklu çizgi ekler. Daha fazla bilgi için Görünümleri özelleştirme (Android için) ve Çoklu Çizgiyi Özelleştirme (iOS için) bölümlerine göz atın.

Android

Java

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

Kotlin

val line: Polyline = map.addPolyline(
  PolylineOptions()
    .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734))
    .width(25f)
    .color(Color.BLUE)
    .geodesic(true)
)

iOS

Objective-C

GMSMutablePath *path = [GMSMutablePath path];
[path addLatitude:-37.81319 longitude:144.96298];
[path addLatitude:-31.95285 longitude:115.85734];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.strokeWidth = 10.f;
polyline.strokeColor = .blue;
polyline.geodesic = YES;
polyline.map = mapView;

Swift

let path = GMSMutablePath()
path.addLatitude(-37.81319, longitude: 144.96298)
path.addLatitude(-31.95285, longitude: 115.85734)
let polyline = GMSPolyline(path: path)
polyline.strokeWidth = 10.0
polyline.geodesic = true
polyline.map = mapView