Rota çizgisi isteğinde bulunma

Hem computeRoutes yöntemi (REST) hem de ComputeRoutes yöntemi (gRPC), yanıtın bir parçası olarak bir çok ç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 için faturalandırma hakkında daha fazla bilgi edinin.

  • Trafik bilinçli çoklu çizgi, rotadaki trafik koşulları hakkında bilgi içerir. Trafik koşulları, poli çizginin belirli bir aralığında geçerli olan hız kategorileri (NORMAL, SLOW, TRAFFIC_JAM) açısından ifade edilir. Trafik bilincine sahip çoklu çizgi isteklerine, Rotalar Tercih Edilen fiyatı üzerinden faturalandırılır. Routes API için faturalandırma hakkında daha fazla bilgi edinin. Ayrıntılar için Poli çizgi kalitesini yapılandırma başlıklı makaleyi inceleyin.

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

Rota, bacak veya adım için temel bir poli çizgisi isteme

Çoklu çizgi, çoklu çizgi (REST) veya çoklu çizgi (gRPC) nesnesi ile temsil edilir. Yanıtta rota, ayak ve adım düzeyinde bir çoklu çizgi döndürebilirsiniz.

Yanıt alanı maskesini kullanarak döndürülecek polilini belirtin:

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

  • Bacak düzeyinde, routes.legs.polyline öğesini ekleyerek rotanın her bir bacağı için yanıtta bir poli çizgi döndürün.

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

Örneğin, rotanın tamamı, her bir kol ve her bir kolun her bir adımı için bir çok çizgi döndürmek istiyorsanız:

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, rotanın her bir kolunun ve kolun her bir adımını 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 bir hedef içerdiğinden döndürülen rota yalnızca tek bir bölüm içerir. Bu nedenle, yol segmenti ve rota için çoklu çizgi aynıdır.

İsteğe ara yol noktası eklerseniz döndürülen rota iki bölümden oluşur:

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 sahip iki yol segmenti ve tüm rota için bir çoklu çizgi 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 yöntem, küçük değerler (tam olarak temsil edilebilen) için iyi sonuç verir ancak değerler arttıkça kayan noktalı yuvarlama hataları nedeniyle hassasiyet azalır.

    computeRoutes yönteminde (REST) ve ComputeRoutes işlevinde 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önteminde (REST) ve ComputeRoutes işlevinde bu, polylineQuality tarafından kontrol edilir.

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

Poli çizgisi türünü kontrol etmek için polylineEncoding istek seçeneğini kullanın. polylineEncoding mülkü, çoklu çizginin ENCODED_POLYLINE (varsayılan) olarak kodlanıp kodlanmayacağını (Kodlanmış Çoklu Çizgi Algoritması Biçimi kullanılacak) veya GEO_JSON_LINESTRING olarak kodlanıp kodlanmayacağını (GeoJSON Satır Dizesi biçimi kullanılacak) kontrol eder.

Örneğin, istek metninde:

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, poli çizginin kalitesini HIGH_QUALITY veya OVERVIEW (varsayılan) olarak belirtir. OVERVIEW ile çok sayıda nokta kullanılarak oluşturulan çoklu çizginin istek gecikmesi HIGH_QUALITY'ten daha düşüktür.

Örneğin, istek metninde:

{
  "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",
  ...
}

Trafik durumunu dikkate alan bir çoklu çizgi isteme

Yukarıda gösterilen örneklerin tümü temel çoklu çizgiler döndürür. Yani trafik bilgileri içermeyen çoklu çizgiler döndürür. Ayrıca, çoklu çizginin rota ve rotanın her bir ayağı için trafik bilgileri içermesini de isteyebilirsiniz.

Trafik bilincine sahip çok çizgiler, rotadaki trafik koşulları hakkında bilgi içerir. Trafik koşulları, yanıt poli çizgisinin belirli bir aralığı için hız kategorileri (NORMAL, SLOW, TRAFFIC_JAM) olarak ifade edilir. Aralıklar, başlangıç (dahil) ve bitiş (hariç) poli çizgisi noktalarının dizinleriyle tanımlanır.

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

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

Trafik bilincine sahip bir çok çizgiyi hesaplama isteği göndermek 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 modlarıyla ilgili istekler hata döndürür.

  • İstekte TRAFFIC_AWARE veya TRAFFIC_AWARE_OPTIMAL yönlendirme tercihini belirtin. Daha fazla bilgi için Kaliteyi ve gecikmeyi yapılandırma başlıklı makaleyi inceleyin.

  • Yanıt özelliklerinin döndürüleceğ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 ş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'

Trafik bilincine sahip bir çok çizgi için örnek yanıt

Yanıtta trafik verileri çoklu çizgide kodlanır ve RouteLegTravelAdvisory nesnesi (her aşama) 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, 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 okuması içerir. Nesne dizisinin tamamı, rotanın poli çizgisinin tamamını çakışma olmadan kapsar. Belirtilen bir aralığın başlangıç noktası, önceki aralığın bitiş noktasıyla aynıdır.

Her aralık, startPolylinePointIndex, endPolylinePointIndex ve ilgili hız kategorisiyle açıklanır. Aralık içinde başlangıç dizininin olmamasının, proto3 uygulamalarına uygun olarak 0 dizine karşılık geldiğini unutmayın.

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

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

Bu durumda, trafik koşulları 2. dizinden 4. diziye kadar aynıydı.

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

Trafik durumunu dikkate alan çoklu çizgileri, Google Haritalar SDK'ları tarafından sunulan çeşitli özelliklerden (ör. özel renklendirme, çizgiler ve çoklu çizgi segmentleri boyunca desenler) yararlanarak haritada göstermenizi ö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ının kullanıcıları, hız kategorileri ile çoklu çizgi oluşturma şemaları arasında özelleştirilmiş bir eşleme mantığı tanımlayabilir. Örneğin, "NORMAL" hızı haritada kalın mavi çizgi olarak, "YAVAŞ" hızı ise kalın turuncu çizgi olarak göstermeye karar verilebilir.

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 için Görünümleri özelleştirme (Android için) ve Poli çizgiyi özelleştirme (iOS için) başlıklı makaleleri inceleyin.

Yapay Zeka

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