Mesafe Matrisi Hizmeti

Genel Bakış

Google'ın Mesafe Matrisi hizmeti seyahati hesaplar birden fazla kalkış ve varış noktası arasındaki mesafe ve yolculuk süresi belirli bir ulaşım şekli seçin.

Bu hizmet ayrıntılı rota bilgisi döndürmez. Güzergah bilgileri çoklu çizgiler ve metin içeren yönler dahil olmak üzere, belirli bir süre için ve varış noktasının Yol Tarifi Hizmeti.

Başlarken

Maps JavaScript API'de Mesafe Matrisi hizmetini kullanmadan önce ilk olarak Mesafe Matrisi API'sinin Google Cloud Console'da oturum açın.

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

  1. Şuraya gidin: Google Cloud Console'da oturum açın.
  2. Proje seçin düğmesini tıklayın, ardından oluşturduğunuz projeyi seçin JavaScript API'sini açın ve Aç'ı tıklayın.
  3. Kontrol Paneli'ndeki API listesinde, Mesafe Matrisi API'si.
  4. Listede API'yi görüyorsanız hazırsınız demektir. API listede yoksa şunu etkinleştirebilirsiniz:
    1. Sayfanın üst kısmında şunu görüntülemek için API'Yİ ETKİNLEŞTİR'i seçin: Kitaplık sekmesine gidin. Alternatif olarak sol taraftaki menüden Kitaplık'ı seçin.
    2. Mesafe Matrisi API'sini aratıp seçin sonuçlar listesinden çıkar.
    3. ETKİNLEŞTİR'i seçin. Süreç tamamlandığında Mesafe Matrisi API, Kontrol paneli.

Fiyatlandırma ve politikalar

Fiyatlandırma

16 Temmuz 2018'den itibaren geçerli olmak üzere, "kullandıkça öde" türünde yeni bir fiyatlandırma planı Haritalar, Rotalar ve Yerler için efekti. Yeni fiyatlandırma hakkında daha fazla bilgi edinmek JavaScript Mesafe Matrisi hizmetini kullanımınızla ilgili kullanım sınırları hakkında daha fazla bilgi edinmek için Kullanım ve Faturalandırma farklı bir yol haritası çıkardık.

Not: Mesafe Matrisi hizmetine gönderilen her sorgu sınırlıdır izin verilen öğe sayısına göre (burada kaynak sayısının hedef sayısı, öğe sayısını tanımlar.

Politikalar

Mesafe Matrisi hizmetinin kullanımı, tanımlanan politikalar Mesafe Matrisi API'si için.

Mesafe Matrisi İstekleri

Mesafe Matrisi hizmetine erişmek eşzamansız olduğundan, Maps API'nin harici bir sunucuya çağrı yapması gerekiyor. Bu nedenle, tamamlanmasının ardından yürütülecek bir callback yöntemi iletmesi isteği gönderin.

Mesafe Matrisi hizmetine kodunuzun içinden erişebilirsiniz. google.maps.DistanceMatrixService oluşturucu nesnesi. DistanceMatrixService.getDistanceMatrix() yöntemi Mesafe Matrisi hizmetine bir istek başlatır ve Kaynakları içeren DistanceMatrixRequest nesne değişmez değeri, güzergâhları ve ulaşım şekli ile birlikte yürütülecek bir geri çağırma yöntemini yanıt alabiliriz.

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): Bir veya daha fazla dize içeren bir dizi adres dizeleri, google.maps.LatLng nesne veya Place uzaklık ve süre hesaplanacak nesnelerden oluşur.
  • destinations (gerekli) — Bir ya da daha fazla adres dizesi, google.maps.LatLng nesne veya Place mesafe ve süre hesaplanacak nesnelerden oluşur.
  • travelMode (isteğe bağlı): Şu modun modu: yardımcı olacak diğer araçlardır. Bu bölümde, seyahat modları hakkında daha fazla bilgi edinin.
  • transitOptions (isteğe bağlı) — Seçenekler yalnızca travelMode şu koşuldaki istekler için geçerlidir: TRANSIT. Geçerli değerler açıklandı toplu taşıma seçenekleri bölümüne bakın.
  • drivingOptions (isteğe bağlı) değerleri (yalnızca travelMode olduğu istekler için geçerli olan değerler) DRIVING. Geçerli değerler açıklandı Sürüş Seçenekleri bölümünde.
  • unitSystem (isteğe bağlı) — Birim sistem mesafeyi gösterirken kullanın. Kabul edilen değerler şunlardır:
    • google.maps.UnitSystem.METRIC (varsayılan)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (isteğe bağlı) — Eğer true, kalkış ve varış noktaları arasındaki rotalar şöyle olacak: otoyoldan izlenecek şekilde yapılan hesaplamadır.
  • avoidTolls (isteğe bağlı) — Eğer true, noktalar arasındaki yol tarifleri şu formülle hesaplanacaktır: mümkünse ücretsiz rota seçin.
