API Tuyến đường hiện đang ở chế độ Xem trước (trước GA). Các sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể không được hỗ trợ hạn chế. Đồng thời, các thay đổi đối với sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể không tương thích với các phiên bản trước giai đoạn phát hành rộng rãi khác. Các Sản phẩm trước giai đoạn phát hành rộng rãi chịu sự điều chỉnh của Điều khoản dành riêng cho dịch vụ nền tảng Google Maps. Để biết thêm thông tin, hãy xem nội dung mô tả giai đoạn ra mắt.

Tính toán ma trận tuyến đường

Sử dụng API tuyến đường để tính khoảng cách và thời lượng của một tuyến đường cho nhiều điểm khởi hành và điểm đến bằng cách gọi phương thức computeRouteMatrix (REST) hoặc phương thức ComputeRouteMatrix (gRPC).

Với danh sách các cặp điểm khởi hành và điểm đến, các phương thức tính toán khoảng cách và thời lượng của một tuyến đường bắt đầu tại mỗi điểm xuất phát và kết thúc tại mỗi điểm đến.

Giới hạn về yêu cầu

Các phương thức Ma trận tuyến tính thực thi các giới hạn của yêu cầu sau:

  • Số lượng phần tử (số nguồn gốc × số đích) không thể vượt quá 625.

  • Nếu bạn chỉ định TRAFFIC_AWARE_OPTIMAL, thì số lượng phần tử không thể vượt quá 100. Để biết thêm thông tin về TRAFFIC_AWARE_OPTIMAL, hãy xem phần Định cấu hình chất lượng so với độ trễ.

  • Số lượng điểm trung bình (nguồn gốc + điểm đến) tối đa mà bạn có thể chỉ định bằng cách sử dụng Mã địa điểm là 50.

Lỗi phản hồi

Một tính năng của phương thức Ma trận tuyến đường là các lỗi có thể được trả về cho toàn bộ phản hồi hoặc cho từng phần tử phản hồi. Ví dụ: toàn bộ phản hồi chứa lỗi nếu yêu cầu không đúng định dạng (ví dụ: yêu cầu không có nguồn gốc).

Tuy nhiên, nếu lỗi áp dụng cho một tập hợp con các phần tử trong phản hồi (ví dụ: không thể tính toán tuyến đường cho một tổ hợp điểm xuất phát và điểm đến), thì chỉ những phần tử bị ảnh hưởng mới có thể trả về mã lỗi.

Kết quả phát trực tiếp

Phương thức gRPC ComputeRouteMatrix lấy danh sách các điểm khởi hành và điểm đến, đồng thời trả về một luồng chứa thông tin tuyến đường cho từng tổ hợp điểm khởi hành và điểm đến. Vì kết quả được trả về dưới dạng luồng, nên bạn không cần phải đợi cho đến khi tất cả các tổ hợp tuyến đường có thể được tính toán trước khi có thể bắt đầu xử lý kết quả.

Các phần tử do luồng trả về không đảm bảo được trả về theo thứ tự bất kỳ. Do đó, mỗi phần tử phản hồi chứa một origin_index và một destination_index. Đối với điểm khởi hành và điểm đến do yêu cầu chỉ định, điểm xuất phát của tuyến đường tương đương với origins[origin_index] của một phần tử nhất định và đích đến của tuyến đường tương đương với destinations[destination_index]. Các mảng này đã được lập chỉ mục bằng 0. Điều quan trọng là bạn phải lưu trữ các đơn đặt hàng gốc và danh sách đích.

Ví dụ về tính toán ma trận tuyến đường

Sử dụng phương thức computeRouteMatrix trong một yêu cầu HTTP để tính toán một ma trận tuyến.

Ví dụ về HTTP

Ví dụ sau đây cho thấy một yêu cầu HTTP computeRouteMatrix. Trong ví dụ này, bạn:

  • Chỉ định một mảng gồm hai điểm xuất phát và hai điểm tham chiếu đích. Phương thức này sẽ tính toán một tuyến đường từ mỗi điểm khởi hành đến mỗi đích đến để phản hồi chứa bốn tuyến.

    Trong mảng, phần tử đầu tiên ở chỉ mục 0, phần tử thứ hai là chỉ mục 1, v.v.

  • Thêm mặt nạ trường phản hồi để chỉ định các trường của phản hồi (REST) hoặc ComputeRoutesResponse (gRPC) cần trả về. Trong ví dụ này, hãy định cấu hình yêu cầu trả về originIndex, destinationIndex, duration, distanceMeters, statuscondition cho mỗi tuyến đường. Để biết thêm thông tin, hãy xem phần Chọn trường cần trả về.

curl -X POST -d '{
  "origins": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420761,
            "longitude": -122.081356
          }
        }
      },
      "routeModifiers": { "avoid_ferries": true}
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.403184,
            "longitude": -122.097371
          }
        }
      },
      "routeModifiers": { "avoid_ferries": true}
    }
  ],
  "destinations": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420999,
            "longitude": -122.086894
          }
        }
      }
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.383047,
            "longitude": -122.044651
          }
        }
      }
    }
  ],
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status,condition' \
'https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix'

Phản hồi chứa 4 tuyến có thể kết hợp của tất cả điểm xuất phát và điểm đến.

Xác định từng tuyến trong phản hồi bằng các trường phản hồi originIndexdestinationIndex. Ví dụ: originIndex của 1 trong phản hồi tương ứng với một tuyến đường được tính từ điểm tham chiếu tại chỉ mục 1 của mảng origins trong yêu cầu.

[
    {
        "originIndex": 0,
        "destinationIndex": 0,
        "status": {},
        "distanceMeters": 822,
        "duration": "160s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 1,
        "destinationIndex": 0,
        "status": {},
        "distanceMeters": 2919,
        "duration": "361s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 1,
        "destinationIndex": 1,
        "status": {},
        "distanceMeters": 5598,
        "duration": "402s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 0,
        "destinationIndex": 1,
        "status": {},
        "distanceMeters": 7259,
        "duration": "712s",
        "condition": "ROUTE_EXISTS"
    }
]

Ví dụ về gRPC

Ví dụ về các yêu cầu gRPC, hãy xem các ví dụ về Ví dụ về yêu cầu gRPC. Ví dụ về Java trên trang đó gọi cả Tuyến tính toán và Ma trận tuyến tính.