Roads API zwraca podany limit prędkości dla danego segmentu drogi. W przypadku segmentów drogi ze zmiennymi ograniczeniami prędkości zwracany jest domyślny limit prędkości.
Nie można zagwarantować dokładności danych o ograniczeniach prędkości, które zwraca Roads API. Podane limity prędkości nie są podawane w czasie rzeczywistym i mogą być szacunkowe, niedokładne, niepełne lub nieaktualne. Zobacz szczegóły zasięgu, aby sprawdzić regiony, w których dostępne są dane o ograniczeniach prędkości.
Żądania
Żądania dotyczące ograniczeń prędkości muszą być wysyłane za pomocą protokołu HTTPS i mieć taką formę:
https://roads.googleapis.com/v1/speedLimits?parameters&key=YOUR_API_KEY
Wykorzystanie parametru
Parametry wymagane
- Parametr
path
lubplaceId
.path
– lista maksymalnie 100 szerokości i długości geograficznej reprezentująca ścieżkę. Długość i szerokość geograficzna muszą być rozdzielone przecinkami. Pary szerokości i długości geograficznej muszą być rozdzielone pionową kreską („|”). Gdy podajesz parametrpath
, interfejs API najpierw przechwytuje ścieżkę do najbardziej prawdopodobnej drogi pokonanej przez pojazd (tak jak w przypadku żądaniasnapToRoads
), a następnie określa limit prędkości dla odpowiedniego segmentu drogi. Jeśli nie chcesz, aby interfejs API przyciągał ścieżkę, musisz przekazać parametrplaceId
w sposób opisany poniżej. Poniższy przykład pokazuje parametrpath
z 3 parami szerokości i długości geograficznej:path=60.170880,24.942795|60.170879,24.942796|60.170877,24.942796
.placeId
– identyfikatory miejsc odpowiadające co najmniej jednemu fragmentowi drogi. Upewnij się, że każdy identyfikator miejsca odnosi się do segmentu drogi, a nie do innego typu miejsca. W każdym żądaniu możesz przekazać do 100 identyfikatorów miejsc. Interfejs API nie robi zdjęć na drogach na podstawie przesłanych identyfikatorów miejsc. Odpowiedź zawiera ograniczenie prędkości dla każdego identyfikatora miejsca w żądaniu. Możesz przesłać żądaniesnapToRoads
lubnearestRoads
, aby znaleźć odpowiednie identyfikatory miejsc, a następnie podać je jako dane wejściowe żądaniaspeedLimits
. Poniższy przykład pokazuje parametrplaceId
z 2 identyfikatorami miejsc:placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU
key
– klucz interfejsu API aplikacji. Aplikacja musi identyfikować się za każdym razem, gdy wysyła żądanie do Roads API, umieszczając w każdym żądaniu klucz interfejsu API. Dowiedz się, jak uzyskać klucz.
Parametry opcjonalne
units
– określa, czy wyświetlić ograniczenia prędkości w kilometrach czy milach na godzinę. Wartość tego ustawienia toKPH
lubMPH
. Domyślna wartość toKPH
.
Odpowiedzi
W odpowiedzi speedLimits
mogą występować te elementy:
speedLimits
– tablica metadanych drogi. Każdy element składa się z tych pól:placeId
– unikalny identyfikator miejsca. Wszystkie identyfikatory miejsc zwrócone przez obiekt Roads API będą odpowiadać segmentom drogi.speedLimit
– ograniczenie prędkości obowiązujące w przypadku tego fragmentu drogi.units
– zwraca wartośćKPH
lubMPH
.
snappedPoints
– tablica przyciąganych punktów. Ta tablica jest dostępna tylko wtedy, gdy żądanie zawiera parametrpath
. Każdy punkt składa się z następujących pól:location
– zawiera wartościlatitude
ilongitude
.originalIndex
– liczba całkowita wskazująca odpowiednią wartość w pierwotnym żądaniu. Każda wartość w żądaniu powinna być zmapowana na wartość zakodowaną w odpowiedzi. Wartości są indeksowane z0
, więc punkt z wartościąoriginalIndex
na poziomie4
będzie równaną wartością piątej szerokości i długości geograficznej przekazanej parametrowipath
.placeId
– unikalny identyfikator miejsca. Wszystkie identyfikatory miejsc zwrócone przez obiekt Roads API będą odpowiadać segmentom drogi.placeId
może być przekazywany w żądaniu ograniczenia prędkości, aby określić ograniczenie prędkości na danym odcinku drogi.
warning_message
– ciąg zawierający ostrzeżenie widoczne dla użytkownika.
Przykładowe żądanie z użyciem ścieżki
To żądanie podaje limit prędkości dla każdego segmentu drogi znajdującego się najbliżej określonych par szerokości i długości geograficznej na ścieżce przekraczającej most Vasco da Gama w Lizbonie.
Wyślij prośbę
https://roads.googleapis.com/v1/speedLimits?path=38.75807927603043,-9.03741754643809|38.6896537,-9.1770515|41.1399289,-8.6094075&key=YOUR_API_KEY
Odpowiedź
{ 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." }
Zwróć uwagę na komunikat ostrzegawczy dotyczący niespójności punktowej w odpowiedzi powyżej. Jeśli żądasz limitów prędkości w najbliższych odcinkach drogi, możesz wywołać metodę speedLimits
, podając identyfikatory miejsc pobrane z punktu końcowego nearestRoads
.
Przykładowe żądanie z wykorzystaniem identyfikatorów miejsc
Zamiast używać długości i szerokości geograficznej, możesz przekazywać identyfikatory miejsc segmentom dróg. Zalecamy uzyskiwanie identyfikatorów miejsc na potrzeby segmentów drogi za pomocą żądań snapToRoads
lub nearestRoads
. Po przekazaniu identyfikatorów miejsc interfejs API zwraca ograniczenie prędkości dla segmentu drogi reprezentowanego przez każdy identyfikator miejsca. Interfejs API nie stosuje żadnych przycięć drogi do podanych identyfikatorów miejsc.
W poniższym przykładzie określono ograniczenia prędkości dla niektórych fragmentów drogi biegnących przez most Vasco da Gama w Lizbonie.
Wyślij prośbę
https://roads.googleapis.com/v1/speedLimits?placeId=ChIJX12duJAwGQ0Ra0d4Oi4jOGE&placeId=ChIJLQcticc0GQ0RoiNZJVa5GxU&placeId=ChIJJ4vQRudkJA0RpednU70A-5M&key=YOUR_API_KEY
Odpowiedź
{ "speedLimits": [ { placeId: "ChIJX12duJAwGQ0Ra0d4Oi4jOGE", speedLimit: 105, units: "KPH" }, { placeId: "ChIJLQcticc0GQ0RoiNZJVa5GxU", speedLimit: 70, units: "KPH" }, { placeId: "ChIJJ4vQRudkJA0RpednU70A-5M", speedLimit: 55, units: "KPH" } ] }
Rekomendacje dotyczące użytkowania
Aby zminimalizować liczbę wywołań funkcji ograniczenia prędkości, zalecamy próbkowanie lokalizacji zasobów w 5–15-minutowych odstępach (dokładna wartość zależy od szybkości poruszania się zasobu). Jeśli zasób jest statyczny, wystarczy jedna próbka lokalizacji (nie trzeba wykonywać wielu wywołań).
Aby zminimalizować ogólny czas oczekiwania, zalecamy wywoływanie usługi Speed Speed po nagromadzeniu części danych, zamiast wywoływać interfejs API za każdym razem, gdy odbierasz lokalizację zasobu mobilnego.
Dlaczego brakuje niektórych lub wszystkich ograniczeń prędkości?
Najczęstszą przyczyną braku wartości speedLimits
jest żądanie ograniczenia prędkości na obszarze, które nie jest fragmentem drogi.
W powyższym przykładzie użyto ilustracji Vasco da Gama. Most obsługuje drogę E90 nad Rio Tejo. Sam most ma identyfikator miejsca ChIJUzt97ZEwGQ0RM1JzQfqoDtU. Pierwszy fragment drogi w powyższej odpowiedzi jest częścią drogi E90 i ma identyfikator miejsca ChIJX12duJAwGQ0Ra0d4Oi4jOGE. W tym przykładzie, jeśli zastąpisz identyfikator miejsca drogi identyfikatorem miejsca mostu, w odpowiedzi pojawią się w tablicy speedLimits
tylko dwa ograniczenia prędkości, ponieważ identyfikator miejsca mostu nie odnosi się do pojedynczego segmentu drogi. Jeśli żaden z identyfikatorów miejsca nie jest przeznaczony dla fragmentów drogi, odpowiedź nie będzie zawierać żadnych ograniczeń prędkości.
Przy zgłaszaniu prośby o ograniczenie prędkości używające identyfikatorów miejsc upewnij się, że każdy identyfikator miejsca odnosi się do segmentu drogi, a nie do innego typu miejsca. Identyfikatory miejsc poszczególnych segmentów drogi najlepiej pobierać za pomocą żądań snapToRoads
lub nearestRoads
. Każde z nich może zwrócić wiele identyfikatorów miejsca z jednego wywołania.