Mesafe Matrisi Hizmeti

Genel bakış

Google'ın Mesafe Matrisi hizmeti, belirli bir ulaşım şeklini kullanarak birden çok kalkış ve varış noktası arasındaki seyahat mesafesini ve yolculuk süresini hesaplar.

Bu hizmet ayrıntılı rota bilgilerini döndürmez. Çoklu çizgiler ve metin şeklindeki yol tarifleri dahil olmak üzere rota bilgileri, istenen tek başlangıç noktası ve hedefin Yol Tarifi Hizmeti'ne geçirilmesiyle elde edilebilir.

Kullanmaya başlama

Maps JavaScript API'de Mesafe Matrisi hizmetini kullanmadan önce, ilk olarak Maps JavaScript API için oluşturduğunuz projede, Google Cloud Console'da Mesafe Matrisi API'sinin etkinleştirildiğinden emin olun.

Etkin API'ler listenizi görüntülemek için:

  1. Google Cloud Console'a gidin.
  2. Proje seçin düğmesini tıklayın, ardından Maps JavaScript API için oluşturduğunuz projeyi seçin ve 'ı tıklayın.
  3. Kontrol Paneli'ndeki API listesinde Mesafe Matrisi API'sini arayın.
  4. Listede API'yi görüyorsanız her şey hazır demektir. API listede yoksa etkinleştirin:
    1. Sayfanın üst kısmında Kitaplık sekmesini görüntülemek için API'yi ETKİNLEŞTİR'i seçin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı seçin.
    2. Mesafe Matrisi API'sini arayın ve sonuçlar listesinden seçin.
    3. ETKİNLEŞTİR'i seçin. İşlem tamamlandığında, Kontrol Paneli'ndeki API listesinde Mesafe Matrisi API'si görünür.

Fiyatlandırma ve politikalar

Fiyatlandırma

16 Temmuz 2018 tarihinden itibaren Haritalar, Rotalar ve Yerler için yeni bir kullandıkça öde fiyatlandırma planı yürürlüğe girdi. JavaScript Mesafe Matrisi hizmeti kullanımınızla ilgili yeni fiyatlandırma ve kullanım sınırları hakkında daha fazla bilgi edinmek için Mesafe Matrisi API'si için 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. Burada, öğe sayısı kaynak sayısı ile hedef sayısının çarpımıyla tanımlanır.

Politikalar

Mesafe Matrisi hizmetinin kullanımı, Mesafe Matrisi API'si 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ız olarak gerçekleşir. Bu nedenle, isteğin tamamlanmasının ardından sonuçları işlemek üzere callback yöntemi iletmeniz gerekir.

Mesafe Matrisi hizmetine kodunuzdan google.maps.DistanceMatrixService oluşturucu nesnesi aracılığıyla erişirsiniz. DistanceMatrixService.getDistanceMatrix() yöntemi, Mesafe Matrisi hizmetine bir istek göndererek başlangıç noktaları, varış noktaları ve seyahat modunu içeren DistanceMatrixRequest nesne değişmez değerini ve yanıt alındığında yürütülecek bir geri çağırma yöntemini 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) — Mesafe ve zaman hesaplanacak bir veya daha fazla adres dizesi, google.maps.LatLng nesnesi veya Place nesnesi içeren dizi.
  • destinations (zorunlu) — Mesafe ve zaman hesaplanacak bir veya daha fazla adres dizesi, google.maps.LatLng nesnesi veya Place nesnesi içeren dizi.
  • travelMode (isteğe bağlı) — Yol tarifi hesaplanırken kullanılacak ulaşım modu. Ulaşım şekilleri ile ilgili bölüme bakın.
  • transitOptions (isteğe bağlı) - Yalnızca travelMode öğesinin TRANSIT olduğu istekler için geçerli olan seçeneklerdir. 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örüntülerken kullanılacak birim sistem. Kabul edilen değerler şunlardır:
    • google.maps.UnitSystem.METRIC (varsayılan)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (isteğe bağlı) — true ise, kalkış ve varış noktaları arasındaki rotalar mümkün olduğunda otoyollardan kaçınmak için hesaplanır.
  • avoidTolls (isteğe bağlı) — true ise, noktalar arasındaki yol tarifi mümkün olduğunda ücretli olmayan rotalar kullanılarak hesaplanır.

Seyahat Modları

Süre ve mesafeleri hesaplarken kullanılacak ulaşım şeklini belirtebilirsiniz. Şu anda aşağıdaki ulaşım şekilleri desteklenmektedir:

  • BICYCLING, bisiklet yolları ve tercih edilen sokaklar üzerinden bisiklet için yol tarifi ister (şu anda yalnızca ABD ve bazı Kanada şehirlerinde kullanılabilir).
  • DRIVING (varsayılan), yol ağını kullanan standart arabayla yol tariflerini gösterir.
  • TRANSIT, toplu taşıma rotaları üzerinden yol tarifi istiyor. Bu seçenek yalnızca isteğin bir API anahtarı içermesi durumunda belirtilebilir. Bu istek türündeki seçenekler için toplu taşıma seçenekleri ile ilgili bölüme bakın.
  • WALKING, yaya yolları ve kaldırımlar üzerinden (varsa) yaya yol tarifi isteğinde bulunur.

