Layanan Distance Matrix

Ringkasan

Layanan Distance Matrix dari Google menghitung jarak perjalanan dan durasi perjalanan antara beberapa tempat asal dan tujuan menggunakan mode perjalanan tertentu.

Layanan ini tidak mengembalikan informasi rute detail. Informasi rute, termasuk polyline dan rute tekstual, dapat diperoleh dengan meneruskan satu tempat asal dan tujuan yang diinginkan ke Directions Service.

Memulai

Sebelum menggunakan layanan Distance Matrix di Maps JavaScript API, pastikan terlebih dahulu bahwa Distance Matrix API diaktifkan di Google Cloud Console, dalam project yang sama dengan yang Anda siapkan untuk Maps JavaScript API.

Untuk menampilkan daftar API yang telah diaktifkan:

  1. Buka Google Cloud Console.
  2. Klik tombol Select a project, lalu pilih project yang sama dengan yang Anda siapkan untuk Maps JavaScript API dan klik Open.
  3. Dari daftar API di Dasbor, cari Distance Matrix API.
  4. Jika sudah melihat API di dalam daftar, artinya Anda sudah siap. Jika API tidak tercantum, aktifkan:
    1. Di bagian atas halaman, pilih ENABLE API untuk menampilkan tab Library. Atau, dari menu samping kiri, pilih Library.
    2. Telusuri Distance Matrix API, lalu pilih dari daftar hasil.
    3. Pilih AKTIFKAN. Setelah proses selesai, Distance Matrix API akan muncul dalam daftar API di Dasbor.

Harga dan kebijakan

Harga

Mulai 16 Juli 2018, paket harga baru, yaitu bayar sesuai penggunaan, berlaku untuk Maps, Rute, dan Tempat. Untuk mempelajari lebih lanjut batas harga dan penggunaan baru untuk penggunaan layanan Distance Matrix JavaScript, lihat Penggunaan dan Penagihan untuk Distance Matrix API.

Catatan: Setiap kueri yang dikirim ke layanan Distance Matrix dibatasi oleh jumlah elemen yang diizinkan, dengan jumlah asal yang dikalikan dengan jumlah tujuan yang menentukan jumlah elemen.

Batas kapasitas

Perhatikan hal-hal berikut tentang batas kapasitas pada permintaan tambahan:

Batas kapasitas diterapkan per sesi pengguna, berapa pun banyaknya pengguna yang berbagi project yang sama. Saat pertama kali memuat API, Anda akan diberikan kuota awal elemen. Setelah Anda menggunakan kuota ini, API akan menerapkan batas kapasitas pada permintaan tambahan per detik. Jika terlalu banyak permintaan dibuat dalam jangka waktu tertentu, API akan menampilkan kode respons OVER_QUERY_LIMIT.

Batas kecepatan per sesi mencegah penggunaan layanan sisi klien untuk permintaan batch. Untuk permintaan batch, gunakan layanan web Distance Matrix API.

Kebijakan

Penggunaan layanan Distance Matrix harus sesuai dengan kebijakan yang dijelaskan untuk Distance Matrix API.

Permintaan Distance Matrix

Mengakses layanan Distance Matrix bersifat asinkron, karena Google Maps API perlu melakukan panggilan ke server eksternal. Oleh karena itu, Anda harus meneruskan metode callback untuk dieksekusi setelah permintaan selesai, untuk memproses hasilnya.

Anda mengakses layanan Distance Matrix dalam kode Anda melalui objek konstruktor google.maps.DistanceMatrixService. Metode DistanceMatrixService.getDistanceMatrix() memulai permintaan ke layanan Distance Matrix, yang meneruskan literal objek DistanceMatrixRequest yang berisi asal, tujuan, dan mode perjalanan, serta metode callback untuk mengeksekusi setelah menerima respons.

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.
}

Lihat contoh

