Rota çizgisi isteğinde bulunma

Avrupa Ekonomik Alanı'ndaki (AEA) geliştiriciler

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 yerleştirilmiş trafik bilgileri yoktur. Temel ç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.

  • Trafiğe 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) cinsinden ifade edilir. Trafiğe duyarlı çoklu çizgi istekleri, Routes Preferred ü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 bakın.

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

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

Çoklu çizgi, Polyline (REST) veya Polyline (gRPC) nesnesiyle temsil edilir. 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ıta routes.polyline değerini yanıt alan maskesine ekleyerek yanıtta bir çoklu çizgi döndürün.

  • Etap düzeyinde, routes.legs.polyline parametresini ekleyerek rotanın her etabı için yanıtta bir çoklu çizgi döndürün.

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

Örneğin, tüm rota, her ayak ve her ayağın her adımı için bir çoklu ç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 her bir ayağı ve ayağın her bir 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 bir 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 bir ara yol noktası eklerseniz döndürülen rota iki bölüm 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 sahip iki ayak 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 temsil edilen enlem ve boylam değerleri olarak belirtilir. Bu yöntem, küçük değerler (tam olarak temsil edilebilen) 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 çizgiyi 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 istek seçeneğini kullanın. polylineEncoding özelliği, çoklu çizginin ENCODED_POLYLINE (varsayılan) olarak kodlanıp kodlanmayacağını kontrol eder. Bu, Kodlanmış Çoklu Çizgi Algoritması Biçimi'nin kullanılacağı anlamına gelir. GEO_JSON_LINESTRING ise GeoJSON LineString biçiminin kullanılacağı anlamına gelir.

Ö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 değerinden 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 ö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 bilgilerini içermesini de isteyebilirsiniz.

Trafik bilgisine dayalı çoklu çizgiler, rota boyunca 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) 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 ve 4 arasındaki NORMAL trafik gösterilmektedir:

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

Trafiğe duyarlı bir çoklu çizgi 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 değerini DRIVE veya TWO_WHEELER olarak ayarlayın. Diğer seyahat modları için yapılan istekler hata döndürür.

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

  • Yanıt özelliklerini döndürmeyi 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 değerini 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, bir SpeedReadingInterval (REST) veya SpeedReadingInterval (gRPC) nesnesiyle temsil edilir.

SpeedReadingInterval nesnesi, rota aralığı için hız ölçümünü içerir (ör. NORMAL, SLOW veya TRAFFIC_JAM). 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ıkta başlangıç dizini olmaması, proto3 uygulamalarına uygun olarak 0 dizinine karşılık gelir.

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

Google Haritalar SDK'ları tarafından sunulan çeşitli özellikleri (ör. özel renklendirme, konturlar ve çoklu çizgi uzantıları boyunca desenler) kullanarak trafiğe duyarlı çoklu çizgileri 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

Maps SDK 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 bir çizgiyle, "YAVAŞ" hız ise kalın turuncu bir çizgiyle 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

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

Hesaplanan bir rota boyunca arama yapmak için Places API'deki (Yeni) Text Search (Yeni) özelliğini kullanın. Routes API Compute Routes'tan önceden hesaplanmış bir rotanın kodlanmış çoklu çizgisini Text Search (New) isteğine iletirsiniz. Yanıt, arama ölçütleriyle eşleşen ve belirtilen rotanın yakınında bulunan yerleri içerir. 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:

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