Toplu Taşıma Seçenekleri

Toplu Taşıma Hizmeti şu anda "deneme aşamasındadır". Bu aşamada, API'lerin kötüye kullanımını önlemek için hız sınırları uygulayacağız. Bir süre sonra, API'nin adil kullanımına bağlı olarak harita yükü başına toplam sorgu sayısına bir sınırlama getireceğiz.

Mesafe matrisi isteği için kullanılabilen seçenekler, ulaşım şekillerine göre değişiklik gösterir. Aktarım isteklerinde avoidHighways ve avoidTolls seçenekleri yoksayılır. TransitOptions nesne değişmez değerini kullanarak geçişe özel yönlendirme seçeneklerini belirtebilirsiniz.

Toplu taşıma istekleri zamana duyarlıdır. Hesaplamalar yalnızca gelecekteki zamanlar için döndürülür.

TransitOptions nesne değişmez değeri 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ı), Date nesnesi olarak istenen varış zamanını belirtir. Varış saati belirtilirse kalkış saati yoksayılır.
  • departureTime (isteğe bağlı), Date nesnesi olarak istenen kalkış saatini belirtir. arrivalTime belirtilirse departureTime yoksayılır. departureTime veya arrivalTime için herhangi bir değer belirtilmezse varsayılan olarak şimdi (yani geçerli saat) kullanılır.
  • modes (isteğe bağlı), bir veya daha fazla TransitMode nesne değişmez değerini içeren bir dizidir. Bu alan, yalnızca isteğin bir API anahtarı içermesi durumunda dahil edilebilir. Her TransitMode, tercih edilen toplu taşıma modunu belirtir. Aşağıdaki değerlere izin verilir:
    • BUS, hesaplanan rotanın otobüsle seyahati tercih etmesi gerektiğini belirtir.
    • RAIL, hesaplanan rotanın tren, tramvay, hafif raylı tren ve metroyla seyahat etmeyi tercih etmesi gerektiğini belirtir.
    • SUBWAY, hesaplanan rotanın metroyla seyahati tercih etmesi gerektiğini belirtir.
    • TRAIN, hesaplanan rotanın trenle seyahat etmeyi tercih etmesi gerektiğini belirtir.
    • TRAM, hesaplanan rotanın tramvay ve hafif raylı sistem ile seyahat etmeyi tercih etmesi gerektiğini belirtir.
  • routingPreference (isteğe bağlı), toplu taşıma rotalarıyla ilgili tercihleri belirtir. Bu seçeneği kullanarak, API tarafından seçilen varsayılan en iyi rotayı kabul etmek yerine döndürülen seçeneklere ağırlık verebilirsiniz. Bu alan, yalnızca isteğin bir API anahtarı içermesi durumunda belirtilebilir. Aşağıdaki değerlere izin verilir:
    • FEWER_TRANSFERS, hesaplanan rotanın sınırlı sayıda aktarımı tercih etmesi gerektiğini belirtir.
    • LESS_WALKING, hesaplanan rotanın sınırlı miktarda yürüyüş tercih etmesi gerektiğini belirtir.

Sürüş Seçenekleri

Beklenen trafik koşullarına göre hedefinize giden en iyi rotayı hesaplamak için drivingOptions nesnesini kullanın. Ayrıca, trafikteki tahmini sürenin kötümser mi, iyimser mi yoksa geçmiş trafik koşullarına ve canlı trafiğe göre en iyi tahmin mi olmasını istediğ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şmez değerinin geçerli olması için gereklidir), Date nesnesi olarak istenen kalkış saatini belirtir. Değer, geçerli zamana veya gelecekteki bir zamana ayarlanmalıdır. Geçmiş bir tarih olamaz. (API, farklı saat dilimlerinde tutarlı bir şekilde işlenmesi için tüm tarihleri UTC'ye dönüştürür.) departureTime öğesini isteğe dahil ederseniz API, o anki beklenen trafik koşullarına göre en iyi rotayı döndürür ve yanıta trafikteki tahmini süreyi (duration_in_traffic) dahil eder. Kalkış saati belirtmezseniz (yani istekte drivingOptions yoksa) döndürülen rota, trafik koşullarını dikkate almadan genellikle iyi bir rotadır.
  • trafficModel (isteğe bağlı), trafikteki süre hesaplanırken kullanılacak varsayımları belirtir. Bu ayar, yanıttaki duration_in_traffic alanında döndürülen değeri etkiler ve bu değer, 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), hem geçmiş trafik koşulları hem de canlı trafik hakkında bilinenler göz önünde bulundurulduğunda, döndürülen duration_in_traffic değerinin en iyi seyahat süresi tahmini olması gerektiğini belirtir. departureTime şu ana ne kadar yakınsa canlı trafik daha ö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 belirtir, ancak bazen kötü trafik koşullarına sahip günler bu değeri aşabilir.
    • 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 belirtir. Bununla birlikte, bazen trafik koşullarının çok iyi olduğu günler bu değerden daha hızlı olabilir.

