Coba fitur Distance Matrix generasi berikutnya dengan Routes API.

Halaman ini diterjemahkan oleh Cloud Translation API.

Permintaan dan respons Distance Matrix API

Permintaan Distance Matrix API memiliki bentuk berikut:

https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters

dengan outputFormat dapat berupa salah satu nilai berikut:

json (direkomendasikan), menunjukkan output dalam JavaScript Object Notation (JSON); atau
xml, menunjukkan output sebagai XML.

Beberapa parameter tertentu wajib ditentukan sementara yang lainnya bersifat opsional. Sesuai dengan standar dalam URL, semua parameter dipisah menggunakan karakter ampersand (&). Semua karakter yang dicadangkan (misalnya tanda plus "+") harus dienkode URL. Daftar parameter dan kemungkinan nilainya disebutkan di bawah ini.

Required parameters

destinations
One or more locations to use as the finishing point for calculating travel distance and time. The options for the destinations parameter are the same as for the origins parameter.
origins
The starting point for calculating travel distance and time. You can supply one or more locations separated by the pipe character (|), in the form of a place ID, an address, or latitude/longitude coordinates:
- Place ID: If you supply a place ID, you must prefix it with place_id:.
- Address: If you pass an address, the service geocodes the string and converts it to a latitude/longitude coordinate to calculate distance. This coordinate may be different from that returned by the Geocoding API, for example a building entrance rather than its center.
  Note: using place IDs is preferred over using addresses or latitude/longitude coordinates. Using coordinates will always result in the point being snapped to the road nearest to those coordinates - which may not be an access point to the property, or even a road that will quickly or safely lead to the destination. Using the address will provide the distance to the center of the building, as opposed to an entrance to the building.
- Coordinates: If you pass latitude/longitude coordinates, they they will snap to the nearest road. Passing a place ID is preferred. If you do pass coordinates, ensure that no space exists between the latitude and longitude values.
- Plus codes must be formatted as a global code or a compound code. Format plus codes as shown here (plus signs are url-escaped to %2B and spaces are url-escaped to %20):
  - global code is a 4 character area code and 6 character or longer local code (849VCWC8+R9 is encoded to 849VCWC8%2BR9).
  - compound code is a 6 character or longer local code with an explicit location (CWC8+R9 Mountain View, CA, USA is encoded to CWC8%2BR9%20Mountain%20View%20CA%20USA).
- Encoded Polyline Alternatively, you can supply an encoded set of coordinates using the Encoded Polyline Algorithm. This is particularly useful if you have a large number of origin points, because the URL is significantly shorter when using an encoded polyline.
  - Encoded polylines must be prefixed with enc: and followed by a colon :. For example: origins=enc:gfo}EtohhU:
  - You can also include multiple encoded polylines, separated by the pipe character |. For example:
```
origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
```

Optional parameters