DistanceMatrixRequest berisi kolom berikut:

  • origins (wajib) — Array yang berisi satu atau beberapa string alamat, objek google.maps.LatLng, atau objek Place untuk menghitung jarak dan waktu.
  • destinations (wajib) — Array yang berisi satu atau beberapa string alamat, objek google.maps.LatLng, atau objek Place untuk menghitung jarak dan waktu.
  • travelMode (opsional) — Mode transportasi yang akan digunakan saat menghitung rute. Lihat bagian mode perjalanan.
  • transitOptions (opsional) — Opsi yang hanya berlaku untuk permintaan yang travelMode-nya adalah TRANSIT. Nilai yang valid dijelaskan di bagian tentang opsi transportasi umum.
  • drivingOptions (opsional) menentukan nilai yang hanya berlaku untuk permintaan dengan travelMode DRIVING. Nilai yang valid dijelaskan di bagian Opsi Mengemudi.
  • unitSystem (opsional) — Sistem satuan yang akan digunakan saat menampilkan jarak. Nilai yang diterima adalah:
    • google.maps.UnitSystem.METRIC (default)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (opsional) — Jika true, rute antara tempat asal dan tujuan akan dihitung untuk menghindari jalan raya jika memungkinkan.
  • avoidTolls (opsional) — Jika true, rute antar-titik akan dihitung menggunakan rute non-tol, jika memungkinkan.

Mode Perjalanan

Saat menghitung waktu dan jarak, Anda dapat menentukan moda transportasi yang akan digunakan. Mode perjalanan berikut saat ini didukung:

  • BICYCLING meminta rute sepeda melalui jalur sepeda & jalan pilihan (saat ini hanya tersedia di AS dan beberapa kota di Kanada).
  • DRIVING (default) menunjukkan rute mobil standar menggunakan jaringan jalan.
  • TRANSIT meminta rute melalui rute transportasi umum. Opsi ini hanya dapat ditetapkan jika permintaan menyertakan kunci API. Lihat bagian opsi transportasi umum untuk opsi yang tersedia dalam jenis permintaan ini.
  • WALKING meminta rute jalan kaki melalui jalur pejalan kaki & trotoar (jika tersedia).

Opsi Angkutan Umum

Layanan Transportasi Umum saat ini 'eksperimental'. Selama fase ini, kami akan menerapkan batas kapasitas untuk mencegah penyalahgunaan API. Kami akan menerapkan pembatasan pada total kueri per beban peta berdasarkan penggunaan wajar API.

Opsi yang tersedia untuk permintaan matriks jarak bervariasi antar mode perjalanan. Dalam permintaan transportasi umum, opsi avoidHighways dan avoidTolls diabaikan. Anda dapat menentukan opsi pemilihan rute khusus transportasi umum melalui literal objek TransitOptions.

Permintaan angkutan umum sesuai-waktu. Penghitungan hanya akan ditampilkan untuk waktu yang akan datang.

Literal objek TransitOptions berisi kolom berikut:

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

Bidang-bidang ini dijelaskan di bawah:

  • arrivalTime (opsional) menentukan waktu kedatangan yang diinginkan sebagai objek Date. Jika waktu kedatangan ditentukan, waktu keberangkatan akan diabaikan.
  • departureTime (opsional) menentukan waktu keberangkatan yang diinginkan sebagai objek Date. departureTime akan diabaikan jika arrivalTime ditentukan. Setelan defaultnya adalah sekarang (yaitu, waktu saat ini) jika tidak ada nilai yang ditentukan untuk departureTime atau arrivalTime.
  • modes (opsional) adalah array yang berisi satu atau beberapa literal objek TransitMode. Kolom ini hanya dapat disertakan jika permintaan menyertakan kunci API. Setiap TransitMode menentukan moda transportasi umum. Nilai berikut diizinkan:
    • BUS menunjukkan bahwa rute yang dihitung akan mengutamakan perjalanan dengan bus.
    • RAIL menunjukkan bahwa rute yang dihitung harus mengutamakan perjalanan dengan kereta api, trem, kereta ringan, dan kereta bawah tanah.
    • SUBWAY menunjukkan bahwa rute yang dihitung harus mengutamakan perjalanan dengan kereta bawah tanah.
    • TRAIN menunjukkan bahwa rute yang dihitung harus mengutamakan perjalanan dengan kereta api.
    • TRAM menunjukkan bahwa rute yang dihitung harus mengutamakan perjalanan dengan trem dan kereta ringan.
  • routingPreference (opsional) menentukan preferensi untuk rute transportasi umum. Dengan menggunakan opsi ini, Anda dapat mencondongkan opsi yang ditampilkan, bukan menerima rute default terbaik yang dipilih oleh API. Kolom ini hanya dapat ditentukan jika permintaan menyertakan kunci API. Nilai berikut diizinkan:
    • FEWER_TRANSFERS menunjukkan bahwa rute yang dihitung harus mengutamakan jumlah transfer yang terbatas.
    • LESS_WALKING menunjukkan bahwa rute yang dihitung akan mengutamakan jumlah berjalan kaki dalam jumlah terbatas.

