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

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Giới thiệu

Yêu cầu Distance Matrix API có dạng như sau:

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

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

  • json (nên dùng) cho biết đầu ra ở định dạng Ký hiệu đối tượng JavaScript (JSON).
  • xml cho biết đầu ra dưới dạng XML.

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

Thông số bắt buộc

  • đích đến

    Một hoặc nhiều vị trí dùng làm điểm kết thúc để tính toán quãng đường và thời gian di chuyển. Các lựa chọn cho tham số đích đến giống với tham số điểm xuất phát.

  • nguồn gốc

    Điểm xuất phát để tính toán khoảng cách và thời gian di chuyển. Bạn có thể cung cấp một hoặc nhiều vị trí được phân tách bằng dấu gạch đứng (|), dưới dạng Mã địa điểm, địa chỉ hoặc toạ độ vĩ độ/kinh độ:

    • Mã địa điểm: Nếu cung cấp mã địa điểm, bạn phải thêm tiền tố place_id: vào mã đó.
    • Địa chỉ: Nếu bạn truyền một địa chỉ, dịch vụ sẽ mã hoá địa lý chuỗi đó và chuyển đổi thành toạ độ vĩ độ/kinh độ để tính khoảng cách. Toạ độ này có thể khác với toạ độ do Geocoding API trả về, ví dụ: lối vào của một toà nhà thay vì tâm của toà nhà đó.
      Lưu ý: bạn nên sử dụng mã địa điểm thay vì sử dụng địa chỉ hoặc toạ độ vĩ độ/kinh độ. Việc sử dụng toạ độ sẽ luôn dẫn đến việc điểm được gắn vào con đường gần nhất với những toạ độ đó – có thể không phải là điểm truy cập vào tài sản, hoặc thậm chí là con đường sẽ dẫn đến đích đến một cách nhanh chóng hoặc an toàn. Khi sử dụng địa chỉ, bạn sẽ biết được khoảng cách đến trung tâm của toà nhà, thay vì đến một lối vào của toà nhà.
    • Toạ độ: Nếu bạn truyền toạ độ vĩ độ/kinh độ, thì các toạ độ này sẽ bám theo con đường gần nhất. Bạn nên truyền mã địa điểm. Nếu bạn truyền toạ độ, hãy đảm bảo rằng không có khoảng trắng giữa các giá trị vĩ độ và kinh độ.
    • Plus Code phải được định dạng dưới dạng mã chung hoặc mã kết hợp. Định dạng mã cộng như minh hoạ ở đây (dấu cộng được thoát URL thành %2B và khoảng trắng được thoát URL thành %20):
      • mã toàn cầu là mã vùng gồm 4 ký tự và mã địa phương gồm 6 ký tự trở lên (849VCWC8+R9 được mã hoá thành 849VCWC8%2BR9).
      • mã kết hợp là mã cục bộ có từ 6 ký tự trở lên với vị trí rõ ràng (CWC8+R9 Mountain View, CA, USA được mã hoá thành CWC8%2BR9%20Mountain%20View%20CA%20USA).
    • Đường đa tuyến được mã hoá Ngoài ra, bạn có thể cung cấp một tập hợp toạ độ được mã hoá bằng Thuật toán đường đa tuyến được mã hoá. Điều này đặc biệt hữu ích nếu bạn có nhiều điểm xuất phát, vì URL sẽ ngắn hơn đáng kể khi sử dụng một đường nhiều đoạn được mã hoá.
      • Đường nhiều đoạn được mã hoá phải có tiền tố là enc: và theo sau là dấu hai chấm :. Ví dụ: origins=enc:gfo}EtohhU:
      • Bạn cũng có thể thêm nhiều đường nhiều đoạn được mã hoá, phân tách bằng dấu gạch đứng |. Ví dụ: 
        origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:

