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 poli ç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, Tercih Edilen Rotalar ücreti ü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 çizgiler, çoklu çizgi (REST) veya çoklu çizgi (gRPC) nesnesi ile temsil edilir. Yanıtta rota, bacak ve adım düzeyinde bir çok çizgi döndürebilirsiniz.

Yanıt alanı maskesini kullanarak döndürülecek poli çizgiyi belirtin:

  • Rota düzeyinde, yanıt alan maskesine routes.polyline ekleyerek yanıtta bir çok ç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

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

  • Noktaların kayan nokta hassasiyeti

    Noktalar, tek hassasiyetli kayan nokta biçiminde temsil edilen enlem ve boylam değerleri olarak belirtilir. Bu yöntem, küçük değerler (tam olarak temsil edilebilir) 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.

  • Poli çizgiyi oluşturan noktaların sayısı

    Nokta sayısı arttıkça çoklu çizgi daha düzgün olur (ö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 dizisi 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 routes.travelAdvisory.speedReadingIntervals

    • Bacak düzeyinde, routes.legs.travelAdvisory ekleyerek rotanın her bir bacağı için yanıtta 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, trafik hızı bilgilerini içeren speedReadingIntervals adlı bir dizi alanı içerir. Dizideki her nesne, bir SpeedReadingInterval (REST) veya SpeedReadingInterval (gRPC) nesnesi tarafından 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ı örtüşmeden 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ıç dizini olmamasının, proto3 uygulamalarına göre 0 diziniyle eşleştiğini unutmayın.

startPolylinePointIndex ve endPolylinePointIndex değerleri her zaman art arda gelmez. Ö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 başlıklı makaleleri inceleyin.

Ö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'ler, Melbourne'dan Perth'e kadar jeodezik segmentler içeren kalın bir mavi poli çizgisi ekler. 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.

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

Rota boyunca arama özelliğiyle kodlanmış çoklu çizgileri kullanma

Hesaplanmış bir rota boyunca arama yapmak için Places API Metin Arama'yı kullanın. Önceden hesaplanmış bir rotanın kodlanmış çoklu çizgisini Routes API'den Text Search isteğine iletirsiniz. Yanıt, arama ölçütleriyle eşleşen ve belirtilen rotanın yakınında bulunan yerleri içerir. Ayrıntılar için rota boyunca arama başlıklı makaleyi inceleyin.

Örneğin, başlangıç noktası ile varış noktası arasındaki rota üzerinde bulunan kafeleri döndürmek için:

Node.js

const API_KEY = 'YOUR_API_KEY';
const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes';
const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';



function init(){
    const routes_request = {
        "origin":{
            "address": "1600 Amphitheatre Parkway, Mountain View, CA"
        },
        "destination":{
            "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
        },
        "travelMode": "DRIVE"
    };
    const textSearch_request = {
        "textQuery": "cafe",
        "searchAlongRouteParameters": {
            "polyline": {
                "encodedPolyline": ""
            }
        }
    };
    fetchResources(routes_service,routes_request).then(routes => {
        textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline;
        fetchResources(textSearch_service,textSearch_request).then(places => {
            console.log(places);
        });
    });
}
async function fetchResources(resource,reqBody){
    const response = await fetch(resource, {
        method: 'POST',
        body: JSON.stringify(reqBody),
        headers: {
            'Content-Type': 'application/json', 
            'X-Goog-Api-Key': API_KEY, 
            'X-Goog-FieldMask': '*'
        }
    });
    const responseJSON = await response.json();
    return responseJSON;
}
init();