Mesafe Matrisi Hizmeti

Genel bakış

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

Bu hizmet ayrıntılı rota bilgisi döndürmez. Çoklu çizgiler ve metin şeklinde yol tarifleri de dahil olmak üzere rota bilgileri, istenen tek kalkış ve varış noktası Yol Tarifi Hizmeti'ne geçirilerek elde edilebilir.

Başlarken

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

Etkin API'lerin listesini 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 Aç'ı tıklayın.
3. Dashboard'daki (Kontrol Paneli) API'ler listesinde Position Matrix API'yi bulun.
4. Listede API'yi görüyorsanız hazırsınız demektir. API listede yoksa API'yi etkinleştirin:
   1. Kitaplık sekmesini görüntülemek için sayfanın üst kısmında API'Yİ ETKİNLEŞTİR'i seçin. Alternatif olarak sol taraftaki menüden Kitaplık'ı da seçebilirsiniz.
   2. Mesafe Matrisi API'sini arayın ve sonuç listesinden bunu seçin.
   3. ETKİNLEŞTİR'i seçin. İşlem tamamlandığında Kontrol Paneli'ndeki API listesinde Mesafe Matrisi API görünür.

Fiyatlandırma ve politikalar

Fiyatlandırma

16 Temmuz 2018'den itibaren Haritalar, Rotalar ve Yerler için yeni bir kullandıkça öde fiyatlandırma planı yürürlüğe girdi. JavaScript Mesafe Matrisi hizmetini kullanımınızla ilgili yeni fiyatlandırma ve kullanım sınırları hakkında daha fazla bilgi edinmek için DISTANCE Matris API'sinin Kullanım ve Faturalandırma bölümünü inceleyin.

Not: Mesafe Matrisi hizmetine gönderilen her sorgu, izin verilen öğe sayısıyla sınırlıdır. Burada kaynak ile hedef sayısı, öğe sayısını tanımlar.

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 yapılır. Bu nedenle, isteği tamamlamak ve sonuçları işlemek için callback (geri çağırma) yöntemi iletmeniz gerekir.

Kodunuzun içindeki Mesafe Matrisi hizmetine google.maps.DistanceMatrixService oluşturucu nesnesi aracılığıyla erişirsiniz. DistanceMatrixService.getDistanceMatrix() yöntemi, Mesafe Matrisi hizmetine bir istek göndererek bu hizmete kaynakları, varış noktalarını ve seyahat modunu içeren sabit bir DistanceMatrixRequest nesne değerinin yanı sıra 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 inceleyin

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

• origins (gerekli): Mesafe ve sürenin hesaplanacağı bir veya daha fazla adres dizesi, google.maps.LatLng nesne veya Place nesnesi içeren dizi.
• destinations (gerekli): Mesafe ve sürenin hesaplanacağı bir veya daha fazla adres dizesi, google.maps.LatLng nesne ya da Place nesnesi içeren dizi.
• travelMode (isteğe bağlı) — Yol tarifleri hesaplanırken kullanılacak ulaşım şekli. Seyahat modları ile ilgili bölüme 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 ile ilgili bölümde açıklanmıştır.
• unitSystem (isteğe bağlı) — Mesafe görüntülenirken 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 başlangıç noktaları ile hedefler arasındaki rotalar, mümkün olduğunda otoyollardan gidilmeyecek şekilde hesaplanır.
• avoidTolls (isteğe bağlı) — true ise, noktalar arasındaki yol tarifleri, mümkün olduğunda ücretli olmayan rotalar kullanılarak hesaplanır.

Ulaşım Şekilleri

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

