Distance Matrix Hizmeti

Avrupa Ekonomik Alanı (AEA) geliştiricileri
Not: Sunucu tarafı kitaplıkları

Genel Bakış

Google'ın Mesafe Matrisi hizmeti, belirli bir ulaşım şeklini kullanarak birden fazla başlangıç ve hedef arasındaki seyahat mesafesini ve yolculuk süresini hesaplar.

Bu hizmet ayrıntılı rota bilgileri döndürmez. Çoklu çizgiler ve metin biçimindeki yol tarifleri de dahil olmak üzere rota bilgileri, istenen tek başlangıç ve hedef Yol Tarifi Hizmeti'ne iletilerek alınabilir.

Başlarken

Maps JavaScript API'deki Distance Matrix hizmetini kullanmadan önce, Google Cloud Console'da Maps JavaScript API için ayarladığınız projede Distance Matrix API'nin (Eski) etkinleştirildiğinden emin olun.

Etkinleştirilen API'lerinizin listesini görüntülemek için:

  1. Google Cloud Console'a gidin.
  2. Proje seç düğmesini tıklayın, ardından Maps JavaScript API için ayarladığınız projeyi seçip Aç'ı tıklayın.
  3. Kontrol paneli'ndeki API listesinde Distance Matrix API (Eski)'yi bulun.
  4. Listede API'yi görüyorsanız hazırsınız demektir. API listelenmemişse https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com adresinden etkinleştirin.

Fiyatlandırma ve politikalar

Fiyatlandırma

JavaScript Mesafe Matrisi hizmetinin fiyatlandırma ve kullanım politikaları hakkında bilgi edinmek için Distance Matrix API (Eski) ile ilgili Kullanım ve Faturalandırma bölümüne bakın.

Not: Mesafe Matrisi hizmetine gönderilen her sorgu, izin verilen öğe sayısıyla sınırlıdır. Başlangıç noktalarının sayısı ile hedef noktalarının sayısı çarpılarak öğe sayısı belirlenir.

Politikalar

Mesafe Matrisi hizmetinin kullanımı, Mesafe Matrisi API'si (Eski) için açıklanan politikalara uygun olmalıdır.

Mesafe Matrisi İstekleri

Google Haritalar API'sinin harici bir sunucuya çağrı yapması gerektiğinden Mesafe Matrisi hizmetine erişim eşzamansızdır. Bu nedenle, sonuçları işlemek için isteğin tamamlanması üzerine yürütülecek bir geri çağırma yöntemi iletmeniz gerekir.

Kodunuzda Mesafe Matrisi hizmetine google.maps.DistanceMatrixService oluşturucu nesnesi üzerinden erişirsiniz. DistanceMatrixService.getDistanceMatrix() yöntemi, Mesafe Matrisi hizmetine bir istek başlatır ve bu isteğe başlangıç noktalarını, hedefleri ve seyahat modunu içeren bir DistanceMatrixRequest nesne değişmezi ile yanıt alındığında yürütülecek bir geri çağırma yöntemi iletir.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

Örneği görüntüleyin

DistanceMatrixRequest aşağıdaki alanları içerir:

  • origins (zorunlu) — Bir veya daha fazla adres dizesi, google.maps.LatLng nesnesi ya da mesafe ve zamanın hesaplanacağı Yer nesnesi içeren bir dizi.
  • destinations (zorunlu) — Mesafenin ve sürenin hesaplanacağı bir veya daha fazla adres dizesi, google.maps.LatLng nesnesi ya da Yer nesnesi içeren bir dizi.
  • travelMode (isteğe bağlı): Yol tarifi hesaplanırken kullanılacak ulaşım şekli. Ulaşım şekilleri bölümüne bakın.
  • transitOptions (isteğe bağlı): Yalnızca travelMode değerinin TRANSIT olduğu istekler için geçerli olan seçenekler. Geçerli değerler, toplu taşıma seçenekleri bölümünde açıklanmıştır.
  • drivingOptions (isteğe bağlı), yalnızca travelMode değerinin DRIVING olduğu istekler için geçerli olan değerleri belirtir. Geçerli değerler, Sürüş Seçenekleri bölümünde açıklanmıştır.
  • unitSystem (isteğe bağlı): Mesafeyi gösterirken kullanılacak birim sistemi. Kabul edilen değerler şunlardır:
    • google.maps.UnitSystem.METRIC (varsayılan)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (isteğe bağlı): true ise kaynaklar ve hedefler arasındaki rotalar, mümkün olduğunda otoyollardan kaçınılacak şekilde hesaplanır.
  • avoidTolls (isteğe bağlı): true ise noktalar arasındaki yol tarifleri mümkün olduğunda ücretli olmayan yollar kullanılarak hesaplanır.

