Giới hạn tốc độ

Roads API sẽ trả về giới hạn tốc độ đã đăng cho một đoạn đường nhất định. Trong trường hợp đoạn đường có giới hạn tốc độ thay đổi, giới hạn tốc độ mặc định cho đoạn đó sẽ được trả về.

Độ chính xác của dữ liệu giới hạn tốc độ do Roads API trả về không thể được đảm bảo. Dữ liệu về giới hạn tốc độ đã cung cấp không phải theo thời gian thực và có thể được ước tính, không chính xác, không đầy đủ và/hoặc đã lỗi thời. Xem thông tin chi tiết về phạm vi bao phủ để xem các khu vực có dữ liệu giới hạn tốc độ.

Yêu cầu

Yêu cầu về giới hạn tốc độ phải được gửi qua HTTPS và có dạng như sau:

https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY

Cách sử dụng thông số

Các thông số bắt buộc

  • Tham số path hoặc placeId.
    • path – Danh sách tối đa 100 cặp vĩ độ/kinh độ đại diện cho một đường dẫn. Các giá trị vĩ độ và kinh độ phải được phân tách bằng dấu phẩy. Các cặp vĩ độ/kinh độ phải được phân tách bằng ký tự ống: "|". Khi bạn cung cấp tham số path, trước tiên API sẽ chụp đường dẫn đến đường có khả năng nhất của xe (như đối với yêu cầu snapToRoads), sau đó xác định giới hạn tốc độ cho đoạn đường liên quan. Nếu không muốn API chụp đường dẫn, bạn phải chuyển một thông số placeId như giải thích bên dưới. Ví dụ sau đây cho thấy thông số path có ba cặp vĩ độ/kinh độ: path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796.
    • placeId — (Các) mã địa điểm thể hiện một hoặc nhiều đoạn đường. Hãy đảm bảo mỗi mã địa điểm đề cập đến một đoạn đường chứ không phải một loại địa điểm khác. Bạn có thể chuyển tối đa 100 mã địa điểm với mỗi yêu cầu. API không thực hiện thao tác giành quyền trên đường đi đối với mã địa điểm được cung cấp. Nội dung phản hồi bao gồm giới hạn tốc độ cho từng mã địa điểm trong yêu cầu. Bạn có thể gửi yêu cầu snapToRoads hoặc nearestRoads để tìm mã địa điểm liên quan, sau đó cung cấp các mã đó làm yêu cầu đầu vào cho yêu cầu speedLimits. Ví dụ sau đây cho thấy thông số placeId có hai mã địa điểm: placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
  • key – Khoá API của ứng dụng. Ứng dụng phải tự nhận dạng mỗi khi gửi yêu cầu đến Roads API bằng cách thêm khoá API với mỗi yêu cầu. Tìm hiểu cách nhận khoá.

Tham số không bắt buộc

  • units – Liệu có cần trả về giới hạn tốc độ tính theo km hay dặm/giờ hay không. Bạn có thể đặt giá trị này thành KPH hoặc MPH. Giá trị mặc định là KPH.

Nội dung trả lời

Các phần tử sau có thể xuất hiện trong phản hồi speedLimits:

  • speedLimits – Một mảng siêu dữ liệu về đường. Mỗi phần tử bao gồm các trường sau:
    • placeId — Giá trị nhận dạng duy nhất của một địa điểm. Tất cả mã địa điểm do Roads API trả về sẽ tương ứng với các đoạn đường.
    • speedLimit — Giới hạn tốc độ cho đoạn đường đó.
    • units – Trả về KPH hoặc MPH.
  • snappedPoints – một loạt các điểm ảnh chụp nhanh. Mảng này chỉ xuất hiện nếu yêu cầu chứa tham số path. Mỗi điểm bao gồm các trường sau:
    • location — chứa giá trị latitudelongitude.
    • originalIndex – Một số nguyên thể hiện giá trị tương ứng trong yêu cầu ban đầu. Mỗi giá trị trong yêu cầu phải ánh xạ tới một giá trị được giành lấy trong phản hồi. Các giá trị này được lập chỉ mục từ 0, vì vậy, một điểm có originalIndex4 sẽ là giá trị chụp nhanh của vĩ độ/kinh độ thứ 5 được chuyển đến thông số path.
    • placeId — Giá trị nhận dạng duy nhất của một địa điểm. Tất cả mã địa điểm do Roads API trả về sẽ tương ứng với các đoạn đường. placeId có thể được chuyển trong yêu cầu giới hạn tốc độ để xác định giới hạn tốc độ dọc theo đoạn đường đó.
  • warning_message – Một chuỗi chứa cảnh báo mà người dùng nhìn thấy được.

Ví dụ về yêu cầu bằng cách sử dụng đường dẫn

Yêu cầu này đặt giới hạn tốc độ cho từng đoạn đường gần nhất với các cặp vĩ độ/kinh độ được chỉ định trong đường dẫn bắc qua cây cầu Pacco da Gama ở Lisbon, Bồ Đào Nha.

