Yêu cầu và phản hồi API ma trận khoảng cách

Yêu cầu API ma trận khoảng cách có dạng sau:

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

trong đó outputFormat có thể là một trong những giá trị sau:

  • json (nên dùng), cho biết kết quả ở dạng Ký hiệu đối tượng JavaScript (JSON); hoặc
  • xml, cho biết dữ liệu đầu ra ở dạng XML.

Một số thông số là bắt buộc trong khi các thông số khác là không bắt buộc. Như tiêu chuẩn trong URL, tất cả các thông số được phân tách bằng ký tự dấu và (&). Tất cả ký tự dành riêng (ví dụ: dấu cộng "+") phải là Được mã hoá URL. Danh sách các tham số và giá trị có thể có của tham số được liệt kê dưới đây.

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.

Ví dụ về yêu cầu

Ví dụ này sử dụng toạ độ vĩ độ/kinh độ để chỉ định toạ độ đích:

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'

Ví dụ này sử dụng mã cộng để chỉ định toạ độ đích:

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'

Ví dụ này cho thấy cùng một yêu cầu bằng một hình nhiều đường được mã hoá:

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'

Thông tin giao thông

Thông tin giao thông được sử dụng khi tất cả các điều kiện sau đây áp dụng (đây là các điều kiện bắt buộc để nhận trường duration_in_traffic trong phản hồi Ma trận khoảng cách):

  • Thông số mode du lịch là driving hoặc không được chỉ định (driving là chế độ đi lại mặc định).
  • Yêu cầu này bao gồm một thông số departure_time hợp lệ. Chiến lược phát hành đĩa đơn Bạn có thể đặt departure_time thành thời gian hiện tại hoặc thời điểm nào đó trong tương lai. Thời điểm này không được là ngày trong quá khứ.

Nếu muốn, bạn có thể thêm thông số traffic_model vào yêu cầu của bạn để chỉ định các giả định cần sử dụng khi tính toán thời gian tham gia lưu lượng truy cập.

URL sau đây bắt đầu yêu cầu Ma trận khoảng cách để lái xe khoảng cách giữa Boston, MA hoặc Charlestown, MA và Lexington, MA và Concord, MA. Yêu cầu bao gồm thời gian khởi hành, đáp ứng tất cả các yêu cầu để trả về trường duration_in_traffic trong Phản hồi của ma trận khoảng cách.

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>

Công cụ sửa đổi vị trí

Bạn có thể sử dụng công cụ sửa đổi vị trí để cho biết cách người lái xe nên tiếp cận một vị trí cụ thể bằng cách sử dụng đối tượng sửa đổi side_of_road để chỉ định bên đường sẽ sử dụng hoặc bằng cách chỉ định tiêu đề để biểu thị đúng hướng di chuyển.

Chỉ định rằng các tuyến đường được tính toán phải đi qua một bên cụ thể của đường

Khi chỉ định một vị trí, bạn có thể yêu cầu tuyến đường đã tính toán đi qua bất kỳ phía nào của con đường mà điểm tham chiếu bị lệch về bằng cách sử dụng Tiền tố side_of_road:. Ví dụ: yêu cầu này sẽ trả về khoảng cách cho một tuyến đường dài để xe kết thúc ở bên đường mà điểm tham chiếu bị sai lệch:

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'

Khi sử dụng side_of_road: với hình nhiều đường mã hoá, đối tượng sửa đổi sẽ được áp dụng cho mọi vị trí dọc theo hình nhiều đường. Ví dụ: hai đích đến trong yêu cầu cả hai đều sử dụng tham số:

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'

Bạn chỉ có thể sử dụng đối tượng sửa đổi side_of_road: với quy định hạn chế này:

  • Thông số mode du lịch là driving hoặc không đã chỉ định (driving là chế độ đi lại mặc định).

Chỉ định rằng các tuyến đường đã tính toán phải có một tiêu đề cụ thể

Khi chỉ định một vị trí, bạn có thể yêu cầu tuyến đường đã tính toán đi qua trong một tiêu đề cụ thể. Tiêu đề này đã được chỉ định với tiền tố heading=X:, trong đó X là giá trị độ nguyên từ 0 (bao gồm) đến 360 (không bao gồm). Tiêu đề 0 biểu thị Bắc, 90 biểu thị Đông, v.v., tiếp tục theo chiều kim đồng hồ. Ví dụ: trong trường hợp này, yêu cầu tuyến đường đã tính toán đi về phía Đông từ điểm khởi hành, sau đó quay đầu:

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'

Bạn chỉ có thể sử dụng đối tượng sửa đổi heading=X: với các hạn chế sau:

  • Thông số mode du lịch là driving, bicycling hoặc không được chỉ định (driving là chế độ đi lại mặc định).
  • Đối tượng sửa đổi side_of_road không được chỉ định cho cùng một vị trí.
  • Vị trí được chỉ định bằng giá trị vĩ độ/kinh độ. Bạn không được sử dụng heading có địa chỉ, mã địa điểm hoặc hình nhiều dòng được mã hoá.

Yêu cầu và phản hồi của ma trận khoảng cách

Yêu cầu HTTP mẫu được hiển thị bên dưới, yêu cầu khoảng cách và thời lượng từ Vancouver, BC, Canada và từ Seattle, WA, Hoa Kỳ đến San Francisco, CA, Hoa Kỳ và đến Victoria, BC, Canada.

URL

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'

Yêu cầu này sẽ trả về 4 phần tử – 2 nguồn gốc nhân với 2 đích đến:

Vancouver đến San Francisco Vancouver đến Victoria
Seattle đến San Francisco Seattle đến Victoria

Kết quả được trả về theo hàng, mỗi hàng chứa một nguồn gốc được ghép nối với từng đích đến.

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

FieldRequiredTypeDescription
requiredArray<string>

An array of addresses as returned by the API from your original request. As with origin_addresses, these are localized if appropriate. This content is meant to be read as-is. Do not programatically parse the formatted addresses.

requiredArray<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 status, duration, and distance element.

See DistanceMatrixRow for more information.

requiredDistanceMatrixStatus

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.

optionalstring

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

FieldRequiredTypeDescription
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

FieldRequiredTypeDescription
requiredDistanceMatrixElementStatus

A status for the element.

See DistanceMatrixElementStatus for more information.

optionalTextValueObject

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.

optionalTextValueObject

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.

optionalTextValueObject

The length of time it takes to travel this route, based on current and historical traffic conditions. See the traffic_model request parameter for the options you can use to request that the returned value is optimistic, pessimistic, or a best-guess estimate. The duration is expressed in seconds (the value field) and as text. The textual representation is localized according to the query's language parameter. The duration in traffic is returned only if all of the following are true:

  • The request includes a departure_time parameter.
  • Traffic conditions are available for the requested route.
  • The mode parameter is set to driving.

See TextValueObject for more information.

optionalFare

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"
}
FieldRequiredTypeDescription
requiredstring

An ISO 4217 currency code indicating the currency that the amount is expressed in.

requiredstring

The total fare amount, formatted in the requested language.

requirednumber

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.

FieldRequiredTypeDescription
requiredstring

String value.

requirednumber

Numeric value.