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ştirilmemiştir. Temel bir çoklu çizgi döndüren istekler, Routes Basic ücreti üzerinden faturalandırılır. Routes API için faturalandırma hakkında daha fazla bilgi edinin.

• Trafik durumuna duyarlı çoklu çizgi, rota boyunca trafik koşulları hakkında bilgi içerir. Trafik koşulları, çoklu çizginin belirli bir aralığında geçerli olan hız kategorileri (NORMAL, SLOW, TRAFFIC_JAM) şeklinde ifade edilir. Trafiğe duyarlı çoklu çizgi istekleri, Tercih Edilen Rota fiyatı üzerinden faturalandırılır. Rotalar API'si için faturalandırma hakkında daha fazla bilgi edinin. Ayrıntılar için Çoklu çizgi kalitesini yapılandırma başlıklı makaleyi inceleyin.

Çoklu çizgiler hakkında daha fazla bilgi için aşağıdaki makaleleri inceleyin:

• Çoklu çizgilerle ilgili kavramsal bilgiler

• Etkileşimli Çoklu Çizgi Kodlayıcı Yardımcı Programı, kullanıcı arayüzünde kodlanmış çoklu çizgiler oluşturmanıza veya çoklu çizgilerin kodunu çözerek haritada görüntülemenize olanak tanır. Örneğin, aşağıdaki kod tarafından oluşturulan bir çoklu çizgiyi çözmek için bu yardımcı programı kullanın.

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

Çoklu çizgi, Polyline (REST) veya Polyline (gRPC) nesnesiyle gösterilir. Yanıtta rota, ayak 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ıtta bir çoklu çizgi döndürün.

• Aşama düzeyinde, routes.legs.polyline öğesini ekleyerek rotanın her aşaması için yanıtta bir çoklu çizgi döndürün.

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

Örneğin, rotanın tamamı, her bir bölüm ve her bölümün her bir adımı için çoklu çizgi 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 çoklu çizgisini, rotanın her ayağını ve ayağın her 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 kaynak ve bir hedef 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 yol noktası eklerseniz döndürülen rotada iki bölüm bulunur:

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 ayak ve rotanın tamamı 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 gösterilebilen) için iyi sonuç verir ancak kayan nokta yuvarlama hataları nedeniyle değerler arttıkça hassasiyet azalır.

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

• Çoklu çizgi oluşturan nokta sayısı

  Nokta sayısı ne kadar fazlaysa çoklu çizgi o kadar düzgün olur (özellikle eğrilerde).

  computeRoutes yönteminde (REST) ve ComputeRoutes'ta bu, polylineQuality tarafından kontrol edilir.

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

Çoklu çizgi türünü kontrol etmek için polylineEncoding isteği seçeneğini kullanın. polylineEncoding özelliği, çoklu çizginin ENCODED_POLYLINE (varsayılan) olarak mı kodlanacağını kontrol eder. Bu durumda Encoded Polyline Algorithm Format kullanılır. Alternatif olarak, GEO_JSON_LINESTRING olarak kodlanabilir. Bu durumda GeoJSON LineString formatı kullanılır.

Ö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 ile çoklu çizgi, az sayıda nokta kullanılarak oluşturulur ve HIGH_QUALITY'ye kıyasla daha düşük 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 isteğinde bulunma

Yukarıda gösterilen örneklerin tümü, trafik bilgisi içermeyen temel ç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.

Trafiğe duyarlı çoklu çizgiler, rota üzerindeki trafik koşulları hakkında bilgi içerir. Trafik koşulları, yanıt çoklu çizgisinin belirli bir aralığı için hız kategorileri (NORMAL, SLOW, TRAFFIC_JAM) şeklinde ifade edilir. Aralıklar, başlangıç (dahil) ve bitiş (hariç) çoklu çizgi noktalarının indeksleriyle 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"
}

Trafiğe duyarlı bir çoklu çizginin hesaplanması için istekte bulunmak üzere 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 değerini DRIVE veya TWO_WHEELER olarak ayarlayın. Diğer seyahat modlarıyla ilgili istekler hata döndürür.

• İstekle birlikte TRAFFIC_AWARE veya TRAFFIC_AWARE_OPTIMAL yönlendirme tercihini belirtin. Daha fazla bilgi için Kalite ve gecikme süresini yapılandırma başlıklı makaleyi inceleyin.

• Yanıt özelliklerinin döndürülmesini 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 routes.travelAdvisory.speedReadingIntervals değerini belirtin.

  • Ayak düzeyinde, routes.legs.travelAdvisory öğesini 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 ayak) 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, trafik hızı bilgilerini içeren speedReadingIntervals adlı bir dizi alanı içerir. Dizideki her nesne, SpeedReadingInterval (REST) veya SpeedReadingInterval (gRPC) nesnesiyle temsil edilir.

SpeedReadingInterval nesnesi, NORMAL, SLOW veya TRAFFIC_JAM gibi bir rota aralığı için hızlı okuma içerir. Nesne dizisinin tamamı, rotanın çoklu ç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 tanımlanır. Aralıktaki başlangıç dizininin olmamasının, proto3 uygulamalarına uygun olarak 0 dizinine 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. dizine kadar aynıydı.

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

Çoklu çizgi uzantıları boyunca özel renklendirme, konturlar ve desenler dahil olmak üzere Google Haritalar SDK'larının sunduğu çeşitli özellikleri kullanarak haritada trafiğe duyarlı çoklu çizgiler 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ı kullananlar, 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 bir çizgi olarak gösterilirken "YAVAŞ" hız kalın turuncu bir çizgi olarak gösterilebilir.

Aşağıdaki snippet'ler, Melbourne'den Perth'e jeodezik segmentler içeren 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) başlıklı makaleleri inceleyin.

Android

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));

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

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;

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 ile kodlanmış çoklu çizgileri kullanma

Hesaplanmış bir rota boyunca arama yapmak için Places API (Yeni) içinde Metin Arama (Yeni) özelliğini kullanın. Routes API Compute Routes'tan önceden hesaplanmış bir rotanın kodlanmış çoklu çizgisini Text Search (New) isteğine iletiyorsunuz. Yanıtta, arama ölçütleriyle eşleşen ve belirtilen rotanın yakınında bulunan yerler gösterilir. Ayrıntılı bilgi için Rota boyunca arama yapma başlıklı makaleyi inceleyin.

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

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();