Ulaşım şekilleri

Süreleri ve mesafeleri hesaplarken hangi ulaşım şeklinin kullanılacağını belirtebilirsiniz. Şu anda aşağıdaki seyahat modları desteklenmektedir:

  • BICYCLING istekleri Bisiklet yolları ve tercih edilen caddeler üzerinden bisikletle yol tarifi (şu anda yalnızca ABD'de ve Kanada'daki bazı şehirlerde kullanılabilir).
  • DRIVING (varsayılan) Karayolu ağını kullanarak standart araba yol tariflerini gösterir.
  • TRANSIT toplu taşıma rotaları üzerinden yol tarifi ister. Bu seçenek yalnızca istek bir API anahtarı içeriyorsa belirtilebilir. Bu tür isteklerde kullanılabilen seçenekler için toplu taşıma seçenekleri bölümüne bakın.
  • WALKING istekleri yaya yolları ve kaldırımlar üzerinden (mümkün olduğunda) yaya yol tarifleri.

Toplu Taşıma Seçenekleri

Toplu Taşıma Hizmeti şu anda "deneysel" aşamadadır. Bu aşamada, API'nin kötüye kullanımını önlemek için sıklık sınırları uygulayacağız. API'nin adil kullanımına bağlı olarak, harita yükleme başına toplam sorgu sayısına bir sınır getireceğiz.

Mesafe matrisi isteği için kullanılabilen seçenekler seyahat modlarına göre değişir. Toplu taşıma isteklerinde avoidHighways ve avoidTolls seçenekleri yoksayılır. TransitOptions nesne değişmezi aracılığıyla toplu taşıma araçlarına özel rota seçenekleri belirtebilirsiniz.

Transit istekleri zamana duyarlıdır. Yalnızca gelecekteki zamanlar için hesaplamalar döndürülür.

TransitOptions nesne değişmezi aşağıdaki alanları içerir:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

Bu alanlar aşağıda açıklanmıştır:

  • arrivalTime (isteğe bağlı), istenen varış zamanını Date nesnesi olarak belirtir. Varış zamanı belirtilmişse kalkış zamanı yoksayılır.
  • departureTime (isteğe bağlı), istenen kalkış zamanını Date nesnesi olarak belirtir. arrivalTime belirtilmişse departureTime yoksayılır. departureTime veya arrivalTime için değer belirtilmezse varsayılan olarak şu anki saat kullanılır.
  • modes (isteğe bağlı), bir veya daha fazla TransitMode nesne değişmezi içeren bir dizidir. Bu alan yalnızca istekte bir API anahtarı varsa eklenebilir. Her TransitMode, tercih edilen bir toplu taşıma şeklini belirtir. Aşağıdaki değerlere izin verilir:
    • BUS, hesaplanan rotada otobüsle seyahatin tercih edilmesi gerektiğini gösterir.
    • RAIL, hesaplanan rotada tren, tramvay, hafif raylı sistem ve metro ile seyahatin tercih edilmesi gerektiğini gösterir.
    • SUBWAY, hesaplanan rotada metroyla seyahatin tercih edilmesi gerektiğini gösterir.
    • TRAIN, hesaplanan rotada trenle seyahatin tercih edilmesi gerektiğini gösterir.
    • TRAM, hesaplanan rotada tramvay ve hafif raylı sistemle seyahatin tercih edilmesi gerektiğini gösterir.
  • routingPreference (isteğe bağlı), toplu taşıma rotalarıyla ilgili tercihleri belirtir. Bu seçeneği kullanarak, API'nin seçtiği varsayılan en iyi rota yerine döndürülen seçenekleri tercih edebilirsiniz. Bu alan yalnızca istek bir API anahtarı içeriyorsa belirtilebilir. Aşağıdaki değerlere izin verilir:
    • FEWER_TRANSFERS hesaplanan rotada sınırlı sayıda aktarmanın tercih edilmesi gerektiğini gösterir.
    • LESS_WALKING Hesaplanan rotada sınırlı miktarda yürüyüş tercih edilmesi gerektiğini gösterir.