Thông số tùy chọn

  • arrival_time

    Chỉ định thời gian đến ưu tiên cho đường đi bằng phương tiện công cộng, tính bằng giây kể từ nửa đêm ngày 1 tháng 1 năm 1970 theo giờ UTC. Bạn có thể chỉ định departure_time hoặc arrival_time, nhưng không được chỉ định cả hai. Xin lưu ý rằng bạn phải chỉ định arrival_time dưới dạng một số nguyên.

  • tránh

    Khoảng cách có thể được tính toán theo một số quy định hạn chế nhất định. Các quy định hạn chế được chỉ ra bằng cách sử dụng tham số avoid và một đối số cho tham số đó cho biết quy định hạn chế cần tránh. Các hạn chế sau đây được hỗ trợ:

    • tolls cho biết tuyến đường được tính toán sẽ tránh các đường/cầu thu phí.
    • highways cho biết tuyến đường được tính toán phải tránh đường cao tốc.
    • ferries cho biết tuyến đường được tính toán phải tránh phà.
    • indoor cho biết tuyến đường được tính toán phải tránh các bước trong nhà cho chỉ đường đi bộ và đường đi bằng phương tiện công cộng.

    Bạn có thể yêu cầu một tuyến đường tránh mọi tổ hợp trạm thu phí, đường cao tốc và phà bằng cách truyền cả hai hạn chế này vào tham số tránh. Ví dụ: avoid=tolls|highways|ferries.

    Lưu ý: Việc thêm các quy tắc hạn chế không loại trừ những tuyến đường có chứa đối tượng bị hạn chế; việc này chỉ thiên về những tuyến đường thuận lợi hơn.

  • departure_time

    Chỉ định thời gian khởi hành ưu tiên. Bạn có thể chỉ định thời gian dưới dạng số nguyên tính bằng giây kể từ nửa đêm ngày 1 tháng 1 năm 1970 (theo giờ UTC). Nếu bạn chỉ định departure_time sau 9999-12-31T23:59:59.999999999Z, thì API sẽ chuyển departure_time về 9999-12-31T23:59:59.999999999Z. Ngoài ra, bạn có thể chỉ định giá trị là now. Giá trị này sẽ đặt thời gian khởi hành thành thời gian hiện tại (chính xác đến từng giây). Bạn có thể chỉ định thời gian khởi hành trong 2 trường hợp:

    • Đối với các yêu cầu có chế độ di chuyển là phương tiện công cộng: Bạn có thể tuỳ ý chỉ định một trong các chế độ departure_time hoặc arrival_time. Nếu bạn không chỉ định thời gian nào, thì departure_time sẽ mặc định là thời gian hiện tại (tức là thời gian khởi hành mặc định là thời gian hiện tại).
    • Đối với các yêu cầu có chế độ di chuyển là lái xe: Bạn có thể chỉ định departure_time để nhận một tuyến đường và thời gian di chuyển (trường phản hồi: duration_in_traffic) có tính đến tình trạng giao thông. departure_time phải được đặt thành thời gian hiện tại hoặc một thời điểm nào đó trong tương lai. Ngày này không được là một ngày trong quá khứ.
    Lưu ý: Nếu bạn không chỉ định thời gian khởi hành, lựa chọn về tuyến đường và thời lượng sẽ dựa trên mạng lưới đường bộ và điều kiện giao thông trung bình không phụ thuộc vào thời gian. Kết quả cho một yêu cầu nhất định có thể thay đổi theo thời gian do những thay đổi trong mạng lưới đường, tình trạng giao thông trung bình mới nhất và bản chất phân tán của dịch vụ. Kết quả cũng có thể khác nhau giữa các tuyến đường gần tương đương vào bất kỳ thời điểm hoặc tần suất nào.
    Lưu ý: Yêu cầu Distance Matrix chỉ định departure_time khi mode=driving bị giới hạn tối đa 100 phần tử cho mỗi yêu cầu. Số lượng điểm xuất phát nhân với số lượng điểm đến sẽ xác định số lượng phần tử.

  • language

    Ngôn ngữ mà bạn muốn nhận kết quả.

    • Xem danh sách các ngôn ngữ được hỗ trợ. Google thường xuyên cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể chưa đầy đủ.
    • Nếu bạn không cung cấp language, API sẽ cố gắng sử dụng ngôn ngữ ưu tiên như được chỉ định trong tiêu đề Accept-Language.
    • API này cố gắng cung cấp một địa chỉ đường phố mà cả người dùng và người dân địa phương đều có thể đọc được. Để đạt được mục tiêu đó, phương thức này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một kịch bản mà người dùng có thể đọc được (nếu cần), tuân theo ngôn ngữ ưu tiên. Tất cả các địa chỉ khác đều được trả về bằng ngôn ngữ ưu tiên. Tất cả các thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ, được chọn từ thành phần đầu tiên.
    • Nếu không có tên bằng ngôn ngữ ưu tiên, API sẽ sử dụng kết quả trùng khớp gần nhất.
    • Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến tập hợp kết quả mà API chọn trả về và thứ tự trả về. Trình mã hoá địa lý diễn giải các từ viết tắt theo nhiều cách tuỳ thuộc vào ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ trong một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác. Ví dụ: utca và tér là từ đồng nghĩa với đường phố trong tiếng Hungary.

  • chế độ

    Để tính toán khoảng cách và đường đi, bạn có thể chỉ định phương tiện giao thông cần sử dụng. Theo mặc định, chế độ DRIVING sẽ được dùng. Theo mặc định, chỉ đường được tính là chỉ đường lái xe. Các chế độ di chuyển sau đây được hỗ trợ:

    • driving (mặc định) cho biết chỉ đường lái xe tiêu chuẩn hoặc khoảng cách bằng cách sử dụng mạng lưới đường bộ.
    • walking yêu cầu chỉ đường hoặc khoảng cách đi bộ bằng đường dành cho người đi bộ và vỉa hè (nếu có).
    • bicycling yêu cầu chỉ đường hoặc khoảng cách đi xe đạp bằng đường dành cho xe đạp và đường phố ưu tiên (nếu có).
    • transit yêu cầu chỉ đường hoặc khoảng cách bằng các tuyến đường phương tiện công cộng (nếu có). Nếu đặt chế độ thành phương tiện công cộng, bạn có thể chỉ định departure_time hoặc arrival_time (không bắt buộc). Nếu bạn không chỉ định thời gian nào, thì departure_time sẽ mặc định là thời gian hiện tại (tức là thời gian khởi hành mặc định là thời gian hiện tại). Bạn cũng có thể thêm transit_mode và/hoặc transit_routing_preference (không bắt buộc).
    Lưu ý: Đôi khi, cả đường đi bộ và đường đi xe đạp đều có thể không bao gồm đường đi bộ hoặc đường đi xe đạp rõ ràng, vì vậy, những đường đi này sẽ trả về cảnh báo trong kết quả trả về mà bạn phải hiển thị cho người dùng.
    Lưu ý: Chuyến đi bằng phương tiện công cộng có thể xem được tối đa 7 ngày trước đó hoặc tối đa 100 ngày sau đó, tuỳ thuộc vào thông tin về phương tiện công cộng do nhà cung cấp dữ liệu cung cấp. Lịch trình phương tiện công cộng thay đổi thường xuyên, các chuyến đi bằng phương tiện công cộng có thể thay đổi theo thời gian và không có gì đảm bảo rằng kết quả dự đoán sẽ nhất quán trong thời gian dài.

  • khu vực

    Mã vùng, được chỉ định là giá trị gồm 2 ký tự ccTLD ("miền cấp cao nhất"). Hầu hết mã ccTLD đều giống với mã ISO 3166-1, ngoại trừ một số trường hợp đáng chú ý. Ví dụ: ccTLD của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 của quốc gia này là "gb" (về mặt kỹ thuật là cho thực thể "Vương quốc Anh và Bắc Ireland").

  • traffic_model

    Chỉ định các giả định cần sử dụng khi tính toán thời gian trong lưu lượng truy cập. Chế độ cài đặt này ảnh hưởng đến giá trị được trả về trong trường duration_in_traffic trong phản hồi. Trường này chứa thời gian dự kiến khi có lưu lượng truy cập dựa trên mức trung bình trong quá khứ. Bạn chỉ có thể chỉ định tham số traffic_model cho chỉ đường lái xe khi yêu cầu có chứa departure_time. Các giá trị có thể sử dụng cho tham số này là:

    • best_guess (mặc định) cho biết duration_in_traffic được trả về phải là thông tin ước tính chính xác nhất về thời gian di chuyển dựa trên những thông tin đã biết về cả tình trạng giao thông trong quá khứ và giao thông theo thời gian thực. Thông tin giao thông theo thời gian thực càng quan trọng hơn khi departure_time càng gần với thời điểm hiện tại.
    • pessimistic cho biết duration_in_traffic được trả về phải dài hơn thời gian di chuyển thực tế vào hầu hết các ngày, mặc dù đôi khi vào những ngày có tình trạng giao thông đặc biệt xấu, giá trị này có thể vượt quá.
    • optimistic cho biết duration_in_traffic được trả về phải ngắn hơn thời gian di chuyển thực tế vào hầu hết các ngày, mặc dù đôi khi vào những ngày có điều kiện giao thông đặc biệt thuận lợi, thời gian di chuyển có thể nhanh hơn giá trị này.

    Giá trị mặc định của best_guess sẽ đưa ra những dự đoán hữu ích nhất cho phần lớn các trường hợp sử dụng. Có thể thời gian di chuyển dự đoán best_guess ngắn hơn optimistic hoặc dài hơn pessimistic do cách mô hình dự đoán tích hợp thông tin giao thông theo thời gian thực best_guess.

  • transit_mode

    Chỉ định một hoặc nhiều phương thức di chuyển ưu tiên. Bạn chỉ có thể chỉ định tham số này cho đường đi bằng phương tiện công cộng. Tham số này hỗ trợ các đối số sau:

    • bus cho biết tuyến đường được tính toán nên ưu tiên di chuyển bằng xe buýt.
    • subway cho biết tuyến đường được tính toán nên ưu tiên đi bằng tàu điện ngầm.
    • train cho biết rằng tuyến đường được tính nên ưu tiên di chuyển bằng tàu hoả.
    • tram cho biết tuyến đường được tính toán nên ưu tiên di chuyển bằng xe điện và tàu điện.
    • rail cho biết tuyến đường được tính toán nên ưu tiên di chuyển bằng tàu hoả, xe điện, tàu điện ngầm và tàu điện ngầm. Điều này tương đương với transit_mode=train|tram|subway.

  • transit_routing_preference

    Chỉ định lựa chọn ưu tiên cho các tuyến đường dành cho phương tiện công cộng. Khi sử dụng tham số này, bạn có thể điều chỉnh các lựa chọn được trả về thay vì chấp nhận tuyến đường tối ưu mặc định do API chọn. Bạn chỉ có thể chỉ định tham số này cho chỉ đường bằng phương tiện công cộng. Tham số này hỗ trợ các đối số sau:

    • less_walking cho biết tuyến đường được tính toán nên ưu tiên đi bộ trong khoảng thời gian ngắn.
    • fewer_transfers cho biết tuyến đường được tính nên ưu tiên số lần chuyển phương tiện có giới hạn.

  • đơn vị

    Chỉ định hệ thống đơn vị cần dùng khi hiển thị kết quả.

    Lưu ý: chế độ cài đặt hệ đơn vị này chỉ ảnh hưởng đến văn bản xuất hiện trong các trường khoảng cách. Các trường khoảng cách cũng chứa những giá trị luôn được biểu thị bằng mét.

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ã địa chỉ để chỉ định toạ độ đích đến:

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 cách sử dụng một đường nhiều đoạn đượ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 về giao thông