• BICYCLING, bisiklet yolları ve tercih edilen sokaklar üzerinden bisiklet için yol tarifi talep eder (ş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 istek bir API anahtarı içeriyorsa belirtilebilir. Bu istek türünde kullanılabilen seçenekleri görmek için toplu taşıma seçenekleri bölümüne bakın.
• WALKING, yaya yolları ve kaldırımlar üzerinden (varsa) yaya yol tarifi ister.

Toplu Taşıma Seçenekleri

Toplu Taşıma Hizmeti şu anda "deneysel" bir hizmet. Bu aşamada, API'nin kötüye kullanımını önlemek için hız sınırları uygulayacağız. Sonunda API'nin adil kullanımına dayalı olarak harita yükü başına toplam sorgu sayısını sınırlandıracağız.

Mesafe matrisi isteği için kullanılabilen seçenekler, ulaşım şekillerine göre değişir. Toplu taşıma isteklerinde avoidHighways ve avoidTolls seçenekleri yoksayılır. TransitOptions nesne değişmez değerini kullanarak toplu taşımaya özel rota seçeneklerini belirtebilirsiniz.

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

TransitOptions nesnesi 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ı), istenen varış zamanını Date nesnesi olarak belirtir. Varış saati belirtilirse kalkış saati yoksayılır.
• departureTime (isteğe bağlı), istenen kalkış saatini Date nesnesi olarak belirtir. arrivalTime belirtilirse departureTime yoksayılır. departureTime veya arrivalTime için herhangi bir değer belirtilmezse varsayılan olarak şimdi (yani geçerli zaman) kullanılır.
• modes (isteğe bağlı), bir veya daha fazla TransitMode nesne değişmez değeri içeren dizidir. Bu alan yalnızca istekte bir API anahtarı varsa eklenebilir. Her TransitMode, tercih edilen bir 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ı sistem ve metro ile seyahati tercih etmesi gerektiğini belirtir.
  • SUBWAY, hesaplanan rotanın metroyla seyahati tercih etmesi gerektiğini belirtir.
  • TRAIN, hesaplanan rotanın trenle seyahati tercih etmesi gerektiğini belirtir.
  • TRAM, hesaplanan rotanın tramvay ve hafif raylı sistemle seyahati tercih etmesi gerektiğini belirtir.
• 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 rotayı kabul etmek yerine döndürülen seçeneklere ağırlık verebilirsiniz. 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 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 bir kalkış zamanı belirtmek üzere 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 tahmini mi olmasını istediğinizi de belirtebilirsiniz.

drivingOptions nesnesi şu alanları içerir:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

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