arrival_time
Specifies the desired time of arrival for transit directions, in seconds since midnight, January 1, 1970 UTC. You can specify either departure_time or arrival_time, but not both. Note that arrival_time must be specified as an integer.
avoid
Distances may be calculated that adhere to certain restrictions. Restrictions are indicated by use of the avoid parameter, and an argument to that parameter indicating the restriction to avoid. The following restrictions are supported:
- tolls indicates that the calculated route should avoid toll roads/bridges.
- highways indicates that the calculated route should avoid highways.
- ferries indicates that the calculated route should avoid ferries.
- indoor indicates that the calculated route should avoid indoor steps for walking and transit directions.
It's possible to request a route that avoids any combination of tolls, highways and ferries by passing both restrictions to the avoid parameter. For example avoid=tolls|highways|ferries.
Note: The addition of restrictions does not preclude routes that include the restricted feature; it biases the result to more favorable routes.
departure_time
Specifies the desired time of departure. You can specify the time as an integer in seconds since midnight, January 1, 1970 UTC. If a departure_time later than 9999-12-31T23:59:59.999999999Z is specified, the API will fall back the departure_time to 9999-12-31T23:59:59.999999999Z. Alternatively, you can specify a value of now, which sets the departure time to the current time (correct to the nearest second). The departure time may be specified in two cases:
- For requests where the travel mode is transit: You can optionally specify one of departure_time or arrival_time. If neither time is specified, the departure_time defaults to now (that is, the departure time defaults to the current time).
- For requests where the travel mode is driving: You can specify the departure_time to receive a route and trip duration (response field: duration_in_traffic) that take traffic conditions into account. The departure_time must be set to the current time or some time in the future. It cannot be in the past.
Note: If departure time is not specified, choice of route and duration are based on road network and average time-independent traffic conditions. Results for a given request may vary over time due to changes in the road network, updated average traffic conditions, and the distributed nature of the service. Results may also vary between nearly-equivalent routes at any time or frequency.
Note: Distance Matrix requests specifying `departure_time` when `mode=driving` are limited to a maximum of 100 elements per request. The number of origins times the number of destinations defines the number of elements.
language
The language in which to return results.
- See the list of supported languages. Google often updates the supported languages, so this list may not be exhaustive.
- If language is not supplied, the API attempts to use the preferred language as specified in the Accept-Language header.
- The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
- If a name is not available in the preferred language, the API uses the closest match.
- The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, utca and tér are synonyms for street in Hungarian.
mode
For the calculation of distances and directions, you may specify the transportation mode to use. By default, DRIVING mode is used. By default, directions are calculated as driving directions. The following travel modes are supported:
- driving (default) indicates standard driving directions or distance using the road network.
- walking requests walking directions or distance via pedestrian paths & sidewalks (where available).
- bicycling requests bicycling directions or distance via bicycle paths & preferred streets (where available).
- transit requests directions or distance via public transit routes (where available). Transit trips are available for up to 7 days in the past or 100 days in the future. If you set the mode to transit, you can optionally specify either a departure_time or an arrival_time. If neither time is specified, the departure_time defaults to now (that is, the departure time defaults to the current time). You can also optionally include a transit_mode and/or a transit_routing_preference.
Note: Both walking and bicycling directions may sometimes not include clear pedestrian or bicycling paths, so these directions will return warnings in the returned result which you must display to the user.
region
The region code, specified as a ccTLD ("top-level domain") two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland").
traffic_model
Specifies the assumptions to use when calculating time in traffic. This setting affects the value returned in the duration_in_traffic field in the response, which contains the predicted time in traffic based on historical averages. The traffic_model parameter may only be specified for driving directions where the request includes a departure_time. The available values for this parameter are:
- best_guess (default) indicates that the returned duration_in_traffic should be the best estimate of travel time given what is known about both historical traffic conditions and live traffic. Live traffic becomes more important the closer the departure_time is to now.
- pessimistic indicates that the returned duration_in_traffic should be longer than the actual travel time on most days, though occasional days with particularly bad traffic conditions may exceed this value.
- optimistic indicates that the returned duration_in_traffic should be shorter than the actual travel time on most days, though occasional days with particularly good traffic conditions may be faster than this value.
The default value of best_guess will give the most useful predictions for the vast majority of use cases. It is possible the best_guess travel time prediction may be shorter than optimistic, or alternatively, longer than pessimistic, due to the way the best_guess prediction model integrates live traffic information.
transit_mode
Specifies one or more preferred modes of transit. This parameter may only be specified for transit directions. The parameter supports the following arguments:
- bus indicates that the calculated route should prefer travel by bus.
- subway indicates that the calculated route should prefer travel by subway.
- train indicates that the calculated route should prefer travel by train.
- tram indicates that the calculated route should prefer travel by tram and light rail.
- rail indicates that the calculated route should prefer travel by train, tram, light rail, and subway. This is equivalent to transit_mode=train|tram|subway.
transit_routing_preference
Specifies preferences for transit routes. Using this parameter, you can bias the options returned, rather than accepting the default best route chosen by the API. This parameter may only be specified for transit directions. The parameter supports the following arguments:
- less_walking indicates that the calculated route should prefer limited amounts of walking.
- fewer_transfers indicates that the calculated route should prefer a limited number of transfers.
units
Specifies the unit system to use when displaying results.
Note: this unit system setting only affects the text displayed within distance fields. The distance fields also contain values which are always expressed in meters.

Contoh permintaan

Contoh ini menggunakan koordinat garis lintang/bujur untuk menentukan koordinat tujuan:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

Contoh ini menggunakan kode plus untuk menentukan koordinat tujuan:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

Contoh ini menampilkan permintaan yang sama menggunakan polyline yang dienkodekan:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

Informasi lalu lintas

Informasi lalu lintas digunakan jika semua hal berikut berlaku (ini adalah kondisi yang diperlukan untuk menerima kolom duration_in_traffic dalam respons Distance Matrix):