Thông tin về lưu lượng truy cập được sử dụng khi tất cả các điều kiện sau đây được áp dụng (đây là những đ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):

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

Bạn có thể thêm tham số traffic_model vào yêu cầu của mình (không bắt buộc) để chỉ định các giả định cần sử dụng khi tính toán thời gian di chuyển trong điều kiện giao thông.

URL sau đây bắt đầu một yêu cầu Distance Matrix cho khoảng cách lái xe giữa Boston, MA hoặc Charlestown, MA và Lexington, MA và Concord, MA. Yêu cầu này bao gồm thời gian khởi hành, đáp ứng mọi yêu cầu để trả về trường duration_in_traffic trong phản hồi 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


 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins

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

Bạn có thể dùng các đối tượng 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 dùng đối tượng sửa đổi side_of_road để chỉ định bên đường cần dùng hoặc bằng cách chỉ định hướng đi để cho biết hướng di chuyển chính xác.

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

Khi chỉ định một vị trí, bạn có thể yêu cầu tuyến đường được tính toán đi qua bất kỳ bên đường nào mà điểm tham chiếu bị lệch về phía đó 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 ở phía đường mà điểm tham chiếu được điều chỉnh:

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 các hình nhiều đường được 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ụ: cả hai đích đến trong yêu cầu này đề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: khi có hạn chế này:

  • Tham số modedu lịch là driving hoặc không được chỉ định (driving là chế độ du lịch mặc định).