Aşağıda, kalkış saati ve trafik modeli dahil, 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ı, bir DistanceMatrixResponse ve bir DistanceMatrixStatus nesnesi döndürür. Bunlar, istekte belirttiğiniz geri çağırma işlevine iletilir.

DistanceMatrixResponse nesnesi, rotanın hesaplanabileceği her kaynak/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ıtta 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çimlendirildikleri gibi döndürülür.
  • destinationAddresses, coğrafi kodlayıcı tarafından döndürülen biçimde, destinations alanında iletilen konumları içeren bir dizidir.
  • rows, her satır bir kaynağa karşılık gelen DistanceMatrixResponseRow nesne dizisidir.
  • elements, rows öğesinin alt öğeleridir ve her bir hedefle satırın başlangıç noktası çiftine karşılık gelir. Her bir kalkış/varış çifti için durum, süre, mesafe ve ücret bilgilerini (varsa) içerirler.
  • Her element aşağıdaki alanları içerir:
    • status: Olası durum kodlarının listesi için Durum Kodları'na bakın.
    • duration: Bu rota üzerinde seyahat etmek için geçen süre. Saniye cinsinden (value alanı) ve text cinsinden belirtilir. Metin değeri, istekte (veya herhangi bir tercih sağlanmamışsa metrikte) belirtilen unitSystem öğesine göre biçimlendirilir.
    • duration_in_traffic: Mevcut trafik koşulları dikkate alınarak bu rota üzerinde seyahat etmek için geçen süre. Saniye cinsinden (value alanı) ve text cinsinden belirtilir. Metin değeri, istekte (veya herhangi bir tercih sağlanmamışsa metrikte) belirtilen unitSystem öğesine göre biçimlendirilir. duration_in_traffic, yalnızca trafik verilerinin mevcut olduğu, mode öğesinin driving olarak ayarlandığı ve istekteki distanceMatrixOptions alanının bir parçası olarak departureTime öğesinin eklendiği Google Haritalar Platformu Premium Plan müşterilerine döndürülür.
    • distance: Bu rotanın metre (value) cinsinden ve text olarak ifade edilen toplam mesafesi. Metin değeri, istekte (veya herhangi bir tercih sağlanmamışsa metrikte) belirtilen unitSystem öğesine göre biçimlendirilir.
    • fare: Rotadaki toplam ücreti (yani toplam bilet maliyetlerini) içerir. Bu tesis, yalnızca toplu taşıma istekleri için ve ücret bilgilerinin mevcut olduğu toplu taşıma sağlayıcıları için döndürülür. Bilgiler şunları içerir:
      • currency: Tutarın ifade edildiği para birimini belirten bir ISO 4217 para birimi kodu.
      • value: Yukarıda belirtilen para biriminde toplam ücret tutarı.

Durum Kodları

Mesafe Matrisi yanıtı, bir bütün olarak yanıt için bir durum kodu ve her bir öğ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. Başlangıç noktaları ve hedefler arasında rota bulunmasa bile bu durum döndürülebilir. Öğe düzeyindeki durum bilgileri için Öğe Durumu Kodları konusuna bakın.
  • INVALID_REQUEST: Sağlanan istek geçersizdi. Bu durum genellikle zorunlu alanların eksik olmasından kaynaklanır. Yukarıdaki desteklenen alanların listesine bakın.
  • MAX_ELEMENTS_EXCEEDED: Kaynak ve hedeflerden oluşan ürün, sorgu başına sınırı aşıyor.
  • MAX_DIMENSIONS_EXCEEDED: İsteğiniz 25'ten fazla kaynak veya 25'ten fazla hedef içeriyordu.
  • OVER_QUERY_LIMIT — Uygulamanız, izin verilen dönem içinde çok fazla öğe istedi. Makul bir süre sonra tekrar denerseniz istek başarılı olur.
  • REQUEST_DENIED — Hizmet, Mesafe Matrisi hizmetinin web sayfanız tarafından kullanılmasını reddetti.
  • UNKNOWN_ERROR — Sunucu hatası nedeniyle Mesafe Matrisi isteği 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 kodla belirlenemedi.
  • OK: Yanıt geçerli bir sonuç içeriyor.
  • ZERO_RESULTS: Kalkış ve varış noktaları arasında rota bulunamadı.

Sonuçları Ayrıştırma

DistanceMatrixResponse nesnesi, istekte geçirilen her kaynak için bir row içerir. Her satırda, söz konusu başlangıç noktasının sağlanan hedeflerle her bir çifti 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];
      }
    }
  }
}