Layanan Distance Matrix

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Ringkasan

Layanan Distance Matrix dari Google menghitung jarak perjalanan dan waktu tempuh 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, terlebih dahulu pastikan 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 Dashboard, 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 ENABLE. Setelah proses selesai, Distance Matrix API akan muncul dalam daftar API di Dashboard.

Harga dan kebijakan

Harga

Pada 16 Juli 2018, paket harga baru, yaitu bayar sesuai penggunaan, diberlakukan untuk Maps, Rute, dan Tempat. Untuk mempelajari lebih lanjut harga baru dan batas penggunaan untuk pemakaian layanan Distance Matrix JavaScript, lihatPenggunaan dan Penagihan untuk Distance Matrix API.

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

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 harus 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 yang akan dieksekusi 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 (diperlukan) — Array yang berisi satu atau beberapa string alamat, objek google.maps.LatLng, atau objek Place untuk menghitung jarak dan waktu.
  • destinations (diperlukan) — 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 yang travelMode-nya adalah 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 di antara titik akan dihitung menggunakan rute non-tol, jika memungkinkan.

Mode Perjalanan

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

  • BICYCLING meminta rute sepeda melalui jalur sepeda & jalan yang disukai (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 dan trotoar (jika tersedia).

Opsi Transportasi Umum

Layanan Transit saat ini 'bersifat eksperimen'. Selama fase ini, kami akan mengimplementasikan batas kecepatan untuk mencegah penyalahgunaan API. Pada akhirnya kami akan membatasi total permintaan per beban peta berdasarkan penggunaan wajar atas 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. Perhitungan hanya akan dikembalikan untuk waktu yang akan datang.

Literal objek TransitOptions berisi kolom berikut:

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

Kolom-kolom ini dijelaskan di bawah:

  • arrivalTime (opsional) menentukan waktu kedatangan yang diinginkan sebagai objek Date. Jika waktu kedatangan telah ditetapkan, 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 preferensi moda transportasi umum. Nilai-nilai berikut ini diizinkan:
    • BUS menunjukkan bahwa rute yang sudah dihitung akan mengutamakan perjalanan dengan bus.
    • RAIL menunjukkan bahwa rute yang sudah dihitung akan mengutamakan perjalanan dengan kereta api, trem, LRT, dan kereta bawah tanah.
    • SUBWAY menunjukkan bahwa rute yang sudah dihitung akan mengutamakan perjalanan dengan kereta bawah tanah.
    • TRAIN menunjukkan bahwa rute yang sudah dihitung akan mengutamakan perjalanan dengan kereta api.
    • TRAM menunjukkan bahwa rute yang sudah dihitung harus mengutamakan perjalanan dengan trem dan LRT.
  • routingPreference (opsional) menentukan preferensi untuk rute transportasi umum. Dengan menggunakan opsi ini, Anda dapat membiaskan opsi yang dikembalikan, daripada menerima rute default terbaik yang dipilih oleh API. Kolom ini hanya dapat ditetapkan jika permintaan berisi kunci API. Nilai-nilai berikut ini diizinkan:
    • FEWER_TRANSFERS menunjukkan bahwa rute yang sudah dihitung akan mengutamakan jumlah transfer yang terbatas.
    • LESS_WALKING menunjukkan bahwa rute yang sudah 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 berdasarkan perkiraan kondisi lalu lintas. Anda juga dapat menentukan apakah menginginkan perkiraan waktu dalam lalu lintas bersifat pesimis, optimis, atau perkiraan terbaik berdasarkan kondisi lalu lintas historis dan lalu lintas langsung.

Objek drivingOptions berisi kolom-kolom berikut:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Kolom-kolom 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 ke waktu yang akan datang. Tidak boleh waktu yang sudah lewat. (API mengonversi semua tanggal ke UTC untuk memastikan penanganan yang konsisten di semua zona waktu.) Jika Anda menyertakan departureTime dalam permintaan, API akan menampilkan rute terbaik berdasarkan perkiraan kondisi lalu lintas pada saat itu, dan menyertakan prediksi waktu lalu lintas (duration_in_traffic) dalam respons. Jika Anda tidak menentukan waktu keberangkatan (yaitu, jika permintaan tidak menyertakan drivingOptions), rute yang dikembalikan adalah rute yang biasanya bagus tanpa memperhitungkan kondisi lalu lintas.

    Catatan: Jika waktu keberangkatan tidak ditentukan, pilihan rute dan durasi didasarkan pada kondisi jaringan jalan raya dan lalu lintas rata-rata yang tidak tergantung 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 didistribusikan. Hasilnya juga dapat bervariasi di antara rute yang hampir setara di semua waktu atau frekuensi.

  • trafficModel (opsional) menentukan asumsi yang akan digunakan saat menghitung waktu dalam lalu lintas. Setelan ini memengaruhi nilai yang dikembalikan di kolom duration_in_traffic dalam respons, yang berisi prediksi waktu dalam lalu lintas berdasarkan rata-rata historis. Default-nya adalah best_guess. Nilai-nilai berikut ini diizinkan:
    • bestguess (default) menunjukkan bahwa duration_in_traffic yang dikembalikan harus berupa perkiraan waktu tempuh terbaik berdasarkan informasi historis kondisi lalu lintas dan lalu lintas langsung. Lalu lintas langsung menjadi lebih penting jika departureTime semakin dekat ke waktu sekarang..
    • pessimistic menunjukkan bahwa duration_in_traffic yang dikembalikan akan lebih lama daripada waktu tempuh sesungguhnya di sebagian besar hari, meskipun hari-hari tertentu dengan kondisi lalu lintas yang sangat parah dapat melebihi nilai ini.
    • optimistic menunjukkan bahwa duration_in_traffic yang dikembalikan akan lebih singkat daripada waktu tempuh yang sebenarnya pada sebagian besar hari, meskipun hari-hari tertentu 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 mengembalikan objek DistanceMatrixResponse dan objek DistanceMatrixStatus. Pengembalian ini akan diteruskan ke fungsi callback yang Anda tetapkan 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

Kolom yang didukung dalam respons dijelaskan di bawah ini.

  • originAddresses adalah array yang berisi lokasi yang diteruskan di kolom origins dalam permintaan Distance Matrix. Alamat dikembalikan sebagaimana diformat oleh geocoder.
  • destinationAddresses adalah array yang berisi lokasi yang diteruskan di kolom destinations, dalam format yang dikembalikan 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 dengan masing-masing tujuan untuk baris tersebut. Isinya berupa status, durasi, jarak, dan informasi tarif (jika tersedia) untuk setiap pasang asal/tujuan.
  • Setiap element berisi kolom berikut:
    • status: Buka Kode Status untuk melihat daftar kemungkinan kode status.
    • duration: Durasi waktu yang diperlukan untuk menempuh 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: Durasi 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). Tab duration_in_traffic hanya dikembalikan kepada pelanggan Premium Plan Google Maps Platform tempat data lalu lintas 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 dikembalikan untuk permintaan transportasi umum dan hanya untuk penyedia transportasi umum yang memiliki informasi tarif. Informasi ini menyertakan:
      • currency: Kode mata uang ISO 4217 yang menunjukkan mata uang yang digunakan dalam menyatakan jumlahnya.
      • value: Jumlah total tarif, dalam mata uang yang ditetapkan 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 dikembalikan, bahkan jika tidak ditemukan rute 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 kolom yang wajib diisi 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 mungkin berhasil jika Anda mencoba lagi setelah menunggu beberapa saat.
  • REQUEST_DENIED — Layanan menolak penggunaan layanan Distance Matrix oleh halaman web Anda.
  • UNKNOWN_ERROR — Permintaan Distance Matrix tidak dapat diproses karena server error. 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 dilakukan geocoding.
  • OK — Respons berisi hasil yang valid.
  • ZERO_RESULTS — Tidak ada rute yang dapat ditemukan antara tempat asal dan tujuan.

Mengurai Hasil

Objek DistanceMatrixResponse berisi satu row untuk setiap tempat asal yang diteruskan dalam permintaan. Setiap baris berisi kolom element untuk setiap pasangan tempat 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];
      }
    }
  }
}