Anda sudah siap!

Untuk mulai mengembangkan, masuklah ke dokumentasi developer kami.

Aktifkan Google Maps JavaScript API

Untuk membantu Anda memulai, kami akan memandu Anda melalui Google Developers Console untuk melakukan beberapa hal terlebih dahulu:

  1. Buat atau pilih sebuah proyek
  2. Aktifkan Google Maps JavaScript API dan layanan terkait
  3. Buat kunci yang sesuai
Lanjutkan

Layanan Distance Matrix

Ringkasan

Layanan Distance Matrix dari Google menghitung jarak perjalanan dan waktu tempuh antara beberapa tempat asal dan tujuan menggunakan mode perjalanan yang diberikan.

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

Memulai

Sebelum menggunakan layanan Distance Matrix di Google Maps JavaScript API, terlebih dahulu pastikan Google Maps Distance Matrix API telah diaktifkan di Google API Console, dalam proyek yang sama dengan yang Anda persiapkan untuk Google Maps JavaScript API.

Untuk menampilkan daftar API yang telah diaktifkan:

  1. Masuklah ke Google API Console.
  2. Klik tombol Select a project, kemudian pilih proyek yang sama dengan yang Anda persiapkan untuk Google Maps JavaScript API dan klik Open.
  3. Dari daftar API di Dashboard, cari Google Maps Distance Matrix API.
  4. Jika sudah melihat API di dalam daftar, artinya Anda sudah siap. Jika API tidak dicantumkan, aktifkan:
    1. Di bagian atas laman, pilih ENABLE API untuk menampilkan tab Library. Atau, dari menu sisi kiri, pilih Library.
    2. Telusuri Google Maps Distance Matrix API, kemudian pilih dari daftar hasil.
    3. Pilih ENABLE. Bila proses selesai, Google Maps Distance Matrix API akan muncul dalam daftar API di Dashboard.

Kebijakan dan batas penggunaan

Kuota

Batas penggunaan berikut ini berlaku untuk layanan Distance Matrix:

Catatan: setiap kueri yang dikirim ke Distance Matrix dibatasi oleh jumlah elemen yang diperbolehkan, dalam hal ini jumlah asal dikali jumlah tujuan akan mendefinisikan jumlah elemen.

Penggunaan layanan Distance Matrix bersama Standard Plan

  • 2.500 elemen gratis per hari, dihitung sebagai jumlah kueri sisi-klien dan sisi-server; aktifkan penagihan untuk mengakses kuota harian lebih tinggi, yang dikenakan sebesar $0,50 USD / 1000 elemen tambahan, hingga 100.000 elemen per hari.
  • Maksimum 25 asal atau 25 tujuan per permintaan.
  • Maksimum 100 elemen per permintaan.
  • Maksimum 100 elemen per detik, yang dihitung sebagai jumlah kueri sisi-klien dan sisi-server.

Penggunaan layanan Distance Matrix bersama Premium Plan

  • Kuota gratis harian bersama sebesar 100.000 elemen per 24 jam; permintaan tambahan berlaku pada pembelian tahunan untuk Kredit Maps API.
  • Maksimum 25 asal atau 25 tujuan per permintaan.
  • Maksimum 625 elemen per permintaan. Catatan: permintaan menggunakan parameter opsional departure_time bila mode=driving dibatasi pada 100 elemen per permintaan.
  • Tanpa batas elemen sisi-klien per detik, per proyek. Perhatikan, API sisi-server dibatasi 1.000 elemen per detik.

Batas kecepatan berlaku per sesi pengguna, berapa pun banyaknya pengguna yang berbagi proyek yang sama.

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

Kebijakan

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

Permintaan Distance Matrix

Mengakses layanan Distance Matrix bersifat asinkron, karena Google Maps API harus melakukan panggilan ke server eksternal. Karena alasan itulah, Anda harus meneruskan metode callback untuk dieksekusi setelah permintaan diselesaikan, untuk memproses hasilnya.

Anda mengakses layanan Distance Matrix dalam kode Anda melalui objek google.maps.DistanceMatrixService. Metode DistanceMatrixService.getDistanceMatrix() memulai permintaan ke layanan Distance Matrix, 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.
}

Tampilkan contoh (distance-matrix.html)

DistanceMatrixRequest berisi bidang-bidang berikut:

  • origins (diperlukan) - Sebuah larik yang berisi satu atau beberapa string alamat, objek google.maps.LatLng, atau objek google.maps.Place untuk menghitung jarak dan waktu.
  • destinations (diperlukan) - Sebuah larik yang berisi satu atau beberapa string alamat, objek google.maps.LatLng, atau objek google.maps.Place untuk menghitung jarak dan waktu.
  • travelMode (opsional) — Moda transportasi yang akan digunakan saat menghitung arah. Lihat bagian mode perjalanan.
  • transitOptions (opsional) — Opsi yang hanya berlaku untuk permintaan dengan travelMode berupa TRANSIT. Nilai yang valid dijelaskan di bagian opsi angkutan umum.
  • drivingOptions (opsional) menetapkan nilai-nilai yang hanya berlaku untuk permintaan dengan travelMode berupa 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 bila memungkinkan.
  • avoidTolls (opsional) — Jika true, arah antar titik tersebut akan dihitung menggunakan rute non-tol, bila memungkinkan.