Chỉ định rằng các tuyến đường được tính toán phải có một hướng cụ thể

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

  • Tham số mode cho loại hình doanh nghiệp du lịch là driving, bicycling hoặc không được chỉ định (driving là chế độ di chuyển mặc định).
  • Bạn không chỉ định đối tượng sửa đổi side_of_road 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 với địa chỉ, mã địa điểm hoặc đường nhiều đoạn được mã hoá.

Yêu cầu và phản hồi của Distance Matrix

Sau đây là một yêu cầu HTTP mẫu, yêu cầu khoảng cách và thời lượng từ Vancouver, British Columbia, Canada và từ Seattle, Washington, Hoa Kỳ đến San Francisco, California, Hoa Kỳ và đến Victoria, British Columbia, 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 điểm xuất phát và 2 điểm đến:

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

Kết quả được trả về theo hàng, mỗi hàng chứa một điểm xuất phát được ghép với từng điểm đế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


 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km

DistanceMatrixResponse

Trường Bắt buộc Loại Mô tả
bắt buộc Array<string>

Một mảng địa chỉ do API trả về từ yêu cầu ban đầu của bạn. Giống như origin_addresses, những thông tin này được bản địa hoá nếu phù hợp. Nội dung này được dùng để đọc nguyên trạng. Đừng phân tích cú pháp theo cách lập trình các địa chỉ được định dạng.