ziyaret edin.

Ulaşım Şekilleri

Süreleri ve mesafeleri hesaplarken, her zaman karar verebilirsiniz. Aşağıdaki seyahat modlar şu anda desteklenmektedir:

  • BICYCLING istekleri ve bisiklet yolu üzerinden bisiklet yol tarifi tercih edilen sokaklar (Şu anda yalnızca ABD'de ve Kanada'nın bazı şehirlerinde kullanılabilir).
  • DRIVING (varsayılan) yol ağını kullanarak standart arabayla yol tariflerini gösterir.
  • TRANSIT, şunun üzerinden yol tarifi istiyor: toplu taşıma rotalarına bakın. Bu seçenek yalnızca bir API anahtarı içerir. Toplu taşıma seçenekleri'ni tıklayın.
  • WALKING istekleri yaya yolları üzerinden yaya yol tarifi ve (mümkün olan yerlerde) kaldırın.

Toplu Taşıma Seçenekleri

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

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. Tekliflerinizi otomatikleştirmek ve optimize etmek için veya toplu taşımaya özel rota seçeneklerini TransitOptions nesne değişmez.

Toplu taşıma istekleri zamana duyarlıdır. Yalnızca şunun için hesaplamalar döndürülür: daha iyi olacaktır.

TransitOptions nesne değişmez değeri şunları içerir: alanlar:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

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

  • arrivalTime (isteğe bağlı), istenen etiketi belirtir Date nesnesi olarak varış zamanını tanımlar. Varış saati: belirtilirse kalkış saati yok sayılır.
  • departureTime (isteğe bağlı), istenen etiketi belirtir kalkış saati, Date nesnesi olarak. İlgili içeriği oluşturmak için kullanılan arrivalTime şu durumda departureTime yoksayılır: belirtilir. Hiçbir değer yoksa varsayılan olarak şimdi (yani geçerli zaman) olur departureTime veya arrivalTime.
  • modes (isteğe bağlı), aşağıdakilerden birini içeren bir dizidir: daha fazla TransitMode nesne değişmez değeri var. Bu alan yalnızca İstek bir API anahtarı içeriyorsa dahil edilir. Her TransitMode tercih edilen bir toplu taşıma modunu belirtir. Aşağıdaki değerlere izin verilir:
    • BUS, hesaplanmış rota otobüsle seyahati tercih etmelidir.
    • RAIL, kullanılarak hesaplanan rota tren, tramvay, hafif raylı sistem ve metro var.
    • SUBWAY, hesaplanmış rota metroyla seyahati tercih etmelidir.
    • TRAIN, trenle seyahati tercih etmesi gerekir.
    • TRAM, tramvay ve hafif raylı sistem ile seyahati tercih etmelidir.
  • routingPreference (isteğe bağlı) tercihleri belirtir . Bu seçeneği kullanarak, döndürülen seçeneklere yansıyabilir, tercih edebilirsiniz. Bu alan yalnızca istekte bir API anahtarı. Aşağıdaki değerlere izin verilir:
    • FEWER_TRANSFERS. hesaplanan rotanın sınırlı sayıda aktarım.
    • LESS_WALKING. , hesaplanan rotanın sınırlı miktarda yürümek.