Mode Perjalanan

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

  • BICYCLING meminta arah bersepeda melalui jalur sepeda & jalan yang disukai (saat ini hanya tersedia di Amerika Serikat dan beberapa kota di Kanada).
  • DRIVING (default) menunjukkan arah mengemudi standar yang menggunakan jaringan jalan raya.
  • TRANSIT meminta arah melalui rute angkutan umum. Opsi ini hanya bisa ditetapkan jika permintaan menyertakan kunci API. Lihat bagian opsi angkutan umum untuk opsi yang tersedia dalam tipe permintaan ini.
  • WALKING meminta arah berjalan melalui jalur pejalan kaki & trotoar (bila tersedia).

Opsi Angkutan Umum

Transit Service saat ini 'bersifat eksperimen'. Selama fase ini, kita akan mengimplementasikan batas kecepatan untuk mencegah penyalahgunaan API. Pada akhirnya kami akan membatasi total permintaan per pemuatan peta berdasarkan penggunaan wajar atas API.

Opsi yang tersedia untuk permintaan matriks jarak bervariasi antar mode perjalanan. Pada permintaan angkutan umum, opsi avoidHighways dan avoidTolls diabaikan. Anda bisa menetapkan opsi rute angkutan umum spesifik melalui literal objek TransitOptions.

Permintaan angkutan umum sesuai-waktu. Perhitungan hanya akan dikembalikan untuk waktu mendatang.

Literal objek TransitOptions berisi bidang-bidang berikut:

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

Bidang-bidang ini dijelaskan di bawah:

  • arrivalTime (opsional) menetapkan waktu kedatangan yang diinginkan sebagai objek Date. Jika waktu kedatangan telah ditetapkan, waktu keberangkatan akan diabaikan.
  • departureTime (opsional) menetapkan waktu keberangkatan yang diinginkan sebagai objek Date. departureTime akan diabaikan jika arrivalTime telah ditetapkan. Default-nya adalah sekarang (yaitu, waktu saat ini) jika tidak ada nilai yang ditetapkan untuk departureTime atau arrivalTime.
  • modes (opsional) adalah larik yang berisi satu atau beberapa literal objek TransitMode. Bidang ini hanya bisa disertakan jika permintaan menyertakan kunci API. Setiap TransitMode menetapkan mode angkutan umum yang diutamakan. Nilai-nilai berikut ini diperbolehkan:
    • BUS menunjukkan rute yang sudah dihitung akan mengutamakan perjalanan dengan bus.
    • RAIL menunjukkan rute yang sudah dihitung akan mengutamakan perjalanan dengan kereta api, trem, kereta ringan, dan kereta bawah tanah.
    • SUBWAY menunjukkan rute yang sudah dihitung akan mengutamakan perjalanan dengan kereta bawah tanah.
    • TRAIN menunjukkan rute yang sudah dihitung akan mengutamakan perjalanan dengan kereta api.
    • TRAM menunjukkan rute yang sudah dihitung akan mengutamakan perjalanan dengan trem dan kereta ringan.
  • routingPreference (opsional) menetapkan preferensi untuk rute angkutan umum. Dengan menggunakan opsi ini, Anda dapat membias opsi yang dikembalikan, daripada menerima rute default terbaik yang dipilih oleh API. Bidang ini hanya dapat ditetapkan jika permintaan berisi kunci API. Nilai-nilai berikut ini diperbolehkan:
    • FEWER_TRANSFERS menunjukkan rute yang sudah dihitung akan mengutamakan jumlah ganti angkutan yang terbatas.
    • LESS_WALKING menunjukkan rute yang sudah dihitung akan mengutamakan jumlah berjalan kaki yang terbatas.

Opsi Mengemudi

Anda bisa menetapkan opsi perutean untuk rute mengemudi melalui objek DrivingOptions. Anda harus memberikan ID klien Google Maps APIs Premium Plan saat memuat API jika ingin menyertakan bidang drivingOptions di DistanceMatrixRequest.

