Distance Matrix Hizmeti

Not: Sunucu tarafı kitaplıklar

Bu sayfada, Maps JavaScript API ile kullanılabilen istemci tarafı hizmeti açıklanmaktadır. Sunucunuzda Google Haritalar web hizmetleriyle çalışmak istiyorsanız Google Haritalar Hizmetleri için Node.js İstemcisi'ne göz atın. Bu bağlantıdaki sayfada, Google Haritalar Hizmetleri için Java İstemcisi, Python İstemcisi ve Go İstemcisi de tanıtılmaktadır.

Genel Bakış

Maps JavaScript API Referansı'na da bakın: Mesafe Matrisi

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

Bu hizmet, ayrıntılı rota bilgileri döndürmez. Poli çizgiler ve metin yol tarifleri dahil olmak üzere rota bilgileri, istenen tek bir başlangıç ve hedefi Yol Tarifi Hizmeti'ne iletilerek elde edilebilir.

Başlarken

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

Etkin 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 oluşturduğunuz projeyi seçin ve Aç'ı tıklayın.
3. Kontrol panelindeki API listesinde Distance Matrix API'yi bulun.
4. API'yi listede görürseniz hazırsınız demektir. API listede yoksa etkinleştirin:
   1. Sayfanın üst kısmında API'yi etkinleştir'i seçerek Kitaplık sekmesini görüntüleyin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı da seçebilirsiniz.
   2. Distance Matrix API'yi arayın ve sonuçlar listesinden seçin.
   3. ETKİNLEŞTİR'i seçin. İşlem tamamlandığında Kontrol paneli'ndeki API listesinde Distance Matrix API görünür.

Fiyatlandırma ve politikalar

Fiyatlandırma

16 Temmuz 2018'den itibaren Haritalar, Rotalar ve Yerler için kullandıkça öde türünde yeni bir fiyatlandırma planı kullanıma sunuldu. 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 Matrix API'nin 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. Bu sınırda, öğe sayısını başlangıç sayısının hedef sayısıyla çarpımı belirler.

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'nin harici bir sunucuya çağrı yapması gerektiğinden, Mesafe Matrisi hizmetine erişme işlemi eşzamanlı değildir. Bu nedenle, sonuçları işlemek için istek tamamlandıktan sonra çalıştırılacak bir geri çağırma yöntemi iletmeniz gerekir.

Mesafe Matrisi hizmetine, kodunuzdaki google.maps.DistanceMatrixService kurucu nesnesi aracılığıyla erişirsiniz. DistanceMatrixService.getDistanceMatrix() yöntemi, Mesafe Matrisi hizmetine bir istek gönderir. Bu istek, başlangıç noktalarını, varış noktalarını ve seyahat modunu içeren bir DistanceMatrixRequest nesne değişmez nesnesi ve yanıt alındıktan sonra çalıştırılacak bir geri çağırma yöntemi ile birlikte gönderilir.

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 sürenin hesaplanacağı bir veya daha fazla adres dizesini, google.maps.LatLng nesnesini ya da Place nesnesini içeren bir dizi.
• destinations (zorunlu) — Mesafe ve sürenin hesaplanacağı bir veya daha fazla adres dizesini, google.maps.LatLng nesnesini ya da Place nesnesini içeren bir dizi.
• travelMode (isteğe bağlı): Yol tarifini hesaplarken 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örüntülerken 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, mümkün olduğunda otoyollardan kaçınacak şekilde başlangıç ve varış noktaları arasındaki rotalar hesaplanır.
• avoidTolls (isteğe bağlı) — true ise noktalar arasındaki rotalar, mümkün olduğunda ücretli olmayan yollar kullanılarak hesaplanır.

Not: durationInTraffic alanı artık kullanımdan kaldırılmıştır. Daha önce, Google Haritalar Platformu Premium Plan müşterilerinin sonucun mevcut trafik koşullarını dikkate alan bir süre içermesi gerekip gerekmediğini belirtmek için kullandıkları önerilen yöntemdi. Bunun yerine drivingOptions alanını kullanmalısınız.

