Rota çizgisi isteğinde bulunma

computeRoutes yöntemi (REST) ve ComputeRoutes yöntemi (gRPC), yanıtın bir 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 trafik bilgileri yerleştirilmez. Temel bir çoklu çizgi döndüren istekler Temel Rotalar ücreti üzerinden faturalandırılır. Routes API için faturalandırma hakkında daha fazla bilgi

  • Trafiğe duyarlı çoklu çizgi, rota boyunca 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 çizgi istekleri, Rotalar Tercih Edilen ücreti üzerinden faturalandırılır. Routes API için faturalandırma 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 için:

Rota, ayak veya adım için temel bir çoklu çizgi isteyin

Çoklu çizgi, Polyline (REST) veya Polyline (gRPC) nesnesiyle temsil edilir. Yanıtta rota, bacak ve adım düzeyinde 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ıta bir çoklu çizgi döndürün.

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

  • Adım düzeyinde, routes.legs.steps.polyline öğesini ekleyerek bacağın her adımı için yanıta bir çoklu çizgi döndürün.

Örneğin, tüm rota, her ayak ve her bacağın her adımı için bir çoklu çizgi döndürmek için:

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 rota, rotanın her ayağı ve ayağın her adımı için çoklu çizgiyi 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 kalkış ve varış noktası içerdiğinden döndürülen rota yalnızca tek bir ayak içerir. Bu nedenle, bacak ve rota için çoklu çizgi aynıdır.

İsteğe ara bir 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 tüm rota 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

Ç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 (hassas şekilde temsil edilebilir) için iyi sonuç verir ancak kayan nokta yuvarlama hataları nedeniyle değerler arttıkça hassasiyet azalır.

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

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

    Nokta sayısı arttıkça çoklu çizgi de pürüzsüz hale gelir (özellikle eğrilerde).

    computeRoutes yöntemi (REST) ve ComputeRoutes'da bu, 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ış Çoklu Çizgi Algoritma Biçimi'nin mi, yoksa GeoJSON LineString biçiminin mi kullanılacağı anlamına gelen GEO_JSON_LINESTRING'in 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'

Çoklu çizgi kalitesini yapılandırma

polylineQuality, çoklu çizginin kalitesini HIGH_QUALITY veya OVERVIEW (varsayılan) olarak belirtir. OVERVIEW kullanıldığında, çoklu çizgi az sayıda nokta kullanılarak oluşturulur ve HIGH_QUALITY ile kıyaslandığı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 örnekler, temel çoklu çizgileri, yani trafik bilgisi içermeyen çoklu çizgileri döndürür. Ayrıca, çoklu çizginin rota ve rotanın her ayağı için trafik bilgileri içermesini isteyebilirsiniz.

Trafiğe duyarlı çoklu çizgiler, rota boyunca trafik koşulları hakkında bilgiler içerir. Trafik koşulları, belirli bir yanıt çoklu çizgi aralığı için hız kategorileri (NORMAL, SLOW, TRAFFIC_JAM) cinsinden 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 çoklu çizgi noktaları 2 ile 4 arasındaki NORMAL trafiği gösterilmektedir:

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

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

  • Trafik hesaplamasını etkinleştirmek için extraComputations dizi 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ıttaki tüm seyahat bilgilerini döndürün. Yalnızca trafik bilgilerini döndürmek için şunu belirtin: routes.travelAdvisory.speedReadingIntervals

    • Bacak düzeyinde, routes.legs.travelAdvisory öğesini ekleyerek rotanın her ayağı için yanıtta yer alan 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 bir bacak) ve RouteTravelAdvisory nesnesi (rota) türündeki travelAdvisory alanında yer alır.

Ö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, speedReadingIntervals adlı ve trafik hızı bilgilerini içeren bir dizi alanı içerir. Dizideki her nesne bir SpeedReadingInterval (REST) veya SpeedReadingInterval (gRPC) nesnesiyle temsil edilir.

SpeedReadingInterval nesnesi, NORMAL, SLOW veya TRAFFIC_JAM gibi bir rota aralığı için hız ölçümü içeriyor. Nesne dizisinin tamamı, rotanın çoklu çizgisinin tamamını çakışmadan kapsar. Belirtilen bir aralığın başlangıç noktası, önceki aralığın bitiş noktasıyla aynıdır.

Her aralık kendi startPolylinePointIndex, endPolylinePointIndex ve karşılık gelen hız kategorisi ile tanımlanır. proto3 uygulamalarına uygun olarak, aralık içinde başlangıç dizini eksikliğinin 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 örnekte, trafik koşulları dizin 2 ile dizin 4 arasında aynıdır.

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

Çoklu çizgi uzantıları boyunca özel renklendirme, çizgi ve desenler gibi Google Haritalar SDK'ları tarafından sunulan ç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 konularına bakın.

Örnek Çoklu çizgi oluşturma

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

Aşağıdaki snippet'lerde Melbourne'dan Perth'e kadar jeodezik bölümler içeren koyu mavi bir çoklu çizgi eklenmiş. Daha fazla bilgi edinmek için Görünümleri özelleştirme (Android için) ve Çoklu çizgiyi özelleştirme (iOS için) konularını inceleyin.

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