Opsi Mengemudi

Gunakan objek drivingOptions untuk menentukan waktu keberangkatan untuk menghitung rute terbaik ke tujuan Anda dengan mempertimbangkan kondisi lalu lintas yang diharapkan. Anda juga dapat menentukan apakah Anda ingin perkiraan waktu dalam traffic bersifat pesimis, optimis, atau perkiraan terbaik berdasarkan kondisi traffic historis dan traffic langsung.

Objek drivingOptions berisi kolom-kolom berikut:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Bidang-bidang ini dijelaskan di bawah:

  • departureTime (diperlukan agar literal objek drivingOptions valid) menentukan waktu keberangkatan yang diinginkan sebagai objek Date. Nilainya harus ditetapkan ke waktu saat ini atau waktu mendatang. Tidak boleh waktu yang sudah lewat. (API mengonversi semua tanggal ke UTC untuk memastikan penanganan yang konsisten di seluruh zona waktu.) Jika Anda menyertakan departureTime dalam permintaan, API akan menampilkan rute terbaik berdasarkan kondisi traffic yang diharapkan pada saat itu, dan menyertakan prediksi waktu dalam traffic (duration_in_traffic) dalam respons. Jika Anda tidak menentukan waktu keberangkatan (yaitu, jika permintaan tidak menyertakan drivingOptions), rute yang ditampilkan adalah rute yang biasanya baik tanpa memperhitungkan kondisi lalu lintas.

    Catatan: Jika waktu keberangkatan tidak ditentukan, pilihan rute dan durasi didasarkan pada jaringan jalan raya dan kondisi lalu lintas rata-rata yang tidak bergantung pada waktu. Hasil untuk permintaan tertentu dapat berubah dari waktu ke waktu karena perubahan pada jaringan jalan, kondisi lalu lintas rata-rata yang diperbarui, dan sifat layanan yang terdistribusi. Hasilnya juga dapat bervariasi di antara rute yang hampir setara pada waktu atau frekuensi tertentu.

  • trafficModel (opsional) menentukan asumsi yang akan digunakan saat menghitung waktu dalam traffic. Setelan ini memengaruhi nilai yang ditampilkan di kolom duration_in_traffic dalam respons, yang berisi prediksi waktu dalam traffic berdasarkan rata-rata historis. Nilai defaultnya adalah best_guess. Nilai berikut diizinkan:
    • bestguess (default) menunjukkan bahwa duration_in_traffic yang ditampilkan harus berupa perkiraan waktu perjalanan terbaik berdasarkan informasi historis kondisi lalu lintas dan lalu lintas langsung. Traffic langsung menjadi lebih penting jika departureTime semakin dekat ke waktu sekarang.
    • pessimistic menunjukkan bahwa duration_in_traffic yang ditampilkan harus lebih lama dari waktu perjalanan aktual pada sebagian besar hari, meskipun terkadang hari dengan kondisi lalu lintas yang sangat buruk dapat melebihi nilai ini.
    • optimistic menunjukkan bahwa duration_in_traffic yang ditampilkan harus lebih singkat dari waktu perjalanan yang sebenarnya pada sebagian besar hari, meskipun terkadang hari dengan kondisi lalu lintas yang sangat baik dapat lebih cepat dari nilai ini.

Berikut adalah contoh DistanceMatrixRequest untuk rute mengemudi, termasuk waktu keberangkatan dan model lalu lintas:

{
  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'
  }
}

Respons Distance Matrix

Panggilan yang berhasil ke layanan Distance Matrix akan menampilkan objek DistanceMatrixResponse dan objek DistanceMatrixStatus. Ini akan diteruskan ke fungsi callback yang Anda tentukan dalam permintaan.

Objek DistanceMatrixResponse berisi informasi jarak dan durasi untuk setiap pasangan asal/tujuan yang rutenya dapat dihitung.

{
  "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"
      }
    } ]
  } ]
}

Hasil Distance Matrix

