Distance Matrix Hizmeti (Eski)

Avrupa Ekonomik Alanı'ndaki (AEA) geliştiriciler
Not: Sunucu tarafı kitaplıklar

Genel Bakış

Google'ın Distance Matrix hizmeti, belirli bir seyahat modunu 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 tabanlı yol tarifleri dahil olmak üzere rota bilgileri, istenen tek bir başlangıç ve varış noktası Directions Service'e 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.

Etkin API'lerinizin 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çip Aç'ı tıklayın.
  3. Kontrol paneli'ndeki API listesinde Distance Matrix API (Eski)'yi bulun.
  4. API'yi listede görüyorsanız hazırsınız demektir. API listelenmiyorsa https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com adresinden etkinleştirin.

Fiyatlandırma ve politikalar

Fiyatlandırma

JavaScript Distance Matrix 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: Distance Matrix hizmetine gönderilen her sorgu, izin verilen öğe sayısıyla sınırlıdır. Başlangıç noktası sayısının hedef sayısıyla çarpımı, öğe sayısını belirler.

Politikalar

Distance Matrix hizmetinin kullanımı, Distance Matrix API (Eski) için açıklanan politikalara uygun olmalıdır.

Distance Matrix İstekleri

Google Maps API'nin harici bir sunucuya çağrı yapması gerektiğinden Distance Matrix hizmetine erişim eşzamansızdır. Bu nedenle, sonuçları işlemek için isteğin tamamlanmasının ardından yürütülecek bir geri çağırma yöntemi iletmeniz gerekir.

Kodunuzda Distance Matrix hizmetine google.maps.DistanceMatrixService oluşturucu nesnesi aracılığıyla erişirsiniz. DistanceMatrixService.getDistanceMatrix() yöntemi, Distance Matrix hizmetine bir istek gönderir ve bu isteğe başlangıç noktalarını, varış noktalarını ve seyahat modunu içeren bir DistanceMatrixRequest nesne değişmez değeri 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): Mesafe ve sürenin hesaplanacağı bir veya daha fazla adres dizesi, google.maps.LatLng nesnesi ya da Place nesnesi içeren bir dizi.
  • destinations (zorunlu): Mesafe ve sürenin hesaplanacağı bir veya daha fazla adres dizesi, google.maps.LatLng nesnesi ya da Place nesnesi içeren bir dizi.
  • travelMode (isteğe bağlı): Yol tarifi hesaplanırken kullanılacak ulaşım modu. 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, nakliye 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:
    • google.maps.UnitSystem.METRIC (varsayılan)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (isteğe bağlı): true ise başlangıç ve varış noktaları arasındaki rotalar, mümkün olduğunca otoyollardan kaçınılacak şekilde hesaplanır.
  • avoidTolls (isteğe bağlı): true ise noktalar arasındaki yol tarifleri, mümkün olan her yerde ücretli olmayan rotalar kullanılarak hesaplanır.

Seyahat Modları

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

  • BICYCLING, bisiklet yolları ve tercih edilen sokaklar üzerinden bisiklet için yol tarifi ister (şu anda yalnızca ABD'de ve bazı Kanada şehirlerinde kullanılabilir).
  • DRIVING (varsayılan), yol ağını kullanan standart arabayla yol tarifini belirtir.
  • 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, yaya yolları ve kaldırımlar (varsa) üzerinden yaya yol tarifi ister.

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ırlamaları uygulayacağız. Zaman içinde, API'nin adil kullanımına dayalı 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şiklik gösterir. Toplu taşıma isteklerinde avoidHighways ve avoidTolls seçenekleri yoksayılır. TransitOptions nesne değişmez değeri aracılığıyla toplu taşımaya özel rota seçenekleri belirtebilirsiniz.

Toplu taşıma istekleri zamana duyarlıdır. Yalnızca gelecekteki zamanlar için hesaplama yapı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ı), istenen varış zamanını Date nesnesi olarak belirtir. Varış zamanı belirtilirse kalkış zamanı yok sayılır.
  • departureTime (isteğe bağlı), istenen kalkış saatini Date nesnesi olarak belirtir. arrivalTime belirtilirse departureTime yok sayılır. departureTime veya arrivalTime için bir değer belirtilmezse varsayılan olarak geçerli zaman kullanılır.
  • 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 bir API anahtarı varsa dahil edilebilir. Her TransitMode, tercih edilen bir toplu taşıma modunu 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 belirtir.
    • SUBWAY, hesaplanan rotada metroyla seyahatin tercih edilmesi gerektiğini belirtir.
    • 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ı 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 etkileyebilirsiniz. Bu alan yalnızca istekte bir API anahtarı varsa belirtilebilir. Aşağıdaki değerlere izin verilir:
    • FEWER_TRANSFERS, hesaplanan rotada sınırlı sayıda aktarma tercih edilmesi gerektiğini gösterir.
    • LESS_WALKING, hesaplanan rotada sınırlı miktarda yürüyüşün tercih edilmesi gerektiğini belirtir.