Sürüş Seçenekleri

drivingOptions nesnesini kullanarak şunun için kalkış saatini belirtin: Beklenen trafik koşulları göz önüne alındığında hedefinize giden en iyi rotayı hesaplama. Şunları yapabilirsiniz: Ayrıca, trafikteki tahmini sürenin kötümser, iyimser veya Geçmiş trafik koşullarına ve canlı trafiğe dayalı olarak en iyi tahmin.

drivingOptions nesnesi şu alanları içerir:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

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

  • departureTime ( drivingOptions nesne değişmez değeri geçerli olacak şekilde) istenen kalkış saatini Date nesne olarak görüntüler. Değer şöyle olmalıdır: geçerli zamana veya gelecekteki bir zamana ayarlayabilirsiniz. Para birimi geçmiş. (API, tutarlı işlem sağlamak için tüm tarihleri UTC'ye dönüştürür. farklı saat dilimlerinde çalışır.) İsteğe departureTime öğesini dahil ederseniz API, o anki beklenen trafik koşullarını göz önünde bulundurarak en iyi rotayı döndürür ve trafikteki tahmini süreyi içerir (duration_in_traffic) kullanıcı olabilir. Bir kalkış saati belirtmezseniz (yani istek drivingOptions içermez), döndürülen rota trafik koşulları hesaba katılmadan genellikle iyi bir rotadır.
  • trafficModel (isteğe bağlı), kullanabileceğiniz bir tekniktir. Bu ayar, yanıttaki duration_in_traffic alanında döndürüldü Bu sütun, 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 En iyi seyahat tahmini duration_in_traffic olmalıdır hem geçmiş trafik koşulları hem de geçmiş trafik koşulları hakkında yardımcı olabilir. Canlı trafik ne kadar önemli hale gelirse departureTime şimdiye kadar...
    • pessimistic, döndürülen duration_in_traffic, gerçek seyahat süresinden daha uzun olmalıdır çoğu gün ancak zaman zaman trafiğin yoğun olduğu günler koşulları bu değeri aşabilir.
    • optimistic, döndürülen duration_in_traffic, gerçek değerden daha kısa olmalıdır çoğu gün seyahat süresi, ancak bazı günlerde trafik koşulları bu değerden daha hızlı olabilir.

Aşağıda arabayla rotalar için örnek DistanceMatrixRequest verilmiştir, (kalkış saati ve trafik modeli dahil):

{
  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ı, DistanceMatrixResponse nesne ve bir DistanceMatrixStatus nesne algılandı. Bunlar geri çağırmaya iletilir işlevini kullanın.

DistanceMatrixResponse nesnesi mesafe ve rotanın kendisi için geçerli olan her kalkış/hedef çifti için süre bilgisi hesaplanabilir.

{
  "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, şu konumları içeren bir dizidir: Mesafe Matrisi isteğinin origins alanına iletildi. Adresler, coğrafi kodlayıcı tarafından biçimlendirildikçe döndürülür.
  • destinationAddresses, konum bilgileri destinations alanına şu biçimde geçirilmiştir döndüren bir tanımlayıcıdır.
  • rows, DistanceMatrixResponseRow dizisidir her satırı bir kaynağa karşılık gelen şekilde gösterilir.
  • elements, rows öğesinin alt öğeleridir ve bunlara karşılık gelir satır başlangıç ve varış noktalarının ikisini birden eşleyeceksiniz. Şunları içerir: Her biri için durum, süre, mesafe ve ücret bilgileri (varsa) başlangıç/hedef çifti.
  • Her element aşağıdaki alanları içerir:
    • status: Bkz. Şu durumların listesi için Durum Kodları: olası durum kodları.
    • duration: Bu yere seyahat etmek için gereken süre rota, saniye cinsinden (value alanı) ve text. Metin değeri İstekte (veya metrikte yoksa metrikte) unitSystem belirtilmiş bir tercih belirtildi).
    • duration_in_traffic: İncelemenin tamamlanması için geçen süre bu rotayı mevcut trafik koşullarını göz önünde bulundurarak seyahat edin, saniye cinsinden (value alanı) ve text. Metin değeri İstekte (veya metrikte yoksa metrikte) unitSystem belirtilmiş bir tercih belirtildi). İlgili içeriği oluşturmak için kullanılan duration_in_traffic yalnızca trafik verilerinin bulunduğu durumlarda döndürülür. mode driving olarak ayarlandı ve departureTime, distanceMatrixOptions alanına girilmelidir.
    • distance: Bu rotanın, cinsinden ifade edilen toplam mesafesi metre (value) ve text olarak. Metin değeri unitSystem istek (veya herhangi bir tercih belirtilmemişse metrik cinsinden).
    • fare: Toplam ücreti (yani toplam ücreti) içerir bilet maliyetleri) girmeniz gerekir. Bu mülk yalnızca toplu taşımada iade edildi yalnızca ücret bilgilerinin mevcut olduğu toplu taşıma sağlayıcıları için geçerlidir kullanılabilir. Bu bilgiler arasında şunlar bulunur:
      • currency: Bir ISO 4217 para birimi kodu belirtir.
      • value: Belirtilen para biriminde toplam ücret tutarı bölümünü ziyaret edin.