Objek DrivingOptions berisi bidang-bidang berikut:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Bidang-bidang ini dijelaskan di bawah:

  • departureTime (diperlukan oleh literal objek drivingOptions agar valid) menetapkan waktu keberangkatan yang diinginkan sebagai objek Date. Nilainya harus disetel ke waktu saat ini atau ke waktu mendatang. Tidak boleh waktu yang sudah lewat. (API mengkonversi semua tanggal ke UTC untuk memastikan penanganan yang konsisten lintas zona waktu.) Untuk pelanggan Google Maps APIs Premium Plan, jika Anda menyertakan departureTime dalam permintaan, API akan mengembalikan rute terbaik berdasarkan kondisi lalu lintas yang diperkirakan pada saat itu, dan menyertakan perkiraan waktu lalu lintas (duration_in_traffic) dalam respons. Jika Anda tidak menetapkan waktu keberangkatan (yaitu, jika permintaan tidak menyertakan drivingOptions), rute yang dikembalikan adalah rute yang biasanya bagus tanpa memperhitungkan kondisi lalu lintas.
  • trafficModel (opsional) menetapkan asumsi yang akan digunakan saat menghitung waktu dalam lalu lintas. Setelan ini memengaruhi nilai yang dikembalikan di bidang 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 diperbolehkan:
    • bestguess (default) menunjukkan duration_in_traffic yang dikembalikan harus berupa perkiraan waktu tempuh terbaik berdasarkan informasi riwayat kondisi lalu lintas dan lalu lintas saat ini. Lalu lintas saat ini menjadi kian penting bila departure_time semakin dekat ke waktu sekarang.
    • optimistic menunjukkan duration_in_traffic yang dikembalikan lebih lama dari waktu tempuh sesungguhnya di hari-hari biasa, meskipun hari-hari tertentu dengan kondisi lalu lintas yang buruk mungkin melebihi nilai ini.
    • optimistic menunjukkan duration_in_traffic yang dikembalikan harus lebih singkat dari waktu tempuh sesungguhnya di hari biasa, meskipun hari-hari tertentu dengan kondisi lalu lintas yang baik bisa lebih cepat dari nilai ini.

Di bawah ini 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 mengembalikan sebuah objek DistanceMatrixResponse dan objek DistanceMatrixStatus. Ini akan diteruskan ke fungsi callback yang Anda tetapkan dalam permintaan.

Objek DistanceMatrixResponse berisi informasi jarak dan durasi untuk setiap pasang asal/tujuan bagi rute yang bisa 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 larik berisi lokasi yang diteruskan dalam bidang origins permintaan Distance Matrix. Alamat dikembalikan sebagaimana diformat oleh geocoder.
  • destinationAddresses adalah larik berisi lokasi yang diteruskan dalam bidang destinations, dalam format yang dikembalikan oleh geocoder.
  • rows adalah larik objek DistanceMatrixResponseRow, dengan setiap baris yang sesuai dengan tempat asal.
  • elements adalah anak rows, dan menyatakan sepasang asal dan tujuan masing-masing untuk baris tersebut. Isinya berupa status, durasi, jarak, dan informasi tarif (jika tersedia) untuk setiap pasang asal/tujuan.
  • Setiap element berisi bidang-bidang berikut:
    • status: Lihat Kode Status untuk daftar kemungkinan kode status.
    • duration: Lama waktu yang dibutuhkan untuk perjalanan rute ini, dinyatakan dalam detik (bidang value) dan sebagai text. Nilai tekstual diformat sesuai dengan unitSystem yang ditetapkan dalam permintaan (atau dalam metrik, jika tidak ada preferensi yang diberikan).
    • duration_in_traffic: Lama waktu yang dibutuhkan untuk perjalanan rute ini dengan memperhitungkan kondisi lalu lintas saat ini, dinyatakan dalam detik (bidang value) dan sebagai text. Nilai tekstual diformat sesuai dengan unitSystem yang ditetapkan dalam permintaan (atau dalam metrik, jika tidak ada preferensi yang diberikan). duration_in_traffic hanya dikembalikan ke pelanggan Google Maps APIs Premium Plan bila data lalu lintas tersedia, mode disetel ke driving, dan departureTime disertakan sebagai bagian dari bidang distanceMatrixOptions dalam permintaan.
    • distance: Jarak total rute ini, dinyatakan dalam meter (value) dan sebagai text. Nilai tekstual diformat sesuai dengan unitSystem yang ditetapkan 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 angkutan umum dan hanya untuk penyedia angkutan umum yang tersedia informasi tarifnya. Informasi ini menyertakan:
      • currency: Sebuah kode mata uang ISO 4217 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 menyertakan:

  • OK — Permintaan valid. Status ini bisa dikembalikan sekalipun 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 bidang yang diperlukan tidak ada. Lihat daftar bidang yang didukung di atas.
  • MAX_ELEMENTS_EXCEEDED — Hasil dari tempat asal dan tujuan melebihi batas per-query.
  • MAX_DIMENSIONS_EXCEEDED — Permintaan Anda berisi lebih dari 25 tempat asal, atau lebih dari 25 tempat tujuan.
  • OVER_QUERY_LIMIT — Aplikasi Anda meminta terlalu banyak elemen dalam jangka waktu yang diperbolehkan. Permintaan mungkin berhasil jika Anda mencoba lagi setelah menunggu beberapa saat.
  • REQUEST_DENIED — Layanan menolak penggunaan layanan Distance Matrix oleh laman web Anda.
  • UNKNOWN_ERROR — Permintaan Distance Matrix tidak bisa diproses karena kesalahan 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 bisa di-geocode.
  • OK — Respons berisi hasil yang valid.
  • ZERO_RESULTS — Tidak ditemukan rute antara tempat asal dan tujuan.

Mem-parse Hasil

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

Kirim masukan tentang...

Google Maps JavaScript API
Google Maps JavaScript API
Butuh bantuan? Kunjungi halaman dukungan kami.