Yêu cầu

https://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEY

Đáp

{
  speedLimits:
  [
    {
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE",
      speedLimit: 105,
      units: "KPH"
    },
    {
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU",
      speedLimit: 70,
      units: "KPH"
    },
    {
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M",
      speedLimit: 55,
      units: "KPH"
    }
  ],
  snappedPoints:
  [
    {
      location:
      {
        latitude: 38.75807927603043,
        longitude: -9.037417546438084
      },
      originalIndex: 0,
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE"
    },
    {
      location:
      {
        latitude: 38.689653701836896,
        longitude: -9.177051486847693
      },
      originalIndex: 1,
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU"
    },
    {
      location:
      {
        latitude: 41.13993011767777,
        longitude: -8.609400794783655
      },
      originalIndex: 2,
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M"
    }
  ],
  warningMessage: "Input path is too sparse. You should provide a path where consecutive points are closer to each other. Refer to the 'path' parameter in Google Roads API documentation."
}

Hãy lưu ý thông báo cảnh báo để biết mức độ rộng rãi của phản hồi ở trên. Nếu đang yêu cầu giới hạn tốc độ cho các đoạn đường gần nhất tại các điểm bất kỳ, bạn phải gọi speedLimits với mã địa điểm được truy xuất từ điểm cuối nearestRoads.

Yêu cầu mẫu sử dụng mã địa điểm

Thay vì sử dụng các cặp vĩ độ/kinh độ, bạn có thể chuyển mã địa điểm của các đoạn đường. Bạn nên lấy mã địa điểm cho đoạn đường bằng cách sử dụng yêu cầu snapToRoads hoặc nearestRoads. Khi bạn chuyển mã địa điểm, API sẽ trả về giới hạn tốc độ cho đoạn đường biểu thị bằng từng mã địa điểm. API không áp dụng bất kỳ đường chiếm quyền nào cho mã địa điểm đã cung cấp.

Ví dụ sau đây yêu cầu giới hạn tốc độ cho một số đoạn đường bắc qua cầu Valco da Gama ở Lisbon, Bồ Đào Nha.

Yêu cầu

https://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEY

Đáp

{
  "speedLimits": [
    {
      placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE",
      speedLimit: 105,
      units: "KPH"
    },
    {
      placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU",
      speedLimit: 70,
      units: "KPH"
    },
    {
      placeId: "ChIJJ4vQRudkJA0RpednU70A-5M",
      speedLimit: 55,
      units: "KPH"
    }
  ]
}

Đề xuất sử dụng

Để giảm thiểu số lượng lệnh gọi đến dịch vụ Giới hạn tốc độ, bạn nên lấy mẫu các vị trí của thành phần trong khoảng thời gian từ 5 đến 15 phút (giá trị chính xác tuỳ thuộc vào tốc độ di chuyển của một thành phần). Nếu một thành phần cố định, thì chỉ cần một mẫu vị trí là đủ (không cần thực hiện nhiều lệnh gọi).

Để giảm thiểu độ trễ tổng thể, bạn nên gọi dịch vụ Giới hạn tốc độ sau khi đã tích luỹ một số dữ liệu thay vì gọi API mỗi khi nhận được vị trí của thành phần trên thiết bị di động.

Tại sao một số/tất cả giới hạn tốc độ bị thiếu?

Nguyên nhân phổ biến nhất dẫn đến tình trạng thiếu speedLimits là do yêu cầu giới hạn tốc độ của địa điểm không phải là đoạn đường.

Ví dụ ở trên sử dụng cầu Vatu da Gama để minh hoạ các khái niệm; cây cầu hỗ trợ con đường E90 bắc qua Rio Tejo. Bản thân cây cầu có mã địa điểm là ChIJUzt97ZEwGQ0RM1JzQfqoDtU. Đoạn đường đầu tiên trong phản hồi ở trên là một phần của đường E90 và có mã địa điểm là ChIJX12duJAwGQ0Ra0d4Oi4jOGE. Trong yêu cầu ví dụ, nếu bạn thay thế mã địa điểm đường bộ bằng mã địa điểm của cầu, thì trong phản hồi, chỉ có hai giới hạn tốc độ trong mảng speedLimits vì mã địa điểm của cầu không tham chiếu đến một đoạn đường riêng lẻ. Hơn nữa, nếu không có mã địa điểm nào là dành cho đoạn đường, thì phản hồi sẽ không chứa giới hạn tốc độ.

Khi đưa ra yêu cầu về giới hạn tốc độ bằng mã địa điểm, hãy đảm bảo mỗi mã địa điểm chỉ một đoạn đường chứ không phải một loại địa điểm khác. Tốt nhất là bạn nên truy xuất mã địa điểm cho các đoạn đường riêng lẻ bằng cách sử dụng yêu cầu snapToRoads hoặc nearestRoads, cả hai đều có thể trả về nhiều mã địa điểm từ một lệnh gọi.