Sürüş Seçenekleri

Beklenen trafik koşulları göz önünde bulundurularak hedefinize ulaşmak için en iyi rotayı hesaplarken kalkış zamanını belirtmek üzere drivingOptions nesnesini kullanın. Ayrıca, trafikteki tahmini sürenin kötümser, iyimser veya geçmiş trafik koşullarına ve canlı trafiğe göre en iyi tahmin olmasını isteyip istemediğinizi de belirtebilirsiniz.

drivingOptions nesnesi aşağıdaki alanları içerir:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Bu alanlar aşağıda açıklanmıştır:

  • departureTime (drivingOptions nesne değişmezinin geçerli olması için zorunlu), istenen kalkış zamanını Date nesnesi olarak belirtir. Değer, geçerli zamana veya gelecekteki bir zamana ayarlanmalıdır. Geçmişte olamaz. (API, farklı saat dilimlerinde tutarlı işlem yapılmasını sağlamak için tüm tarihleri UTC'ye dönüştürür.) İsteğe departureTime dahil ederseniz API, o sırada beklenen trafik koşulları göz önüne alındığında en iyi rotayı döndürür ve yanıta trafikteki tahmini süreyi (duration_in_traffic) ekler. Kalkış saati belirtmezseniz (yani istek drivingOptions içermiyorsa) döndürülen rota, trafik koşulları dikkate alınmadan genel olarak iyi bir rotadır.
  • trafficModel (isteğe bağlı) trafikteki süreyi hesaplarken kullanılacak varsayımları belirtir. Bu ayar, yanıttaki duration_in_traffic alanında döndürülen değeri etkiler. Bu alan, geçmiş ortalamalara göre trafikteki tahmini süreyi içerir. Varsayılan olarak best_guess değerine ayarlanır. Aşağıdaki değerlere izin verilir:
    • bestguess (varsayılan), döndürülen duration_in_traffic değerinin, hem geçmiş trafik koşulları hem de canlı trafik hakkında bilinenler göz önüne alındığında seyahat süresinin en iyi tahmini olması gerektiğini gösterir. Canlı trafik, departureTime şu ana ne kadar yakın olursa o kadar önemli hale gelir.
    • pessimistic, döndürülen duration_in_traffic değerinin çoğu günde gerçek seyahat süresinden daha uzun olması gerektiğini gösterir. Ancak trafik koşullarının özellikle kötü olduğu bazı günlerde bu değer aşılabilir.
    • optimistic, döndürülen duration_in_traffic değerinin çoğu günde gerçek seyahat süresinden daha kısa olması gerektiğini gösterir. Ancak trafik koşullarının özellikle iyi olduğu bazı günlerde bu değerden daha hızlı olabilir.

Aşağıda, kalkış saati ve trafik modeli de dahil olmak üzere sürüş rotaları için örnek bir DistanceMatrixRequest verilmiştir:

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Mesafe Matrisi Yanıtları

Mesafe Matrisi hizmetine yapılan başarılı bir çağrı, DistanceMatrixResponse nesnesi ve DistanceMatrixStatus nesnesi döndürür. Bunlar, istekte belirttiğiniz geri çağırma işlevine iletilir.

DistanceMatrixResponse nesnesi, rota hesaplanabilen her başlangıç/hedef çifti için mesafe ve süre bilgilerini içerir.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

Mesafe Matrisi Sonuçları

Yanıt içinde desteklenen alanlar aşağıda açıklanmıştır.

  • originAddresses, Mesafe Matrisi isteğinin origins alanında iletilen konumları içeren bir dizidir. Adresler, coğrafi kodlayıcı tarafından biçimlendirildiği şekilde döndürülür.
  • destinationAddresses, destinations alanında iletilen konumları içeren bir dizidir. Bu dizi, coğrafi kodlayıcı tarafından döndürülen biçimdedir.
  • rows, her satırı bir kaynağa karşılık gelen DistanceMatrixResponseRow nesnelerinden oluşan bir dizidir.
  • elements, rows öğesinin alt öğeleridir ve satırın kaynağının her hedefle eşleştirilmesine karşılık gelir. Her başlangıç/varış noktası çifti için durum, süre, mesafe ve ücret bilgileri (varsa) yer alır.
  • Her element aşağıdaki alanları içerir:
    • status: Olası durum kodlarının listesi için Durum Kodları bölümüne bakın.
    • duration: Bu rotada seyahat etmek için gereken süre, saniye cinsinden (value alanı) ve text olarak ifade edilir. Metin değeri, istekte (veya tercih sağlanmadıysa metrikte) belirtilen unitSystem göre biçimlendirilir.
    • duration_in_traffic: Mevcut trafik koşulları dikkate alınarak bu rotada seyahat etmek için gereken süre. Saniye cinsinden (value alanı) ve text olarak ifade edilir. Metin değeri, istekte (veya tercih sağlanmadıysa metrikte) belirtilen unitSystem göre biçimlendirilir. The duration_in_traffic is only returned where traffic data is available, the mode is set to driving, and departureTime is included as part of the distanceMatrixOptions field in the request.
    • distance: Bu rotanın toplam mesafesi, metre (value) cinsinden ve text olarak ifade edilir. Metin değeri, istekte (veya tercih belirtilmediyse metrikte) belirtilen unitSystem göre biçimlendirilir.
    • fare: Bu rotadaki toplam ücreti (yani toplam bilet maliyetlerini) içerir. Bu özellik yalnızca toplu taşıma istekleri ve yalnızca ücret bilgilerinin mevcut olduğu toplu taşıma sağlayıcıları için döndürülür. Bu bilgiler arasında şunlar yer alır:
      • currency: Tutarın ifade edildiği para birimini gösteren ISO 4217 para birimi kodu.
      • value: Yukarıda belirtilen para biriminde toplam ücret tutarı.

Durum Kodları

Mesafe Matrisi yanıtı, yanıtın tamamı için bir durum kodu ve her öğe için bir durum içerir.

Yanıt Durumu Kodları

DistanceMatrixResponse için geçerli olan durum kodları DistanceMatrixStatus nesnesinde iletilir ve şunları içerir:

  • OK: İstek geçerlidir. Bu durum, başlangıç ve hedef noktalar arasında rota bulunmasa bile döndürülebilir. Öğe düzeyindeki durum bilgileri için Öğe Durum Kodları'na bakın.
  • INVALID_REQUEST — Sağlanan istek geçersizdi. Bu durum genellikle zorunlu alanların eksik olmasından kaynaklanır. Yukarıdaki desteklenen alanlar listesine bakın.
  • MAX_ELEMENTS_EXCEEDED — Başlangıç ve varış noktalarının çarpımı, sorgu başına sınırı aşıyor.
  • MAX_DIMENSIONS_EXCEEDED — Talebinizde 25'ten fazla kaynak veya 25'ten fazla hedef vardı.
  • OVER_QUERY_LIMIT — Uygulamanız, izin verilen süre içinde çok fazla öğe istedi. Makul bir süre sonra tekrar denerseniz istek başarılı olur.
  • REQUEST_DENIED — Hizmet, web sayfanızın Mesafe Matrisi hizmetini kullanmasını reddetti.
  • UNKNOWN_ERROR: Bir mesafe matrisi isteği, sunucu hatası nedeniyle işlenemedi. Tekrar denerseniz istek başarılı olabilir.

Öğe Durum Kodları

Aşağıdaki durum kodları belirli DistanceMatrixElement nesneleri için geçerlidir:

  • NOT_FOUND: Bu eşlemenin kaynağı ve/veya hedefi coğrafi olarak kodlanamadı.
  • OK: Yanıt geçerli bir sonuç içeriyor.
  • ZERO_RESULTS: Başlangıç ve varış noktası arasında rota bulunamadı.

Sonuçları ayrıştırma

DistanceMatrixResponse nesnesi, istekte iletilen her kaynak için bir row içerir. Her satırda, söz konusu kaynağın sağlanan hedefle eşleştirilmesi için bir element alanı bulunur.

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}