Sürüş Seçenekleri

Beklenen trafik koşulları göz önünde bulundurularak hedefinize 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ı ile canlı trafiğe dayalı 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), istenen kalkış saatini 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ı bir şekilde işlenmesini 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ına göre en iyi rotayı döndürür ve yanıta trafikteki tahmini süreyi (duration_in_traffic) ekler. Bir 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ı), trafikte geçen 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 trafikte geçirilen tahmini süreyi içerir. Varsayılan değer: best_guess. 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 bilinenlere göre seyahat süresinin en iyi tahmini olması gerektiğini belirtir. Canlı trafik, departureTime şu ana yaklaştıkça 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 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ün 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'
  }
}

Distance Matrix Yanıtları

Distance Matrix 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 hesaplanabilen her başlangıç/varış noktası ç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"
      }
    } ]
  } ]
}

Distance Matrix Sonuçları

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

  • originAddresses, Distance Matrix 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ı bir başlangıç noktasına karşılık gelen DistanceMatrixResponseRow nesnelerinden oluşan bir dizidir.
  • elements, rows öğesinin alt öğeleridir ve satırın başlangıç noktasının her bir hedefle eşleşmesine karşılık gelir. Her başlangıç/varış noktası ç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ı 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 belirtilen unitSystem değerine göre (veya tercih belirtilmemişse metrikte) biçimlendirilir.
    • duration_in_traffic: Mevcut trafik koşulları dikkate alınarak bu rotada seyahat etmenin ne kadar süreceği, saniye cinsinden (value alanı) ve text olarak ifade edilir. Metin değeri, istekte belirtilen unitSystem değerine göre (veya tercih belirtilmemişse metrikte) biçimlendirilir. duration_in_traffic yalnızca trafik verilerinin mevcut olduğu, mode değerinin driving olarak ayarlandığı ve departureTime değerinin istekteki distanceMatrixOptions alanının bir parçası olarak dahil edildiği durumlarda döndürülür.
    • distance: Bu rotanın metre (value) ve text olarak ifade edilen toplam mesafesi. Metin değeri, istekte belirtilen unitSystem değerine göre (veya tercih belirtilmemişse metrikte) biçimlendirilir.
    • fare: Bu rotadaki toplam ücreti (yani toplam bilet maliyetlerini) içerir. Bu özellik yalnızca toplu taşıma istekleri ve ücret bilgilerinin mevcut olduğu toplu taşıma sağlayıcıları için döndürülür. Bu bilgiler şunlardı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ı

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

Yanıt Durum Kodları

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

  • OK: İstek geçerli. Bu durum, başlangıç ve varış noktaları arasında rota bulunamadığında da 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 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: İsteğiniz 25'ten fazla başlangıç noktası veya 25'ten fazla hedef içeriyor.
  • 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 Distance Matrix hizmetini kullanmasını reddetti.
  • UNKNOWN_ERROR: Sunucu hatası nedeniyle Distance Matrix 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 için coğrafi kod oluşturulamadı.
  • OK: Yanıt geçerli bir sonuç içeriyor.
  • ZERO_RESULTS: Başlangıç ve varış noktaları 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 her eşleşmesi 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];
      }
    }
  }
}