Genel bakış
Google'ın Mesafe Matrisi hizmeti, belirli bir ulaşım şeklini kullanarak birden çok kalkış ve varış noktası arasındaki seyahat mesafesini ve yolculuk süresini hesaplar.
Bu hizmet ayrıntılı rota bilgilerini döndürmez. Çoklu çizgiler ve metin şeklindeki yol tarifleri dahil olmak üzere rota bilgileri, istenen tek başlangıç noktası ve hedefin Yol Tarifi Hizmeti'ne geçirilmesiyle elde edilebilir.
Kullanmaya başlama
Maps JavaScript API'de Mesafe Matrisi hizmetini kullanmadan önce, ilk olarak Maps JavaScript API için oluşturduğunuz projede, Google Cloud Console'da Mesafe Matrisi API'sinin etkinleştirildiğinden emin olun.
Etkin API'ler listenizi 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.
- Kontrol Paneli'ndeki API listesinde Mesafe Matrisi API'sini arayın.
- Listede API'yi görüyorsanız her şey hazır demektir. API listede yoksa etkinleştirin:
- Sayfanın üst kısmında Kitaplık sekmesini görüntülemek için API'yi ETKİNLEŞTİR'i seçin. Alternatif olarak, sol taraftaki menüden Kitaplık'ı seçin.
- Mesafe Matrisi API'sini arayın ve sonuçlar listesinden seçin.
- 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 tarihinden itibaren Haritalar, Rotalar ve Yerler için yeni bir kullandıkça öde fiyatlandırma planı yürürlüğe girdi. JavaScript Mesafe Matrisi hizmeti kullanımınızla ilgili 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üne bakın.
Not: Mesafe Matrisi hizmetine gönderilen her sorgu, izin verilen öğe sayısıyla sınırlıdır. Burada, öğe sayısı kaynak sayısı ile 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 Haritalar API'sinin harici bir sunucuya çağrı yapması gerektiğinden, Mesafe Matrisi hizmetine erişim eşzamansız olarak gerçekleşir. Bu nedenle, isteğin tamamlanmasının ardından sonuçları işlemek üzere callback yöntemi iletmeniz gerekir.
Mesafe Matrisi hizmetine kodunuzdan google.maps.DistanceMatrixService
oluşturucu nesnesi aracılığıyla erişirsiniz.
DistanceMatrixService.getDistanceMatrix()
yöntemi, Mesafe Matrisi hizmetine bir istek göndererek başlangıç noktaları, varış noktaları ve seyahat modunu içeren DistanceMatrixRequest
nesne değişmez değerini ve 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
(zorunlu) — Mesafe ve zaman hesaplanacak bir veya daha fazla adres dizesi,google.maps.LatLng
nesnesi veya Place nesnesi içeren dizi.destinations
(zorunlu) — Mesafe ve zaman hesaplanacak bir veya daha fazla adres dizesi,google.maps.LatLng
nesnesi veya Place nesnesi içeren dizi.travelMode
(isteğe bağlı) — Yol tarifi hesaplanırken kullanılacak ulaşım modu. Ulaşım şekilleri ile ilgili bölüme bakın.transitOptions
(isteğe bağlı) - YalnızcatravelMode
öğesininTRANSIT
olduğu istekler için geçerli olan seçeneklerdir. 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 bölümünde açıklanmıştır.unitSystem
(isteğe bağlı) — Mesafeyi görüntülerken 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, 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 tarifi mümkün olduğunda ücretli olmayan rotalar kullanılarak hesaplanır.
Seyahat Modları
Süre ve mesafeleri hesaplarken kullanılacak ulaşım şeklini belirtebilirsiniz. Şu anda aşağıdaki ulaşım şekilleri desteklenmektedir:
BICYCLING
, bisiklet yolları ve tercih edilen sokaklar üzerinden bisiklet için yol tarifi ister (ş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 isteğin bir API anahtarı içermesi durumunda belirtilebilir. Bu istek türündeki seçenekler için toplu taşıma seçenekleri ile ilgili bölüme bakın.WALKING
, yaya yolları ve kaldırımlar üzerinden (varsa) yaya yol tarifi isteğinde bulunur.
Toplu Taşıma Seçenekleri
Toplu Taşıma Hizmeti şu anda "deneme aşamasındadır". Bu aşamada, API'lerin kötüye kullanımını önlemek için hız sınırları uygulayacağız. Bir süre sonra, API'nin adil kullanımına bağlı olarak harita yükü başına toplam sorgu sayısına bir sınırlama getireceğiz.
Mesafe matrisi isteği için kullanılabilen seçenekler, ulaşım şekillerine göre değişiklik gösterir.
Aktarım isteklerinde avoidHighways
ve avoidTolls
seçenekleri yoksayılır. TransitOptions
nesne değişmez değerini kullanarak geçişe özel yönlendirme seçeneklerini belirtebilirsiniz.
Toplu taşıma istekleri zamana duyarlıdır. Hesaplamalar yalnızca gelecekteki zamanlar 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 istenen varış zamanını belirtir. Varış saati belirtilirse kalkış saati yoksayılır.departureTime
(isteğe bağlı),Date
nesnesi olarak istenen kalkış saatini belirtir.arrivalTime
belirtilirsedepartureTime
yoksayılır.departureTime
veyaarrivalTime
için herhangi bir değer belirtilmezse varsayılan olarak şimdi (yani geçerli saat) kullanılır.modes
(isteğe bağlı), bir veya daha fazlaTransitMode
nesne değişmez değerini içeren bir dizidir. Bu alan, yalnızca isteğin bir API anahtarı içermesi durumunda dahil edilebilir. HerTransitMode
, tercih edilen 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ı tren ve metroyla seyahat etmeyi tercih etmesi gerektiğini belirtir.SUBWAY
, hesaplanan rotanın metroyla seyahati tercih etmesi gerektiğini belirtir.TRAIN
, hesaplanan rotanın trenle seyahat etmeyi tercih etmesi gerektiğini belirtir.TRAM
, hesaplanan rotanın tramvay ve hafif raylı sistem ile seyahat etmeyi tercih etmesi gerektiğini belirtir.
routingPreference
(isteğe bağlı), toplu taşıma rotalarıyla ilgili 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ç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 belirtir.
Sürüş Seçenekleri
Beklenen trafik koşullarına göre hedefinize giden en iyi rotayı hesaplamak için 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 tahmin mi olmasını istediğ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 istenen kalkış saatini belirtir. Değer, geçerli zamana veya gelecekteki bir zamana ayarlanmalıdır. Geçmiş bir tarih olamaz. (API, farklı saat dilimlerinde tutarlı bir şekilde işlenmesi için tüm tarihleri UTC'ye dönüştürür.)departureTime
öğesini isteğe dahil ederseniz API, o anki beklenen trafik koşullarına göre en iyi rotayı döndürür ve yanıta trafikteki tahmini süreyi (duration_in_traffic
) dahil eder. Kalkış saati belirtmezseniz (yani istektedrivingOptions
yoksa) döndürülen rota, trafik koşullarını dikkate almadan genellikle iyi bir 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 ve 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 bilinenler göz önünde bulundurulduğunda, döndürülenduration_in_traffic
değerinin en iyi seyahat süresi tahmini olması gerektiğini belirtir.departureTime
şu ana ne kadar yakınsa canlı trafik daha önemli hale gelir.pessimistic
, döndürülenduration_in_traffic
değerinin çoğu günde gerçek seyahat süresinden daha uzun olması gerektiğini belirtir, ancak bazen kötü trafik koşullarına sahip günler bu değeri aşabilir.optimistic
, döndürülenduration_in_traffic
değerinin, çoğu günde gerçek seyahat süresinden daha kısa olması gerektiğini belirtir. Bununla birlikte, bazen trafik koşullarının çok iyi olduğu günler bu değerden daha hızlı olabilir.
Aşağıda, kalkış saati ve trafik modeli dahil, 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
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ı
Yanıtta desteklenen alanlar aşağıda açıklanmıştır.
originAddresses
, Mesafe Matrisi isteğininorigins
alanında iletilen konumları içeren bir dizidir. Adresler, coğrafi kodlayıcı tarafından biçimlendirildikleri gibi döndürülür.destinationAddresses
, coğrafi kodlayıcı tarafından döndürülen biçimde,destinations
alanında iletilen konumları içeren bir dizidir.rows
, her satır bir kaynağa karşılık gelenDistanceMatrixResponseRow
nesne dizisidir.elements
,rows
öğesinin alt öğeleridir ve her bir hedefle satırın başlangıç noktası çiftine karşılık gelir. Her bir kalkış/varış ç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ı'na bakın.duration
: Bu rota üzerinde seyahat etmek için geçen süre. Saniye cinsinden (value
alanı) vetext
cinsinden belirtilir. Metin değeri, istekte (veya herhangi bir tercih sağlanmamışsa metrikte) belirtilenunitSystem
öğesine göre biçimlendirilir.duration_in_traffic
: Mevcut trafik koşulları dikkate alınarak bu rota üzerinde seyahat etmek için geçen süre. Saniye cinsinden (value
alanı) vetext
cinsinden belirtilir. Metin değeri, istekte (veya herhangi bir tercih sağlanmamışsa metrikte) belirtilenunitSystem
öğesine göre biçimlendirilir.duration_in_traffic
, yalnızca trafik verilerinin mevcut olduğu,mode
öğesinindriving
olarak ayarlandığı ve istektekidistanceMatrixOptions
alanının bir parçası olarakdepartureTime
öğesinin eklendiği Google Haritalar Platformu Premium Plan müşterilerine döndürülür.distance
: Bu rotanın metre (value
) cinsinden vetext
olarak ifade edilen toplam mesafesi. Metin değeri, istekte (veya herhangi bir tercih sağlanmamışsa metrikte) belirtilenunitSystem
öğesine göre biçimlendirilir.fare
: 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. 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ı, bir bütün olarak yanıt için bir durum kodu ve her bir öğe için bir durum içerir.
Yanıt Durumu Kodları
DistanceMatrixResponse
için geçerli olan durum kodları DistanceMatrixStatus
nesnesinde iletilir ve şunları içerir:
OK
: İstek geçerlidir. Başlangıç noktaları ve hedefler arasında rota bulunmasa bile bu durum döndürülebilir. Öğe düzeyindeki durum bilgileri için Öğe Durumu Kodları konusuna 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
: Kaynak ve hedeflerden oluşan ü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 dönem 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
— Sunucu hatası nedeniyle Mesafe Matrisi 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 coğrafi kodla belirlenemedi.OK
: Yanıt geçerli bir sonuç içeriyor.ZERO_RESULTS
: Kalkış ve varış noktaları arasında rota bulunamadı.
Sonuçları Ayrıştırma
DistanceMatrixResponse
nesnesi, istekte geçirilen her kaynak için bir row
içerir. Her satırda, söz konusu başlangıç noktasının sağlanan hedeflerle her bir çifti 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]; } } } }