Distance Matrix API 要求的格式如下:
https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters
其中 outputFormat
可為下列其中一個值:
json
(建議使用) 表示輸出格式為 JavaScript 物件註釋 (JSON);或xml
:表示輸出格式為 XML。
有些是必要參數,有些則是自選參數。跟網址的標準一樣,
參數則以 &
字元分隔。所有語言
保留字元 (例如加號「+」) 必須是
網址編碼:
參數清單和其可能的值列舉如下。
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 to849VCWC8%2BR9
). - compound code is a 6 character or longer local code
with an explicit location (
CWC8+R9 Mountain View, CA, USA
is encoded toCWC8%2BR9%20Mountain%20View%20CA%20USA
).
- global code is a 4 character area code and 6
character or longer local code (
- 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:
-
Encoded polylines must be prefixed with
- Place ID: If you supply a place ID, you must prefix it
with
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
orarrival_time
, but not both. Note thatarrival_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 thedeparture_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
orarrival_time
. If neither time is specified, thedeparture_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. Thedeparture_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.-
For requests where the travel mode is transit: You can optionally
specify one of
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 theAccept-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 adeparture_time
or anarrival_time
. If neither time is specified, thedeparture_time
defaults to now (that is, the departure time defaults to the current time). You can also optionally include atransit_mode
and/or atransit_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 adeparture_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 thedeparture_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 thebest_guess
travel time prediction may be shorter thanoptimistic
, or alternatively, longer thanpessimistic
, due to the way thebest_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 totransit_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.
要求範例
這個範例使用經緯度座標來指定 目的地座標:
網址
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'
以下範例使用 Plus Codes 來指定目的地座標:
網址
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'
以下範例說明使用編碼折線的相同要求:
網址
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'
交通資訊
只要符合下列所有條件 (這些條件都符合),系統就會使用路況資訊
需要在距離矩陣回應中收到 duration_in_traffic
欄位):
- 旅遊
mode
參數為driving
或未指定 (driving
是預設的交通方式)。 - 要求內含有效的
departure_time
參數。departure_time
可以設為目前時間或未來的時間, 不得設為過去的日期。
您可以視需要在traffic_model
請求,以指定計算交通時間時要採用的假設。
下列網址會針對麻薩諸塞州波士頓之間的行車距離發出「距離矩陣」要求
或麻薩諸塞州的查爾斯敦和麻薩諸塞州萊辛頓要求中包含出發時間
符合所有條件,傳回duration_in_traffic
距離矩陣回應。
網址
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>
位置修飾符
您可以用位置修飾符指示駕駛人應如何前往特定地點,
使用 side_of_road
修飾符指定要使用的道路的哪一側,或
請指定標題以指出正確的通行方向。
指定計算的路線必須通過道路的特定側
指定位置時,您可以要求計算的路線會經過
道路的任一側,使用
side_of_road:
前置字串。舉例來說,這個要求會傳回
長路線,確保車輛停在要接收的
路點有偏誤:
網址
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'
搭配編碼折線使用 side_of_road:
時,修飾符會套用至
每個位置。以本例中的兩個目的地為例
要求都使用 參數:
網址
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'
side_of_road:
修飾符只能搭配以下限制使用:
- 旅遊
mode
參數為driving
或不是 指定 (driving
是預設的交通方式)。
指定計算的路線應有特定的方向
指定位置時,您可以要求計算的路線經過
特定標題中的多個位置已指定這個標題
前置字串為 heading=X:
,其中 X 是整數度數值
介於 0 和 360 (不含 0 之間) 和 360 之間。標題 0 表示北方朝北,90
表示東方,以此類推,順時針繼續。例如,在這個例子中
要求計算的路線會從起點偏向,然後會採用迴轉:
網址
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'
heading=X:
修飾符只能搭配以下限制使用:
- 旅遊
mode
參數為driving
。bicycling
或未指定 (driving
是 預設交通方式)。 - 並未針對同一個位置指定
side_of_road
修飾符。 - 位置是以經緯度值指定。您不得使用
包含地址、地點 ID 或編碼折線的
heading
。
距離矩陣要求和回應
下方顯示一個要求距離和持續時間的 HTTP 要求範例 分別是溫哥華 (加拿大卑詩省) 以及美國華盛頓州西雅圖到加州舊金山 美國和加拿大英屬哥倫比亞省維多利亞。
網址
https://maps.googleapis.com/maps/api/distancematrix/json ?destinations=San%20Francisco%7CVictoria%20BC &language=fr-FR &mode=bicycling &origins=Vancouver%20BC%7CSeattle &key=YOUR_API_KEY
cURL
curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'
這項要求會傳回四個元素 (即 兩個起點乘以兩個目的地):
溫哥華到舊金山 | 溫哥華到維多利亞 |
西雅圖到舊金山 | 西雅圖到維多利亞 |
結果會以資料列的形式傳回,而每一列都會包含一個來源並對調 每個目的地
JSON
{ "destination_addresses": ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"], "origin_addresses": ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"], "rows": [ { "elements": [ { "distance": { "text": "1 712 km", "value": 1711765 }, "duration": { "text": "3 jours 16 heures", "value": 318119 }, "status": "OK", }, { "distance": { "text": "140 km", "value": 139695 }, "duration": { "text": "6 heures 49 minutes", "value": 24567 }, "status": "OK", }, ], }, { "elements": [ { "distance": { "text": "1 452 km", "value": 1451704 }, "duration": { "text": "3 jours 2 heures", "value": 266680 }, "status": "OK", }, { "distance": { "text": "146 km", "value": 146500 }, "duration": { "text": "2 heures 53 minutes", "value": 10374 }, "status": "OK", }, ], }, ], "status": "OK", }
XML
<DistanceMatrixResponse> <status>OK</status> <origin_address>Vancouver, BC, Canada</origin_address> <origin_address>Seattle, Washington, États-Unis</origin_address> <destination_address>San Francisco, Californie, États-Unis</destination_address> <destination_address>Victoria, BC, Canada</destination_address> <row> <element> <status>OK</status> <duration> <value>318119</value> <text>3 jours 16 heures</text> </duration> <distance> <value>1711765</value> <text>1 712 km</text> </distance> </element> <element> <status>OK</status> <duration> <value>24567</value> <text>6 heures 49 minutes</text> </duration> <distance> <value>139695</value> <text>140 km</text> </distance> </element> </row> <row> <element> <status>OK</status> <duration> <value>266680</value> <text>3 jours 2 heures</text> </duration> <distance> <value>1451704</value> <text>1 452 km</text> </distance> </element> <element> <status>OK</status> <duration> <value>10374</value> <text>2 heures 53 minutes</text> </duration> <distance> <value>146500</value> <text>146 km</text> </distance> </element> </row> </DistanceMatrixResponse>
DistanceMatrixResponse
Field | Required | Type | Description |
---|---|---|---|
| required | Array<string> |
An array of addresses as returned by the API from your original
request. As with |
| required | Array<string> | An array of addresses as returned by the API from your original request. These are formatted by the geocoder and localized according to the language parameter passed with the request. This content is meant to be read as-is. Do not programatically parse the formatted addresses. |
| required | Array<DistanceMatrixRow> |
An array of elements, which in turn each contain a
See DistanceMatrixRow for more information. |
| required | DistanceMatrixStatus | Contains the status of the request, and may contain debugging information to help you track down why the request failed. See DistanceMatrixStatus for more information. |
| optional | string | A string containing the human-readable text of any errors encountered while the request was being processed. |
DistanceMatrixStatus
Status codes returned by service.
OK
indicates the response contains a valid result.INVALID_REQUEST
indicates that the provided request was invalid.MAX_ELEMENTS_EXCEEDED
indicates that the product of origins and destinations exceeds the per-query limit.MAX_DIMENSIONS_EXCEEDED
indicates that the number of origins or destinations exceeds the per-query limit.OVER_DAILY_LIMIT
indicates any of the following:- The API key is missing or invalid.
- Billing has not been enabled on your account.
- A self-imposed usage cap has been exceeded.
- The provided method of payment is no longer valid (for example, a credit card has expired).
OVER_QUERY_LIMIT
indicates the service has received too many requests from your application within the allowed time period.REQUEST_DENIED
indicates that the service denied use of the Distance Matrix service by your application.UNKNOWN_ERROR
indicates a Distance Matrix request could not be processed due to a server error. The request may succeed if you try again.
DistanceMatrixRow
Field | Required | Type | Description |
---|---|---|---|
| required | Array<DistanceMatrixElement> | When the Distance Matrix API returns results, it places them within a JSON rows array. Even if no results are returned (such as when the origins and/or destinations don't exist), it still returns an empty array. Rows are ordered according to the values in the origin parameter of the request. Each row corresponds to an origin, and each element within that row corresponds to a pairing of the origin with a destination value. Each row array contains one or more element entries, which in turn contain the information about a single origin-destination pairing. See DistanceMatrixElement for more information. |
DistanceMatrixElement
Field | Required | Type | Description |
---|---|---|---|
| required | DistanceMatrixElementStatus | A status for the element. See DistanceMatrixElementStatus for more information. |
| optional | TextValueObject | The total distance of this route, expressed in meters (value) and as text. The textual value uses the unit system specified with the unit parameter of the original request, or the origin's region. See TextValueObject for more information. |
| optional | TextValueObject | The length of time it takes to travel this route, expressed in seconds (the value field) and as text. The textual representation is localized according to the query's language parameter. See TextValueObject for more information. |
| optional | TextValueObject |
The length of time it takes to travel this route, based on current
and historical traffic conditions. See the
See TextValueObject for more information. |
| optional | Fare | If present, contains the total fare (that is, the total ticket costs) on this route. This property is only returned for transit requests and only for transit providers where fare information is available. See Fare for more information. |
Fare
The total fare for the route.
{
"currency" : "USD",
"value" : 6,
"text" : "$6.00"
}
Field | Required | Type | Description |
---|---|---|---|
| required | string | An ISO 4217 currency code indicating the currency that the amount is expressed in. |
| required | string | The total fare amount, formatted in the requested language. |
| required | number | The total fare amount, in the currency specified. |
DistanceMatrixElementStatus
OK
indicates the response contains a valid result.NOT_FOUND
indicates that the origin and/or destination of this pairing could not be geocoded.ZERO_RESULTS
indicates no route could be found between the origin and destination.MAX_ROUTE_LENGTH_EXCEEDED
indicates the requested route is too long and cannot be processed.
TextValueObject
An object containing a numeric value and its formatted text representation.
Field | Required | Type | Description |
---|---|---|---|
| required | string | String value. |
| required | number | Numeric value. |