Layanan Distance Matrix

Catatan: Library sisi server

Halaman ini menjelaskan layanan sisi klien yang tersedia dengan Maps JavaScript API. Jika ingin menggunakan layanan web Google Maps di server Anda, lihat Klien Node.js untuk Layanan Google Maps. Halaman di link tersebut juga menyertakan Klien Java, Klien Python, dan Klien Go untuk Layanan Google Maps.

Ringkasan

Lihat juga Referensi Maps JavaScript API: Distance Matrix

Layanan Distance Matrix dari Google menghitung jarak perjalanan dan waktu tempuh antara beberapa tempat asal dan tujuan menggunakan moda transportasi tertentu.

Layanan ini tidak menampilkan detail informasi rute. 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 lebih dahulu bahwa Distance Matrix API telah diaktifkan di Konsol Google Cloud, dalam project yang sama dengan yang Anda siapkan untuk Maps JavaScript API.

Untuk menampilkan daftar API yang telah diaktifkan:

1. Baca 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 tersebut 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, lihat Penggunaan dan Penagihan untuk Distance Matrix API.

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

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 moda transportasi, 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 (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 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:
  • 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 antartitik akan dihitung menggunakan rute non-tol, jika memungkinkan.

Catatan: Kolom durationInTraffic kini tidak digunakan lagi. Sebelumnya, cara ini direkomendasikan kepada pelanggan Premium Plan Google Maps Platform untuk menentukan apakah hasilnya harus menyertakan durasi dengan memperhitungkan kondisi lalu lintas saat ini. Sekarang Anda harus menggunakan kolom drivingOptions.

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 Transportasi Umum saat ini 'bersifat eksperimental'. Selama fase ini, kami akan mengimplementasikan pembatasan kapasitas 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 transportasi umum bersifat 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 dihitung akan mengutamakan perjalanan dengan bus.
  • RAIL menunjukkan bahwa rute yang dihitung akan mengutamakan perjalanan dengan kereta api, trem, LRT, dan kereta bawah tanah.
  • SUBWAY menunjukkan bahwa rute yang dihitung akan mengutamakan perjalanan dengan kereta bawah tanah.
  • TRAIN menunjukkan bahwa rute yang dihitung akan mengutamakan perjalanan dengan kereta api.
  • TRAM menunjukkan bahwa rute yang dihitung akan mengutamakan perjalanan dengan trem dan LRT.
• routingPreference (opsional) menentukan preferensi untuk rute transportasi umum. Dengan menggunakan opsi ini, Anda dapat memprioritaskan opsi yang ditampilkan, 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 dihitung akan mengutamakan jumlah transfer tertentu.
  • LESS_WALKING menunjukkan bahwa rute yang dihitung akan mengutamakan rute yang tidak memerlukan berjalan kaki terlalu jauh.

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 pesimistis, optimistis, atau perkiraan terbaik berdasarkan kondisi lalu lintas historis dan lalu lintas live.

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 lampau. (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 jaringan jalan dan kondisi lalu lintas rata-rata tanpa memperhitungkan waktu tertentu. Hasil untuk permintaan tertentu dapat berubah dari waktu ke waktu karena perubahan pada jaringan jalan, kondisi lalu lintas rata-rata yang diperbarui, dan sifat distribusi layanan. 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 ditampilkan di kolom duration_in_traffic dalam respons, yang berisi prediksi waktu lalu lintas berdasarkan rata-rata historis. Default-nya adalah best_guess. Nilai-nilai berikut ini diizinkan:
  • bestguess (default) menunjukkan bahwa duration_in_traffic yang ditampilkan harus berupa perkiraan waktu tempuh terbaik berdasarkan informasi historis kondisi lalu lintas dan lalu lintas live. Lalu lintas live menjadi lebih penting jika departureTime lebih dekat ke waktu sekarang.
  • pessimistic menunjukkan bahwa duration_in_traffic yang ditampilkan biasanya akan lebih lama daripada waktu tempuh sesungguhnya, meskipun hari-hari tertentu dengan kondisi lalu lintas yang sangat padat dapat lebih lama dari nilai ini.
  • optimistic menunjukkan bahwa duration_in_traffic yang ditampilkan biasanya akan lebih singkat daripada waktu tempuh yang sesungguhnya, meskipun hari-hari tertentu dengan kondisi lalu lintas yang sangat lancar 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. Objek 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 ditampilkan oleh geocoder.
• rows adalah array object DistanceMatrixResponseRow, yang setiap barisnya berkaitan dengan suatu tempat asal.
• elements adalah turunan dari rows, dan berkaitan 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 memperhitungkan 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 ditampilkan kepada pelanggan Premium Plan Google Maps Platform jika 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.

Kode Status Respons

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