Bidang yang didukung dalam respons dijelaskan di bawah ini.

  • originAddresses adalah array yang berisi lokasi yang diteruskan di kolom origins permintaan Distance Matrix. Alamat dikembalikan sebagaimana diformat oleh geocoder.
  • destinationAddresses adalah array yang berisi lokasi yang diteruskan di kolom destinations, dalam format yang ditampilkan oleh geocoder.
  • rows adalah array objek DistanceMatrixResponseRow, dengan setiap baris yang sesuai dengan tempat asal.
  • elements adalah turunan dari rows, dan sesuai dengan pasangan asal baris dengan setiap tujuan. Isinya berisi informasi status, durasi, jarak, dan tarif (jika tersedia) untuk setiap pasangan asal/tujuan.
  • Setiap element berisi kolom berikut:
    • status: Buka Kode Status untuk melihat daftar kemungkinan kode status.
    • duration: Waktu yang diperlukan untuk melewati rute ini, yang dinyatakan dalam detik (kolom value) dan sebagai text. Nilai tekstual diformat sesuai dengan unitSystem yang ditentukan dalam permintaan (atau dalam metrik, jika tidak ada preferensi yang diberikan).
    • duration_in_traffic: Waktu yang diperlukan untuk menempuh rute ini dengan mempertimbangkan kondisi lalu lintas saat ini, yang dinyatakan dalam detik (kolom value) dan sebagai text. Nilai tekstual diformat sesuai dengan unitSystem yang ditentukan dalam permintaan (atau dalam metrik, jika tidak ada preferensi yang diberikan). duration_in_traffic hanya ditampilkan kepada pelanggan Premium Plan Google Maps Platform tempat data traffic tersedia, mode ditetapkan ke driving, dan departureTime disertakan sebagai bagian dari kolom distanceMatrixOptions dalam permintaan.
    • distance: Jarak total rute ini, yang dinyatakan dalam meter (value) dan sebagai text. Nilai tekstual diformat sesuai dengan unitSystem yang ditentukan dalam permintaan (atau dalam metrik, jika tidak ada preferensi yang diberikan).
    • fare: Berisi total tarif (yaitu, total biaya tiket) pada rute ini. Properti ini hanya ditampilkan untuk permintaan transportasi umum dan hanya untuk penyedia transportasi umum yang menyediakan informasi tarif. Informasi ini mencakup:
      • currency: Kode mata uang ISO 4217 yang menunjukkan mata uang yang digunakan untuk menyatakan jumlah.
      • value: Jumlah total tarif, dalam mata uang yang ditentukan di atas.

Kode Status

Respons Distance Matrix berisi kode status untuk respons secara keseluruhan, serta status untuk setiap elemen.

Respons Kode Status

Kode status yang berlaku untuk DistanceMatrixResponse diteruskan dalam objek DistanceMatrixStatus dan mencakup:

  • OK — Permintaan valid. Status ini dapat ditampilkan meskipun tidak ada rute yang ditemukan antara tempat asal dan tujuan. Lihat Kode Status Elemen untuk informasi status tingkat elemen.
  • INVALID_REQUEST — Permintaan yang diberikan tidak valid. Hal ini sering kali disebabkan oleh bidang yang diperlukan tidak ada. Lihat daftar kolom yang didukung di atas.
  • MAX_ELEMENTS_EXCEEDED — Hasil dari tempat asal dan tujuan melampaui batas per kueri.
  • MAX_DIMENSIONS_EXCEEDED — Permintaan Anda berisi lebih dari 25 asal atau lebih dari 25 tujuan.
  • OVER_QUERY_LIMIT — Aplikasi Anda meminta terlalu banyak elemen dalam jangka waktu yang diizinkan. Permintaan akan berhasil jika Anda mencoba lagi setelah jangka waktu yang wajar.
  • REQUEST_DENIED — Layanan menolak penggunaan layanan Distance Matrix oleh halaman web Anda.
  • UNKNOWN_ERROR — Permintaan Distance Matrix tidak dapat diproses karena error server. Permintaan mungkin berhasil jika Anda mencoba lagi.

Kode Status Elemen

Kode status berikut berlaku untuk objek DistanceMatrixElement tertentu:

  • NOT_FOUND — Tempat asal dan/atau tujuan dari pasangan ini tidak dapat di-geocoding.
  • OK — Respons berisi hasil yang valid.
  • ZERO_RESULTS — Tidak ada rute yang dapat ditemukan antara asal dan tujuan.

Mem-parse Hasil

Objek DistanceMatrixResponse berisi satu row untuk setiap asal yang diteruskan dalam permintaan. Setiap baris berisi kolom element untuk setiap pasangan asal tersebut dengan tujuan yang diberikan.

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