Os métodos computeRoutes (REST) e ComputeRoutes (gRPC) retornam a rota representada por uma polilinha como parte da resposta. Essas APIs retornam dois tipos de polilinhas:
Polilinha básica (padrão): representa um trajeto, mas sem informações de trânsito incorporadas na polilinha. As solicitações que retornam uma polilinha básica são cobradas de acordo com a taxa básica do Routes. Saiba mais sobre o faturamento da API Routes.
Polilinha com reconhecimento de trânsito, que contém informações sobre as condições de trânsito ao longo do trajeto. As condições de trânsito são expressas em termos de categorias de velocidade (
NORMAL
,SLOW
,TRAFFIC_JAM
) aplicáveis em um determinado intervalo da polilinha. As solicitações de polilinhas com reconhecimento de tráfego são cobradas de acordo com a taxa do Routes Preferred. Saiba mais sobre o faturamento da API Routes. Para mais detalhes, consulte Configurar a qualidade da polilinha.
Para saber mais sobre polilinhas, consulte:
Com o utilitário interativo de codificação de polilinhas, você cria polilinhas codificadas em uma IU ou decodifica polilinhas para exibição em um mapa. Por exemplo, use esse utilitário para decodificar uma polilinha criada pelo código abaixo.
Solicitar uma polilinha básica para um trajeto, trecho ou etapa
Uma polilinha é representada por um objeto Polyline (REST) ou Polyline (gRPC). Você pode retornar uma polilinha na resposta no nível do trajeto, do trecho e da etapa.
Use a máscara do campo de resposta para especificar qual polilinha retornar:
No nível do trajeto, retorne uma polilinha na resposta incluindo
routes.polyline
na máscara do campo de resposta.No nível do trecho, retorne uma polilinha na resposta para cada trecho do trajeto incluindo
routes.legs.polyline
.No nível da etapa, retorne uma polilinha na resposta para cada etapa do trecho incluindo
routes.legs.steps.polyline
.
Por exemplo, para retornar uma polilinha para o trajeto inteiro, para cada trecho e para cada etapa de cada trecho:
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'
Essa solicitação retorna a seguinte resposta, que inclui a polilinha do trajeto, de cada trecho e de cada etapa do trecho:
{ "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_@@_@?" } } ] }
Como essa solicitação contém apenas uma origem e um destino, a rota retornada contém apenas um trecho. Portanto, a polilinha do trecho e do trajeto é a mesma.
Se você adicionar um waypoint intermediário à solicitação, a rota retornada terá dois trechos:
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'
Essa solicitação retorna dois trechos, cada um com uma polilinha exclusiva e uma polilinha para todo o trajeto:
{ "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" } } ] }
Qualidade da polilinha
A qualidade de uma polilinha pode ser descrita nos seguintes termos:
A precisão de ponto flutuante dos pontos
Os pontos são especificados como valores de latitude e longitude, que são representados no formato de ponto flutuante de precisão única. Isso funciona bem para valores pequenos, que podem ser representados com precisão, mas a precisão diminui à medida que os valores aumentam devido a erros de arredondamento de ponto flutuante.
No método computeRoutes (REST) e ComputeRoutes, isso é controlado por
polylineEncoding
.O número de pontos que compõem a polilinha
Quanto mais pontos houver, mais suave será a polilinha (especialmente em curvas).
No método computeRoutes (REST) e ComputeRoutes, isso é controlado por
polylineQuality
.
Configurar o tipo de codificação da polilinha
Use a opção de solicitação polylineEncoding
para controlar o tipo de polilinha.
A propriedade polylineEncoding
controla se a polilinha será codificada como ENCODED_POLYLINE
(padrão), o que significa que o Formato do algoritmo de polilinhas codificadas será usado, ou GEO_JSON_LINESTRING
, que será usado no formato LineString GeoJSON.
Por exemplo, no corpo da solicitação:
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'
Configurar a qualidade da polilinha
polylineQuality
especifica a qualidade da polilinha como HIGH_QUALITY
ou OVERVIEW
(padrão). Com OVERVIEW
, a polilinha é composta usando um pequeno número de pontos e tem uma latência de solicitação menor do que HIGH_QUALITY
.
Por exemplo, no corpo da solicitação:
{ "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", ... }
Solicitar uma polilinha com reconhecimento de tráfego
Os exemplos mostrados acima retornam polilinhas básicas, ou seja, sem informações de trânsito. Além disso, você também pode solicitar que a polilinha contenha informações de trânsito para o trajeto e para cada trecho do trajeto.
As polilinhas com reconhecimento de trânsito contêm informações sobre as condições de trânsito ao longo do trajeto. As condições de trânsito são expressas em termos de categorias de velocidade (NORMAL
, SLOW
, TRAFFIC_JAM
) para um determinado intervalo da polilinha de resposta. Os intervalos são definidos pelos índices dos pontos de polilinha inicial (inclusivo) e final (exclusivo).
Por exemplo, a resposta a seguir mostra o tráfego NORMAL
entre os pontos 2 e 4 da polilinha:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Para fazer uma solicitação para calcular uma polilinha com reconhecimento de tráfego, defina as seguintes propriedades na solicitação:
Defina o campo de matriz
extraComputations
comoTRAFFIC_ON_POLYLINE
para ativar o cálculo de tráfego.Defina a
travelMode
comoDRIVE
ouTWO_WHEELER
. As solicitações de qualquer outro meio de transporte retornam um erro.Especifique a preferência de roteamento
TRAFFIC_AWARE
ouTRAFFIC_AWARE_OPTIMAL
na solicitação. Para mais informações, consulte Configurar qualidade e latência.Defina uma máscara de campo de resposta que especifique para retornar as propriedades da resposta:
No nível do trajeto, retorne todas as informações de viagem na resposta incluindo
routes.travelAdvisory
na máscara do campo de resposta. Para retornar apenas as informações de trânsito, especifiqueroutes.travelAdvisory.speedReadingIntervals
.No nível do trecho, retorne todas as informações de viagem na resposta para cada trecho do trajeto incluindo
routes.legs.travelAdvisory
. Para retornar apenas as informações de trânsito, especifiqueroutes.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'
Exemplo de resposta para uma polilinha com reconhecimento de tráfego
Na resposta, os dados de tráfego são codificados na polilinha e estão contidos no campo travelAdvisory
, do tipo objeto RouteLegTravelAdvisory (cada trecho) e RouteTravelAdvisory (rota).
Exemplo:
{ "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" } ] } } ] }
RouteTravelAdvisory
e RouteLegTravelAdvisory
incluem um campo de matriz chamado speedReadingIntervals
, que contém informações de velocidade do tráfego. Cada objeto na matriz é representado por um objeto SpeedReadingInterval (REST) ou SpeedReadingInterval (gRPC).
Um objeto SpeedReadingInterval
inclui a leitura de velocidade para um intervalo de trajeto, como NORMAL
, SLOW
ou TRAFFIC_JAM
. Toda a matriz de objetos abrange toda a polilinha do trajeto sem sobreposição. O ponto de início de um intervalo
especificado é o mesmo que o ponto final do intervalo anterior.
Cada intervalo é descrito por startPolylinePointIndex
,
endPolylinePointIndex
e pela categoria de velocidade correspondente.
Observe que a falta do índice inicial dentro do intervalo corresponde ao índice 0
de acordo com as
práticas do proto3.
Os valores startPolylinePointIndex
e endPolylinePointIndex
nem sempre são consecutivos. Exemplo:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Nesse caso, as condições de tráfego foram as mesmas do índice 2 ao índice 4.
Renderizar polilinhas com reconhecimento de tráfego usando o SDK do Maps
Recomendamos exibir polilinhas com reconhecimento de trânsito no mapa usando os vários recursos oferecidos pelos SDKs do Google Maps, incluindo cores, traços e padrões personalizados ao longo dos trechos de polilinha. Para mais detalhes sobre o uso de polilinhas, consulte Recursos de polilinhas para Android e Recursos de polilinhas para iOS.
Exemplo de renderização de polilinha
Os usuários do SDK do Maps têm a oportunidade de definir uma lógica de mapeamento personalizada entre as categorias de velocidade e os esquemas de renderização de polilinhas. Por exemplo, é possível mostrar a velocidade "NORMAL" como uma linha azul grossa no mapa, enquanto a velocidade "Lenta" pode ser exibida como uma linha laranja grossa, por exemplo.
Os snippets a seguir adicionam um polígono azul espesso com segmentos geodésicos de Melbourne a Perth. Para mais informações, consulte Como personalizar aparências (para Android) e Personalizar a polilinha (para 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