Metoda computeRoutes (REST) i metoda ComputeRoutes (gRPC) zwracają w odpowiedzi trasę przedstawioną za pomocą linii łamanej. Te interfejsy API zwracają 2 rodzaje linii łamanych:
Podstawowa linia łamana (domyślna), która reprezentuje trasę, ale bez informacji o ruchu drogowym osadzonych w linii łamanej. Żądania, które zwracają podstawową linię łamaną, są rozliczane według stawki za Routes Basic. Więcej informacji o płatnościach za interfejs Routes API
Linia łamana uwzględniająca natężenie ruchu, która zawiera informacje o warunkach na drodze na trasie. Warunki na drogach są wyrażane w kategoriach prędkości (
NORMAL,SLOW,TRAFFIC_JAM) obowiązujących w danym przedziale polilinii. Żądania polilinii uwzględniających ruch są rozliczane według stawki Routes Preferred. Więcej informacji o płatnościach za interfejs Routes API. Więcej informacji znajdziesz w artykule Konfigurowanie jakości polilinii.
Więcej informacji o liniach łamanych znajdziesz w tych artykułach:
Interaktywne narzędzie do kodowania linii łamanych umożliwia tworzenie zakodowanych linii łamanych w interfejsie lub dekodowanie linii łamanych w celu wyświetlania ich na mapie. Możesz na przykład użyć tego narzędzia do zdekodowania linii łamanej utworzonej przez poniższy kod.
Żądanie podstawowej linii łamanej dla trasy, odcinka lub kroku
Linia łamana jest reprezentowana przez obiekt Polyline (REST) lub Polyline (gRPC). W odpowiedzi możesz zwrócić linię łamaną na poziomie trasy, odcinka i kroku.
Określ, którą linię łamaną chcesz zwrócić, używając maski pola odpowiedzi:
Na poziomie trasy zwróć w odpowiedzi linię łamaną, uwzględniając w masce pola odpowiedzi wartość
routes.polyline.Na poziomie odcinka zwracaj w odpowiedzi linię łamaną dla każdego odcinka trasy, uwzględniając parametr
routes.legs.polyline.Na poziomie kroku zwracaj w odpowiedzi linię łamaną dla każdego kroku odcinka, uwzględniając parametr
routes.legs.steps.polyline.
Aby na przykład zwrócić linię łamaną dla całej trasy, dla każdego etapu i dla każdego kroku każdego etapu:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
W odpowiedzi na to żądanie otrzymasz te informacje, w tym linię łamaną trasy, dla każdego odcinka trasy i dla każdego kroku odcinka:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } }, "steps": [ { "polyline": { "encodedPolyline": "kclcF...@sC@YIOKI" } }, { "polyline": { "encodedPolyline": "wblcF~...SZSF_@?" } }, ... ], "distanceMeters": 56901, "duration": "2420s", "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } } ] }
Ponieważ to żądanie zawiera tylko punkt początkowy i miejsce docelowe, zwrócona trasa zawiera tylko 1 odcinek. Dlatego linia łamana dla odcinka i dla trasy jest taka sama.
Jeśli do żądania dodasz pośredni punkt trasy, zwrócona trasa będzie zawierać 2 odcinki:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "intermediates": [ { "address": "450 Serra Mall, Stanford, CA 94305, USA"}, ], "travelMode": "DRIVE", }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
To żądanie zwraca 2 odcinki, z których każdy ma unikalną linię łamaną, oraz linię łamaną dla całej trasy:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG" } "steps": [ { "polyline": { "encodedPolyline": "kclcFfqch...YIOKI" } }, ... }, { "polyline": { "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G" } "steps": [ { "polyline": { "encodedPolyline": "uypeFbo`jVgJq...PoBiC" } }, ... } ], "distanceMeters": 68403, "duration": "3759s", "polyline": { "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE" } } ] }
Jakość linii łamanej
Jakość polilinii można opisać w ten sposób:
Precyzja zmiennoprzecinkowa punktów
Punkty są określane jako wartości szerokości i długości geograficznej, które są reprezentowane w formacie zmiennoprzecinkowym pojedynczej precyzji. Sprawdza się to w przypadku małych wartości (które można dokładnie przedstawić), ale precyzja maleje wraz ze wzrostem wartości ze względu na błędy zaokrąglania liczb zmiennoprzecinkowych.
W metodzie computeRoutes (REST) i ComputeRoutes jest to kontrolowane przez
polylineEncoding.Liczba punktów tworzących polilinię
Im więcej punktów, tym gładsza jest linia łamana (zwłaszcza na zakrętach).
W metodzie computeRoutes (REST) i ComputeRoutes jest to kontrolowane przez
polylineQuality.
Konfigurowanie typu kodowania linii łamanej
Użyj opcji żądania polylineEncoding, aby kontrolować typ linii łamanej. Właściwość polylineEncoding określa, czy linia łamana będzie kodowana jako ENCODED_POLYLINE (domyślnie), co oznacza, że będzie używany format algorytmu kodowania linii łamanych, czy jako GEO_JSON_LINESTRING, co oznacza, że będzie używany format GeoJSON LineString.
Na przykład w treści żądania:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE", "polylineEncoding": "ENCODED_POLYLINE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Konfigurowanie jakości linii łamanej
polylineQuality określa jakość polilinii jako HIGH_QUALITY lub OVERVIEW (domyślnie). W przypadku OVERVIEW polilinia składa się z niewielkiej liczby punktów i ma mniejsze opóźnienie żądania niż HIGH_QUALITY.
Na przykład w treści żądania:
{ "origin":{ "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0827784 } } }, "destination":{ "location":{ "latLng":{ "latitude": 37.417670, "longitude": -122.079595 } } }, "travelMode": "DRIVE", "routingPreference": "TRAFFIC_AWARE", "polylineQuality": "HIGH_QUALITY", "polylineEncoding": "ENCODED_POLYLINE", "departureTime": "2023-10-15T15:01:23.045123456Z", ... }
Wysyłanie prośby o linię łamaną uwzględniającą ruch
Wszystkie przykłady powyżej zwracają podstawowe linie łamane, czyli linie łamane bez informacji o ruchu. Możesz też poprosić, aby linia łamana zawierała informacje o ruchu na trasie i na każdym jej odcinku.
Linie łamane uwzględniające natężenie ruchu zawierają informacje o warunkach na drodze na trasie. Warunki na drogach są wyrażane w kategoriach prędkości (NORMAL, SLOW, TRAFFIC_JAM) dla danego przedziału linii łamanej odpowiedzi.
Przedziały są definiowane przez indeksy punktów linii łamanej, które wyznaczają ich początek (włącznie) i koniec (wyłącznie).
Na przykład ta odpowiedź pokazuje NORMAL ruch między punktami 2 i 4 linii łamanej:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Aby przesłać żądanie obliczenia linii łamanej uwzględniającej ruch, ustaw w nim te właściwości:
Ustaw pole tablicy
extraComputationsnaTRAFFIC_ON_POLYLINE, aby włączyć obliczanie ruchu.Ustaw wartość
travelModenaDRIVElubTWO_WHEELER. Żądania dotyczące innych środków transportu zwracają błąd.W żądaniu określ preferencję routingu
TRAFFIC_AWARElubTRAFFIC_AWARE_OPTIMAL. Więcej informacji znajdziesz w artykule Konfigurowanie jakości a opóźnienia.Ustaw maskę pola odpowiedzi, która określa, że mają być zwracane właściwości odpowiedzi:
Na poziomie trasy zwracaj w odpowiedzi wszystkie informacje o podróży, uwzględniając w masce pola odpowiedzi wartość
routes.travelAdvisory. Aby zwrócić tylko informacje o natężeniu ruchu, podajroutes.travelAdvisory.speedReadingIntervalsNa poziomie odcinka zwróć w odpowiedzi wszystkie informacje o podróży dla każdego odcinka trasy, uwzględniając
routes.legs.travelAdvisory. Aby zwrócić tylko informacje o natężeniu ruchu, określroutes.legs.travelAdvisory.speedReadingIntervals.
curl -X POST -d '{
"origin":{
"address": "1600 Amphitheatre Parkway, Mountain View, CA"
},
"destination":{
"address": "24 Willie Mays Plaza, San Francisco, CA 94107"
},
"travelMode": "DRIVE",
"extraComputations": ["TRAFFIC_ON_POLYLINE"],
"routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \
'https://routes.googleapis.com/directions/v2:computeRoutes'Przykładowa odpowiedź dla linii łamanej uwzględniającej ruch
W odpowiedzi dane o ruchu są zakodowane w polilinii i zawarte w polu travelAdvisory typu RouteLegTravelAdvisory (każdy odcinek) i RouteTravelAdvisory (trasa).
Na przykład:
{
"routes": [
{
"legs": {
"polyline": {
"encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
},
// Traffic data for the leg.
"travelAdvisory": {
"speedReadingIntervals": [
{
"endPolylinePointIndex": 1,
"speed": "NORMAL"
},
{
"startPolylinePointIndex": 1,
"endPolylinePointIndex": 2,
"speed": "SLOW"
},
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
]
}
},
"polyline": {
"encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
},
// Traffic data for the route.
"travelAdvisory": {
"speedReadingIntervals": [
{
"endPolylinePointIndex": 1,
"speed": "NORMAL"
},
{
"startPolylinePointIndex": 1,
"endPolylinePointIndex": 2,
"speed": "SLOW"
},
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
]
}
}
]
}
Zarówno RouteTravelAdvisory, jak i RouteLegTravelAdvisory zawierają pole tablicy o nazwie speedReadingIntervals, które zawiera informacje o prędkości w ruchu drogowym. Każdy obiekt w tablicy jest reprezentowany przez obiekt SpeedReadingInterval (REST) lub SpeedReadingInterval (gRPC).
Obiekt SpeedReadingInterval zawiera odczyt prędkości dla przedziału trasy, np. NORMAL, SLOW lub TRAFFIC_JAM. Cała tablica obiektów obejmuje całą polilinię trasy bez nakładania się. Punkt początkowy określonego przedziału jest taki sam jak punkt końcowy poprzedniego przedziału.
Każdy przedział jest opisany przez startPolylinePointIndex, endPolylinePointIndex i odpowiednią kategorię prędkości. Zwróć uwagę, że brak indeksu początkowego w przedziale odpowiada indeksowi 0 zgodnie z zasadami proto3.
Wartości startPolylinePointIndex i endPolylinePointIndex nie zawsze są kolejne. Na przykład:
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
W tym przypadku warunki ruchu były takie same od indeksu 2 do indeksu 4.
Renderowanie linii łamanych uwzględniających ruch drogowy za pomocą pakietu Maps SDK
Zalecamy wyświetlanie na mapie linii łamanych uwzględniających ruch drogowy za pomocą różnych funkcji oferowanych przez pakiety SDK Map Google, w tym niestandardowych kolorów, obrysów i wzorów wzdłuż odcinków linii łamanej. Więcej informacji o korzystaniu z polilinii znajdziesz w artykułach Funkcje polilinii na Androida i Funkcje polilinii na iOS.
Przykładowe renderowanie linii łamanej
Użytkownicy pakietu Maps SDK mają możliwość zdefiniowania niestandardowej logiki mapowania między kategoriami prędkości a schematami renderowania linii łamanych. Na przykład prędkość „NORMALNA” może być wyświetlana na mapie jako gruba niebieska linia, a prędkość „WOLNA” – jako gruba pomarańczowa linia.
Poniższe fragmenty kodu dodają grubą niebieską polilinię z odcinkami geodezyjnymi z Melbourne do Perth. Więcej informacji znajdziesz w sekcjach Dostosowywanie wyglądu (Android) i Dostosowywanie polilinii (iOS).
Android
Java
Polyline line = map.addPolyline(new PolylineOptions() .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734)) .width(25) .color(Color.BLUE) .geodesic(true));
Kotlin
val line: Polyline = map.addPolyline( PolylineOptions() .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734)) .width(25f) .color(Color.BLUE) .geodesic(true) )
iOS
Objective-C
GMSMutablePath *path = [GMSMutablePath path]; [path addLatitude:-37.81319 longitude:144.96298]; [path addLatitude:-31.95285 longitude:115.85734]; GMSPolyline *polyline = [GMSPolyline polylineWithPath:path]; polyline.strokeWidth = 10.f; polyline.strokeColor = .blue; polyline.geodesic = YES; polyline.map = mapView;
Swift
let path = GMSMutablePath() path.addLatitude(-37.81319, longitude: 144.96298) path.addLatitude(-31.95285, longitude: 115.85734) let polyline = GMSPolyline(path: path) polyline.strokeWidth = 10.0 polyline.geodesic = true polyline.map = mapView
Używanie zakodowanych linii łamanych w przypadku wyszukiwania wzdłuż trasy
Użyj interfejsu Places API Text Search, aby wyszukiwać wzdłuż obliczonej trasy. Do żądania wyszukiwania tekstowego przekazujesz zakodowaną linię łamaną wstępnie obliczonej trasy z interfejsu Compute Routes API. Odpowiedź zawiera wtedy miejsca, które pasują do kryteriów wyszukiwania i znajdują się w pobliżu określonej trasy. Więcej informacji znajdziesz w artykule wyszukiwanie wzdłuż trasy.
Aby na przykład wyświetlić kawiarnie na trasie między miejscem wylotu a celem podróży:
Node.js
const API_KEY = 'YOUR_API_KEY'; const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes'; const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';function init(){ const routes_request = { "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }; const textSearch_request = { "textQuery": "cafe", "searchAlongRouteParameters": { "polyline": { "encodedPolyline": "" } } }; fetchResources(routes_service,routes_request).then(routes => { textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline; fetchResources(textSearch_service,textSearch_request).then(places => { console.log(places); }); }); } async function fetchResources(resource,reqBody){ const response = await fetch(resource, { method: 'POST', body: JSON.stringify(reqBody), headers: { 'Content-Type': 'application/json', 'X-Goog-Api-Key': API_KEY, 'X-Goog-FieldMask': '*' } }); const responseJSON = await response.json(); return responseJSON; } init();