Mesafe Matrisi Hizmeti

Genel bakış

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

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

Başlarken

Maps JavaScript API'de Mesafe Matrisi hizmetini kullanmadan önce, Google Cloud Console'da Mesafe Matrisi API'sinin etkinleştirildiğinden emin olmak için öncelikle Maps JavaScript API'yi ayarlayın.

Etkin API'lerinizin listesini görüntülemek için:

  1. Google Cloud Console'a gidin.
  2. Bir proje seçin düğmesini tıklayın, ardından Maps JavaScript API için ayarladığınız projeyi seçin ve Aç'ı tıklayın.
  3. Kontrol Paneli'ndeki API listesinde Mesafe Matrisi API'sini arayın.
  4. API'yi listede görüyorsanız her şey hazır demektir. API listelenmiyorsa etkinleştirin:
    1. Kitaplık sekmesini görmek için sayfanın üst kısmından API'Yİ ETKİNLEŞTİR'i seçin. Alternatif olarak, sol kısımdaki menüden Kitaplık'ı seçin.
    2. DISTANCE Matrix API'yi arayın, ardından sonuç 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'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 kullanımınız için 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ünü inceleyin.

Not: Mesafe Matrisi hizmetine gönderilen her sorgu, izin verilen öğe sayısıyla sınırlandırılır. Burada kaynak sayısı, 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 Maps API'nin 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ından sonra yürütülecek bir geri çağırma yöntemi iletmeniz gerekir.

Mesafe Matrisi'ne, kodunuza google.maps.DistanceMatrixService oluşturucu nesnesi üzerinden erişebilirsiniz. DistanceMatrixService.getDistanceMatrix() yöntemi, Mesafe Matrisi hizmetine bir istek başlatır. Bu örnekte, kalkış noktası, varış noktaları ve ulaşım şeklinin yanı sıra yanıtı aldıktan sonra yürütülecek bir geri çağırma yöntemi ile birlikte DistanceMatrixRequest nesne değişmez değeri aktarılır.

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öster

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

  • origins (gerekli): Bir veya daha fazla adres dizesi, google.maps.LatLng nesne ya da mesafe ve zaman hesaplanacak Yer nesneleri içeren bir dizi.
  • destinations (gerekli): Bir veya daha fazla adres dizesi, google.maps.LatLng nesne ya da mesafe ve zaman hesaplanacak Yer nesneleri içeren bir dizi.
  • travelMode (isteğe bağlı): Yol tarifi hesaplanırken kullanılacak ulaşım şekli. Seyahat modları ile ilgili bölüme bakın.
  • transitOptions (isteğe bağlı): Yalnızca travelMode TRANSIT olan istekler için geçerli olan seçenekler. Geçerli değerler, nakliye seçenekleri bölümünde açıklanmıştır.
  • drivingOptions (isteğe bağlı), yalnızca travelMode öğesinin DRIVING olduğu istekler için geçerli olan değerleri belirtir. Geçerli değerler, Sürüş Seçenekleri bölümündeki bölümde açıklanmıştır.
  • unitSystem (isteğe bağlı): Mesafe görüntülenirken 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, 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 tarifleri mümkün olduğunda ücretli olmayan rotalar kullanılarak hesaplanır.

Ulaşım Yöntemleri