Ulaşım Şekilleri

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

• BICYCLING bisiklet yolları ve tercih edilen sokaklar üzerinden bisiklet yolu tarifi ister (şu anda yalnızca ABD ve bazı Kanada şehirlerinde kullanılabilir).
• DRIVING (varsayılan) karayolu ağını kullanan standart arabayla yol tarifini gösterir.
• TRANSIT toplu taşıma rotaları üzerinden yol tarifi isteğinde bulunur. 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 isteklerinde, yaya yolları ve kaldırımlar (varsa) üzerinden yürüyüş yol tarifi istenir.

Toplu Taşıma Seçenekleri

Toplu Taşıma Hizmeti şu anda "denemelidir". Bu aşamada, API kötüye kullanımını önlemek için hız sınırlamaları uygulayacağız. API'nin adil kullanımına göre, harita yükleme başına toplam sorgu sayısı için bir sınırlama uygulayacağız.

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. Toplu taşımaya özgü yönlendirme seçeneklerini TransitOptions obje değişmezi aracılığıyla belirtebilirsiniz.

Aktarım istekleri zamana bağlıdır. Hesaplamalar yalnızca gelecekteki zamanlar için 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ı belirtilirse kalkış zamanı 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 bir değer belirtilmezse varsayılan olarak şimdiki saate (yani geçerli saate) ayarlanır.
• modes (isteğe bağlı), bir veya daha fazla TransitMode nesne literalı içeren bir dizidir. Bu alan yalnızca istek bir API anahtarı içeriyorsa dahil edilebilir. Her TransitMode, tercih edilen bir toplu taşıma şeklini belirtir. Aşağıdaki değerlere izin verilir:
  • BUS, hesaplanan rotanın otobüsle seyahat etmeyi tercih edeceğini gösterir.
  • RAIL, hesaplanan rotanın tren, tramvay, hafif raylı sistem ve metro ile seyahat etmeyi tercih etmesi gerektiğini gösterir.
  • SUBWAY, hesaplanan rotanın metroyla seyahat etmeyi tercih edeceğini gösterir.
  • TRAIN, hesaplanan rotanın trenle seyahat etmeyi tercih etmesi gerektiğini gösterir.
  • TRAM, hesaplanan rotanın tramvay ve hafif raylı sistemle seyahat etmeyi tercih etmesi gerektiğini gösterir.
• routingPreference (isteğe bağlı), toplu taşıma rotaları için 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çenekleri tercih edebilirsiniz. Bu alan yalnızca istek bir API anahtarı içeriyorsa belirtilebilir. Aşağıdaki değerlere izin verilir:
  • FEWER_TRANSFERS Hesaplanan rotanın sınırlı sayıda aktarma seçeneğini tercih etmesi gerektiğini gösterir.
  • LESS_WALKING Hesaplanan rotanın sınırlı miktarda yürüyüşe öncelik vermesi gerektiğini gösterir.

Sürüş Seçenekleri