Parameter mode perjalanan adalah driving, atau belum ditentukan (driving adalah mode perjalanan default).
Permintaan menyertakan parameter departure_time yang valid. departure_time dapat ditetapkan ke waktu saat ini atau waktu mendatang. Tidak boleh waktu yang sudah lewat.

Secara opsional, Anda dapat menyertakan parameter traffic_model dalam permintaan untuk menentukan asumsi yang akan digunakan saat menghitung waktu dalam traffic.

URL berikut memulai permintaan Distance Matrix untuk jarak mengemudi antara Boston, MA atau Charlestown, MA, dan Lexington, MA dan Concord, MA. Permintaan menyertakan waktu keberangkatan, yang memenuhi semua persyaratan untuk menampilkan kolom duration_in_traffic dalam respons Distance Matrix.

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

JSON

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

XML

<DistanceMatrixResponse>
 <status>OK</status>
 <origin_address>Boston, MA, USA</origin_address>
 <origin_address>Charlestown, Boston, MA, USA</origin_address>
 <destination_address>Lexington, MA, USA</destination_address>
 <destination_address>Concord, MA, USA</destination_address>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>1620</value>
    <text>27 mins</text>
   </duration>
   <distance>
    <value>33253</value>
    <text>33.3 km</text>
   </distance>
   <duration_in_traffic>
    <value>2018</value>
    <text>34 mins</text>
   </duration_in_traffic>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>1981</value>
    <text>33 mins</text>
   </duration>
   <distance>
    <value>41491</value>
    <text>41.5 km</text>
   </distance>
   <duration_in_traffic>
    <value>2342</value>
    <text>39 mins</text>
   </duration_in_traffic>
  </element>
 </row>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>1543</value>
    <text>26 mins</text>
   </duration>
   <distance>
    <value>31100</value>
    <text>31.1 km</text>
   </distance>
   <duration_in_traffic>
    <value>1759</value>
    <text>29 mins</text>
   </duration_in_traffic>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>1904</value>
    <text>32 mins</text>
   </duration>
   <distance>
    <value>39338</value>
    <text>39.3 km</text>
   </distance>
   <duration_in_traffic>
    <value>2077</value>
    <text>35 mins</text>
   </duration_in_traffic>
  </element>
 </row>
</DistanceMatrixResponse>

Pengubah Lokasi

Anda dapat menggunakan pengubah lokasi untuk menunjukkan bagaimana pengemudi harus mendekati lokasi tertentu, dengan menggunakan pengubah side_of_road untuk menentukan sisi jalan yang akan digunakan, atau dengan menentukan judul untuk menunjukkan arah perjalanan yang benar.

Menentukan bahwa rute yang dihitung harus melewati sisi jalan tertentu

Saat menentukan lokasi, Anda dapat meminta agar rute yang dihitung melalui jalan mana pun yang dituju titik jalan dengan menggunakan awalan side_of_road:. Misalnya, permintaan ini akan menampilkan jarak untuk rute panjang sehingga kendaraan berakhir di sisi jalan tempat titik jalan dibiaskan:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

Saat menggunakan side_of_road: dengan polyline yang dienkode, pengubah diterapkan ke setiap lokasi di sepanjang polyline. Misalnya, kedua tujuan dalam permintaan ini menggunakan parameter:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

Pengubah side_of_road: hanya dapat digunakan dengan batasan ini:

Parameter mode perjalanan adalah driving, atau belum ditentukan (driving adalah mode perjalanan default).

Menentukan bahwa rute yang dihitung harus memiliki judul tertentu

Saat menentukan lokasi, Anda dapat meminta agar rute yang dihitung melalui lokasi dalam arah tertentu. Judul ini ditentukan dengan awalan heading=X:, dengan X adalah nilai derajat bilangan bulat antara 0 (inklusif) dan 360 (eksklusif). Arah 0 menunjukkan Utara, 90 menunjukkan Timur, dan seterusnya, terus searah jarum jam. Misalnya, dalam permintaan ini, rute yang dihitung mengarah ke timur dari asal, lalu berbelok balik:

URL

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

Pengubah heading=X: hanya boleh digunakan dengan batasan berikut:

Parameter mode perjalanan adalah driving, bicycling, atau belum ditentukan (driving adalah mode perjalanan default).
Pengubah side_of_road tidak ditentukan untuk lokasi yang sama.
Lokasi ditentukan dengan nilai lintang/bujur. Anda tidak boleh menggunakan heading dengan alamat, ID Tempat, atau polyline yang dienkode.