Saatleri ve mesafeleri hesaplarken kullanılacak ulaşım modunu belirtebilirsiniz. Aşağıdaki ulaşım modları şu anda desteklenmektedir:

  • BICYCLING, bisiklet yolları ve tercih edilen sokaklar üzerinden bisiklet için yol tarifi istiyor (ş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ı aracılığıyla yol tarifi istiyor. Bu seçenek yalnızca isteğin bir API anahtarı içermesi durumunda belirtilebilir. Bu tür isteklerde kullanılabilecek seçenekler için toplu taşıma seçenekleri ile ilgili bölüme bakın.
  • WALKING, yaya yolları ve kaldırımlar (varsa) üzerinden yaya yol tarifi istiyor.

Toplu Taşıma Seçenekleri

Toplu Taşıma Hizmeti şu anda "deneme aşamasındadır". Bu aşamada, API'nin kötüye kullanımını engellemek için hız sınırları uygulayacağız. Nihayetinde, API'nin adil kullanımına bağlı olarak harita yüklemesi başına toplam sorgu sayısı için bir sınır uygulamaya başlayacağız.

Mesafe matrisi için kullanılabilen seçenekler, ulaşım şekillerine göre değişir. Toplu taşıma isteklerinde, avoidHighways ve avoidTolls seçenekleri yok sayılır. Toplu taşımaya özel yönlendirme seçeneklerini, TransitOptions nesne değişmez değeri aracılığıyla belirtebilirsiniz.

Toplu taşıma istekleri zamana duyarlıdır. Hesaplamalar yalnızca gelecekteki seferler 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 istediğiniz varış zamanını belirtir. Varış saati belirtilirse kalkış saati yok sayılır.
  • departureTime (isteğe bağlı), kalkış zamanı olarak Date nesnesini belirtir. arrivalTime belirtilirse departureTime yoksayılır. departureTime veya arrivalTime için herhangi bir değer belirtilmemişse varsayılan değer şimdi (yani geçerli saat) olur.
  • modes (isteğe bağlı), bir veya daha fazla TransitMode nesne değişmez değeri içeren bir dizidir. Bu alan yalnızca istekte 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 seyahat etmeyi tercih ettiğini gösterir.
    • RAIL, hesaplanan rotanın tren, tramvay, hafif raylı sistem ve metro yoluyla seyahati tercih etmesi gerektiğini belirtir.
    • SUBWAY, hesaplanan rotanın metroyla seyahat etmeyi tercih ettiğini belirtir.
    • TRAIN, hesaplanan rotanın trenle seyahat etmeyi tercih ettiğini gösterir.
    • TRAM, hesaplanan rotanın tramvay ve hafif raylı ulaşımı tercih ettiğini gösterir.
  • routingPreference (isteğe bağlı), toplu taşıma rotası tercihlerini 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 gösterir.

Sürüş Seçenekleri

Beklediğiniz trafik koşullarına göre hedefinize giden en iyi rotanın hesaplanması için kalkış saati belirtmek üzere drivingOptions nesnesini kullanın. Trafikteki tahmini sürenin kötümser, iyimser ya da 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şmez değerinin geçerli olması için gereklidir) Date nesnesi olarak istediğiniz kalkış saatini belirtir. Değer mevcut saate veya gelecekteki bir zamana ayarlanmalıdır. Geçmiş bir tarih seçilemez. (API, saat dilimleri arasında tutarlı bir işleme sağlamak için tüm tarihleri UTC'ye dönüştürür.) İsteğe departureTime özelliğini eklerseniz API, o anki beklenen trafik koşullarına göre en iyi rotayı döndürür ve yanıtta trafikte tahmin edilen süreyi (duration_in_traffic) içerir. Kalkış saati belirtmezseniz (yani, istek drivingOptions içermiyorsa) döndürülen rota, trafik koşullarını dikkate almadan genellikle iyi bir rotadır.

    Not: Kalkış saati belirtilmemişse rota ve süre seçenekleri, yol ağına ve ortalama süreden bağımsız trafik koşullarına göre belirlenir. Yol ağındaki değişiklikler, güncellenen ortalama trafik koşulları ve hizmetin dağıtılmış yapısı nedeniyle belirli bir isteğin sonuçları zaman içinde değişiklik gösterebilir. Sonuçlar, herhangi bir zamanda veya sıklık açısından neredeyse eşdeğer rotalar arasında da farklılık gösterebilir.

  • trafficModel (isteğe bağlı), trafikteki zamanı hesaplarken kullanılacak varsayımları belirtir. Bu ayar, geçmiş ortalamalara göre trafikte tahmin edilen süreyi içeren, yanıttaki duration_in_traffic alanında döndürülen değeri etkiler. 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 ile ilgili bilinen bir bilgi ışığında, döndürülen duration_in_traffic değerinin seyahat süresi için en iyi tahmin olması gerektiğini belirtir. Canlı trafik, departureTime yaklaşırken daha önemli hale geliyor.
    • pessimistic, döndürülen duration_in_traffic değerinin çoğu gündeki gerçek seyahat süresinden uzun olması gerektiğini belirtir. Ancak zaman zaman, özellikle kötü trafik koşullarına sahip olan günler bu değeri aşabilir.
    • optimistic, döndürülen duration_in_traffic değerinin çoğu gündeki gerçek seyahat süresinden daha kısa olduğunu gösterir. Ancak zaman zaman, özellikle iyi trafik koşullarına sahip olan günler, bu değerden daha hızlı olabilir.

Aşağıda, kalkış saatleri ve trafik modeli dahil olmak üzere rotalar için örnek 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ı çağrı, bir DistanceMatrixResponse nesnesi ve bir DistanceMatrixStatus nesnesi döndürür. Bunlar, istekte belirttiğiniz geri çağırma işlevine geçirilir.

DistanceMatrixResponse nesnesi, bir 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ıttaki 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 kodlama uzmanı tarafından biçimlendirildiği şekliyle döndürülür.
  • destinationAddresses, destinations alanında iletilen konumları, coğrafi kodlama uzmanı tarafından döndürülen biçimde 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 birlikte satırın başlangıç noktasının eşleşmesine karşılık gelir. Her kaynak/hedef çifti için durum, süre, mesafe ve ücret bilgilerini (varsa) içerir.
  • Her element aşağıdaki alanları içerir:
    • status: Olası durum kodlarının listesi için Durum Kodları bölümüne göz atın.
    • duration: Bu rota üzerinde seyahat etmek için gereken süredir (saniye ve value alanı) ve text olarak ifade edilir. Metin değeri, istekte belirtilen unitSystem doğrultusunda (veya tercih sağlanmamışsa metrikte) biçimlendirilmiştir.
    • duration_in_traffic: Mevcut trafik koşulları göz önünde bulundurularak bu rotada seyahat etmek için gereken süre. Saniye cinsinden (value alanı) ve text olarak ifade edilir. Metin değeri, istekte belirtilen unitSystem doğrultusunda (veya tercih sağlanmamışsa metrikte) biçimlendirilmiştir. duration_in_traffic, yalnızca trafik verilerinin kullanılabilir olduğu, mode alanının driving olarak ayarlandığı ve departureTime özelliğinin isteğe distanceMatrixOptions alanının bir parçası olarak dahil edildiği Google Haritalar Platformu Premium Planı müşterilerine döndürülür.
    • distance: Bu rotanın toplam mesafesinin metre (value) cinsinden ve text olarak ifadesi. Metin değeri, istekte belirtilen unitSystem doğrultusunda (veya tercih belirtilmemişse metrikte) biçimlendirilmiştir.
    • fare: Bu rotadaki toplam ücreti (toplam bilet maliyetleri) içerir. Bu özellik yalnızca toplu taşıma istekleri ve yalnızca ücret bilgilerinin sunulduğu toplu taşıma şirketleri için iade edilir. Bu 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ı, tüm yanıtın durumunu ve her öğe için bir durumu 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. Kaynaklar ve hedefler arasında hiçbir rota bulunmasa bile bu durum döndürülebilir. Öğe düzeyindeki durum bilgileri için Öğe Durum Kodları bölümüne 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: Kaynakların ve hedeflerin ü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 süre 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 - Bir sunucu hatası nedeniyle Mesafe Matrisi isteği işlenemedi. Tekrar denemeniz durumunda 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 - Kalkış noktası ile 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, o kaynağın sağlanan hedeflerle yaptığı her bir eşleme 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];
      }
    }
  }
}