Beklenen trafik koşulları göz önüne alındığında, varış noktanıza giden en iyi rotayı hesaplamak için drivingOptions nesnesini kullanarak bir kalkış saati belirtin. Ayrıca, trafikte tahmini sürenin kötümser, iyimser veya geçmiş trafik koşullarına ve canlı trafiğe göre en iyi tahmini olmasını da 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 zorunludur), istenen kalkış saatini Date nesnesi olarak belirtir. Değer, mevcut saate veya gelecekteki bir saate ayarlanmalıdır. Geçmişte olamaz. (API, saat dilimlerinde tutarlı bir şekilde işlem yapılmasını sağlamak için tüm tarihleri UTC'ye dönüştürür.) İsteğe departureTime parametresini eklerseniz API, o andaki beklenen trafik koşulları göz önüne alınarak en iyi rotayı döndürür ve yanıta trafikte tahmini süreyi (duration_in_traffic) ekler. Kalkış saati belirtmezseniz (yani istek drivingOptions içermiyorsa) döndürülen rota genellikle trafik koşullarını dikkate almadan iyi bir rotadır.
  Dikkat: Kalkış saati belirtmezseniz seçilen rota ve süre, mevcut yol koşullarına değil, yol ağına ve zamana bağlı olmayan ortalama trafik koşullarına göre belirlenir. Bu nedenle, rotalar geçici olarak kapalı olan yollar içerebilir. Belirli bir istek için sonuçlar, yol ağındaki değişiklikler, güncellenen ortalama trafik koşulları ve hizmetin dağıtılmış yapısı nedeniyle zaman içinde değişiklik gösterebilir. Sonuçlar, herhangi bir zamanda veya sıklıkta neredeyse eşdeğer rotalar arasında da değişiklik gösterebilir.
• trafficModel (isteğe bağlı), trafikteki süreyi hesaplarken kullanılacak varsayımlarını 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 trafikte 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 belirtir. Canlı trafik, departureTime'nin şimdiye ne kadar yakın olduğuna bağlı olarak daha önemli hale gelir.
  • pessimistic, döndürülen duration_in_traffic değerinin çoğu gün gerçek seyahat süresinden daha uzun olması gerektiğini belirtir. Ancak özellikle kötü trafik koşullarının olduğu bazı günlerde bu değer aşılabilir.
  • optimistic, döndürülen duration_in_traffic değerinin çoğu gün gerçek seyahat süresinden daha kısa olması gerektiğini belirtir. Ancak özellikle trafik koşullarının iyi olduğu bazı günlerde bu değerden daha hızlı olabilir.

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

DistanceMatrixResponse nesnesi, rota hesaplanabilecek her bir başlangıç/bitiş ç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çimlendirildiği şekilde döndürülür.
• destinationAddresses, destinations alanında iletilen konumları, coğrafi kodlayıcı tarafından döndürülen biçimde içeren bir dizidir.
• rows, her satırın bir kaynağa karşılık geldiği DistanceMatrixResponseRow nesnelerinden oluşan bir dizidir.
• elements, rows'un alt öğeleridir ve satırın kaynağının her hedefle eşlenmesine karşılık gelir. Her bir başlangıç/varış noktası ç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 listesini görmek için Durum Kodları bölümüne bakın.
  • duration: Bu rotayı kat etmenin saniye cinsinden (value alanı) ve text olarak ifade edilen süresi. Metin değeri, istekte belirtilen unitSystem'e göre biçimlendirilir (veya tercih belirtilmediyse metrik olarak).
  • duration_in_traffic: Mevcut trafik koşulları dikkate alınarak bu rotanın kat edilmesinin saniye cinsinden (value alanı) ve text olarak ifade edilen süresi. Metin değeri, istekte belirtilen unitSystem'e göre biçimlendirilir (veya tercih belirtilmediyse metrik olarak). 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 dahil edilir.
  • distance: Bu rotanın toplam mesafesi, metre (value) cinsinden ve text olarak ifade edilir. Metin değeri, istekte belirtilen unitSystem'e göre biçimlendirilir (veya tercih belirtilmediyse metrik olarak).
  • fare: Bu rotadaki toplam ücreti (yani toplam bilet maliyetini) içerir. Bu özellik yalnızca toplu taşıma istekleri için ve yalnızca ücret bilgilerinin bulunduğ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 biriminde toplam ücret tutarı.

Durum Kodları

Mesafe matrisi yanıtı, yanıtın tamamı 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 iletilir ve şunları içerir:

• OK: İstek geçerlidir. Bu durum, kaynaklar ve hedefler arasında hiçbir rota bulunamadığında bile döndürülebilir. Öğe düzeyindeki durum bilgileri için Öğe Durum Kodları başlıklı makaleyi inceleyin.
• 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: Kaynakların ve hedeflerin çarpımı 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: Mesafe Matrisi hizmetinin web sayfanız tarafından kullanılması hizmet tarafından reddedildi.
• 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 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ır, söz konusu kaynağın sağlanan hedeflerle yaptığı her eşleme için bir element alanı içerir.

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];
      }
    }
  }
}