• departureTime (drivingOptions nesnesinin değişmez değerinin geçerli olması için gereklidir), istenen kalkış zamanını Date nesnesi olarak belirtir. Değer, geçerli zamana veya gelecekteki bir zamana ayarlanmalıdır. Geçmiş bir tarih olamaz. (API, farklı saat dilimlerinde işleme tutarlılık sağlamak için tüm tarihleri UTC'ye dönüştürür.) İsteğe departureTime öğesini dahil ederseniz API, o anda beklenen trafik koşullarına göre en iyi rotayı döndürür ve trafikteki tahmini süreyi (duration_in_traffic) yanıta dahil eder. Kalkış saati belirtmezseniz (yani istek drivingOptions içermiyorsa) döndürülen rota, trafik koşulları dikkate alınmadan genellikle en iyi 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. 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 bilinenlere göre, döndürülen duration_in_traffic değerinin en iyi seyahat süresi tahmini olması gerektiğini belirtir. departureTime yaklaştıkça canlı trafik daha önemli hale gelir.
  • pessimistic, döndürülen duration_in_traffic değerinin çoğu gündeki gerçek seyahat süresinden daha uzun olması gerektiğini belirtir. Bununla birlikte, özellikle kötü trafik koşullarının bulunduğu günlerde bu değeri aşabilir.
  • optimistic, döndürülen duration_in_traffic değerinin çoğu gündeki gerçek seyahat süresinden kısa olması gerektiğini belirtir. Bununla birlikte, trafik koşulları özellikle iyi olan günler bu değerden daha hızlı olabilir.

Aşağıda, kalkış saati ve trafik modeli dahil olmak üzere, sürüş rotaları için DistanceMatrixRequest örneği 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 nesnesi 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ı

Bir yanıtta desteklenen alanlar aşağıda açıklanmıştır.

• originAddresses, Mesafe Matrisi isteğinin origins alanında geçirilen konumları içeren bir dizidir. Adresler, coğrafi kodlayıcı tarafından biçimlendirildikçe döndürülür.
• destinationAddresses, coğrafi kodlayıcı tarafından döndürülen biçimde destinations alanında geçirilen 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 satırın başlangıç noktası ile her hedef çiftine karşılık gelir. Her kalkış/hedef çifti için durum, süre, mesafe ve ücret bilgileri (varsa) içerir.
• 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 gereken süre. Saniye cinsinden (value alanı) ve text olarak ifade edilir. Metin değeri, istekte belirtilen unitSystem öğesine (veya herhangi bir tercih sağlanmamışsa metrik cinsinden) göre biçimlendirilir.
  • duration_in_traffic: Mevcut trafik koşulları dikkate alınarak bu rota üzerinde seyahat etmek için gereken süre. Saniye cinsinden (value alanı) ve text olarak ifade edilir. Metin değeri, istekte belirtilen unitSystem öğesine (veya herhangi bir tercih sağlanmamışsa metrik cinsinden) göre biçimlendirilir. duration_in_traffic yalnızca trafik verilerinin mevcut olduğu durumlarda döndürülür. mode, driving olarak ayarlanır ve departureTime, istekteki distanceMatrixOptions alanının bir parçası olarak eklenir.
  • distance: Bu rotanın metre (value) ve text cinsinden toplam mesafesi. Metin değeri, istekte belirtilen unitSystem öğesine göre (veya herhangi bir tercih sağlanmamışsa metrik cinsinden) biçimlendirilir.
  • fare: Bu 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. Bu bilgiler şunları içerir:
    • currency: Tutarın ifade edildiği para birimini belirten ISO 4217 para birimi kodu.
    • value: Yukarıda belirtilen para birimi cinsinden toplam ücret tutarı.

Durum Kodları

Mesafe Matrisi yanıtı, yanıtın bütünü için bir durum kodunun yanı sıra her öğenin durumunu içerir.

Yanıt Durumu Kodları

DistanceMatrixResponse için geçerli olan durum kodları DistanceMatrixStatus nesnesine aktarılır ve şunları içerir:

• OK — İstek geçerli. Başlangıç noktalarından ve hedeflerden herhangi biri arasında rota bulunmasa bile bu durum döndürülebilir. Öğe düzeyindeki durum bilgileri için Öğe Durumu Kodları'na bakın.
• INVALID_REQUEST — Sağlanan istek geçersizdi. Bunun nedeni genellikle zorunlu alanların eksik olmasıdır. Yukarıdaki desteklenen alanların listesini inceleyin.
• MAX_ELEMENTS_EXCEEDED — Kaynakların ve hedeflerin çarpımı, sorgu başına sınırı aşıyor.
• MAX_DIMENSIONS_EXCEEDED: İsteğinizde 25'ten fazla kaynak veya 25'ten fazla hedef bulunuyordu.
• OVER_QUERY_LIMIT — Uygulamanız, izin verilen süre içinde çok fazla öğe istedi. Makul bir süre sonra tekrar denerseniz isteğin başarılı olması gerekir.
• REQUEST_DENIED — Hizmet, web sayfanız tarafından Mesafe Matrisi hizmetinin kullanımını reddetti.
• UNKNOWN_ERROR — Sunucu hatası nedeniyle Mesafe Matrisi isteği işlenemedi. Tekrar denerseniz istek başarılı olabilir.

Öğe Durumu 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 — Kalkış ve hedef 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 başlangıç noktasının sağlanan hedeflerle her eşlemesi 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];
      }
    }
  }
}