Durum Kodları

Mesafe Matrisi yanıtında, yanıtın zaman çizelgesinde her öğenin durumunu gösterir.

Yanıt Durumu Kodları

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

  • OK — İstek geçerli. Bu durum, başlangıç noktaları arasında hiçbir rota bulunmasa bile hedefler. Bkz. Öğe Öğe düzeyindeki durum bilgileri için Durum Kodları.
  • INVALID_REQUEST - Sağlanan istek geçersiz. Bunun nedeni genellikle zorunlu alanların eksik olmasıdır. Bkz. desteklenen alanların listesini inceleyin.
  • MAX_ELEMENTS_EXCEEDED: Kalkış ve varış noktalarının çarpımı sorgu başına sınır uygulanır.
  • MAX_DIMENSIONS_EXCEEDED — İsteğinizde daha fazla yer vardı 25'ten fazla kaynak veya 25 hedef.
  • OVER_QUERY_LIMIT — Uygulamanız istekte bulundu izin verilen dönemde çok fazla öğe var. İstek, makul bir süre sonra yeniden denerseniz başarılı olur.
  • REQUEST_DENIED — Hizmet, Web sayfanıza göre Mesafe Matrisi hizmeti.
  • UNKNOWN_ERROR — Bir Mesafe Matrisi isteği başarısız oldu bir sunucu hatasından dolayı işlenmeleri gerekir. Şunları denerseniz istek başarılı olabilir: tekrar.

Öğe Durumu Kodları

Aşağıdaki durum kodları, DistanceMatrixElement nesne:

  • NOT_FOUND — Bunun kalkış ve/veya varış noktası eşlemenin coğrafi kodlaması yapılamadı.
  • OK — Yanıt geçerli bir sonuç içeriyor.
  • ZERO_RESULTS — Şu tarihler arasında rota bulunamadı: kalkış ve varış noktası.

Sonuçları Ayrıştırma

DistanceMatrixResponse nesnesi bir tane içeriyor İstekte iletilen her kaynak için row. Her satır söz konusu başlangıç noktasının her eşlemesi için bir element alanı içerir sağlanan hedeflerdir.

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