bắt buộc Array<string>

Một mảng địa chỉ do API trả về từ yêu cầu ban đầu của bạn. Các thông tin này được bộ mã hoá địa lý định dạng và bản địa hoá theo tham số ngôn ngữ được truyền cùng với yêu cầu. Nội dung này được dùng để đọc nguyên trạng. Đừng phân tích cú pháp theo lập trình các địa chỉ được định dạng.

bắt buộc Array<DistanceMatrixRow>

Một mảng các phần tử, trong đó mỗi phần tử lần lượt chứa một phần tử status, duration và distance.

Hãy xem DistanceMatrixRow để biết thêm thông tin.

bắt buộc DistanceMatrixStatus

Chứa trạng thái của yêu cầu và có thể chứa thông tin gỡ lỗi để giúp bạn theo dõi lý do khiến yêu cầu không thành công.

Hãy xem DistanceMatrixStatus để biết thêm thông tin.

tùy chọn chuỗi

Một chuỗi chứa văn bản mà con người có thể đọc được về mọi lỗi gặp phải trong quá trình xử lý yêu cầu.

DistanceMatrixStatus

Mã trạng thái do dịch vụ trả về.

  • OK cho biết câu trả lời chứa một kết quả hợp lệ.
  • INVALID_REQUEST cho biết rằng yêu cầu được cung cấp không hợp lệ.
  • MAX_ELEMENTS_EXCEEDED cho biết rằng sản phẩm của điểm xuất phát và điểm đến vượt quá giới hạn cho mỗi truy vấn.
  • MAX_DIMENSIONS_EXCEEDED cho biết số lượng điểm xuất phát hoặc điểm đến vượt quá giới hạn cho mỗi truy vấn.
  • OVER_DAILY_LIMIT cho biết một trong những trường hợp sau:
    • Khoá API bị thiếu hoặc không hợp lệ.
    • Bạn chưa bật tính năng thanh toán cho tài khoản của mình.
    • Bạn đã vượt quá hạn mức sử dụng do chính mình đặt ra.
    • Phương thức thanh toán bạn cung cấp không còn hợp lệ (ví dụ: thẻ tín dụng đã hết hạn).
  • OVER_QUERY_LIMIT cho biết dịch vụ đã nhận được quá nhiều yêu cầu từ ứng dụng của bạn trong khoảng thời gian cho phép.
  • REQUEST_DENIED cho biết rằng dịch vụ đã từ chối ứng dụng của bạn sử dụng dịch vụ Ma trận khoảng cách.
  • UNKNOWN_ERROR cho biết không thể xử lý yêu cầu Ma trận khoảng cách do lỗi máy chủ. Yêu cầu có thể thành công nếu bạn thử lại.

DistanceMatrixRow

Trường Bắt buộc Loại Mô tả
bắt buộc Array<DistanceMatrixElement>

