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:
- Google Cloud Console'a gidin.
- 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.
- Dashboard'daki (Kontrol Paneli) API'ler listesinde Position Matrix API'yi bulun.
- Listede API'yi görüyorsanız hazırsınız demektir. API listede yoksa API'yi etkinleştirin:
- 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.
- Mesafe Matrisi API'sini arayın ve sonuç listesinden bunu seçin.
- 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. }
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ızcatravelMode
değerininTRANSIT
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ızcatravelMode
değerininDRIVING
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ış saatiniDate
nesnesi olarak belirtir.arrivalTime
belirtilirsedepartureTime
yoksayılır.departureTime
veyaarrivalTime
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 fazlaTransitMode
nesne değişmez değeri içeren dizidir. Bu alan yalnızca istekte bir API anahtarı varsa eklenebilir. HerTransitMode
, 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ğedepartureTime
öğ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 istekdrivingOptions
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ıttakiduration_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 olarakbest_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ülenduration_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ülenduration_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ülenduration_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ğininorigins
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çimdedestinations
alanında geçirilen konumları içeren bir dizidir.rows
, her satırı bir kaynağa karşılık gelenDistanceMatrixResponseRow
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ı) vetext
olarak ifade edilir. Metin değeri, istekte belirtilenunitSystem
öğ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ı) vetext
olarak ifade edilir. Metin değeri, istekte belirtilenunitSystem
öğ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 vedepartureTime
, istektekidistanceMatrixOptions
alanının bir parçası olarak eklenir.distance
: Bu rotanın metre (value
) vetext
cinsinden toplam mesafesi. Metin değeri, istekte belirtilenunitSystem
öğ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]; } } } }