Khi Distance Matrix API trả về kết quả, API này sẽ đặt kết quả trong một mảng hàng JSON. Ngay cả khi không có kết quả nào được trả về (chẳng hạn như khi không có điểm xuất phát và/hoặc điểm đến), thì phương thức này vẫn trả về một mảng trống.

Các hàng được sắp xếp theo giá trị trong tham số nguồn gốc của yêu cầu. Mỗi hàng tương ứng với một nguồn và mỗi phần tử trong hàng đó tương ứng với một cặp nguồn có giá trị đích.

Mỗi mảng hàng chứa một hoặc nhiều mục nhập phần tử, lần lượt chứa thông tin về một cặp nguồn gốc – đích đến duy nhất.

Hãy xem DistanceMatrixElement để biết thêm thông tin.

DistanceMatrixElement

Trường Bắt buộc Loại Mô tả
bắt buộc DistanceMatrixElementStatus

Trạng thái của phần tử.

Hãy xem DistanceMatrixElementStatus để biết thêm thông tin.

tùy chọn TextValueObject

Tổng quãng đường của tuyến đường này, được biểu thị bằng mét (giá trị) và dưới dạng văn bản. Giá trị văn bản sử dụng hệ thống đơn vị được chỉ định bằng tham số đơn vị của yêu cầu ban đầu hoặc khu vực của nguồn gốc.

Hãy xem TextValueObject để biết thêm thông tin.

tùy chọn TextValueObject

Khoảng thời gian cần thiết để đi theo tuyến đường này, được biểu thị bằng giây (trường giá trị) và dưới dạng văn bản. Biểu diễn bằng văn bản được bản địa hoá theo tham số ngôn ngữ của truy vấn.

Hãy xem TextValueObject để biết thêm thông tin.

tùy chọn TextValueObject

Khoảng thời gian cần thiết để di chuyển trên tuyến đường này, dựa trên tình trạng giao thông hiện tại và trước đây. Hãy xem tham số yêu cầu traffic_model để biết các lựa chọn mà bạn có thể dùng để yêu cầu giá trị trả về là giá trị lạc quan, bi quan hoặc ước tính gần đúng nhất. Thời lượng được biểu thị bằng giây (trường giá trị) và dưới dạng văn bản. Biểu diễn bằng văn bản được bản địa hoá theo tham số ngôn ngữ của truy vấn. Thời lượng trong lưu lượng truy cập chỉ được trả về nếu tất cả các điều kiện sau đều đúng:

  • Yêu cầu này bao gồm một tham số departure_time.
  • Tình trạng giao thông có sẵn cho tuyến đường được yêu cầu.
  • Tham số mode được đặt thành driving.

Hãy xem TextValueObject để biết thêm thông tin.

tùy chọn Giá vé

Nếu có, trường này chứa tổng giá vé (tức là tổng chi phí vé) trên tuyến đường này. Thuộc tính này chỉ được trả về cho các yêu cầu về phương tiện công cộng và chỉ dành cho những nhà cung cấp dịch vụ vận chuyển công cộng có thông tin về giá vé.

Hãy xem Giá vé để biết thêm thông tin.

Giá vé

Tổng giá vé của tuyến đường.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}
Trường Bắt buộc Loại Mô tả
bắt buộc chuỗi

Mã đơn vị tiền tệ theo ISO 4217 cho biết đơn vị tiền tệ mà số tiền được biểu thị.

text

bắt buộc chuỗi

Tổng số tiền giá vé, được định dạng bằng ngôn ngữ yêu cầu.
bắt buộc số

Tổng số tiền giá vé, tính bằng đơn vị tiền tệ được chỉ định.

DistanceMatrixElementStatus

  • OK cho biết câu trả lời chứa một kết quả hợp lệ.
  • NOT_FOUND cho biết rằng hệ thống không thể mã hoá địa lý nguồn và/hoặc điểm đến của cặp này.
  • ZERO_RESULTS cho biết không tìm thấy tuyến đường nào giữa điểm khởi hành và điểm đến.
  • MAX_ROUTE_LENGTH_EXCEEDED cho biết tuyến đường được yêu cầu quá dài và không thể xử lý.

TextValueObject

Một đối tượng chứa giá trị dạng số và biểu thị văn bản được định dạng của giá trị đó.

Trường Bắt buộc Loại Mô tả

text

bắt buộc chuỗi

Giá trị chuỗi.
bắt buộc số

Giá trị số.