Os métodos computeRoutes (REST) e o ComputeRoutes método (gRPC) retornam o trajeto representado 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. As solicitações que retornam uma polilinha básica são cobradas na taxa básica da API Routes. Saiba mais sobre o faturamento da API Routes.
Polilinha com informações 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) aplicáveis a um determinado intervalo da polilinha. As solicitações de polilinhas com informações de trânsito são cobradas na taxa preferencial da API Routes. Saiba mais sobre o faturamento da API Routes. Para mais detalhes, consulte Configurar a qualidade da polilinha.
Para mais informações sobre polilinhas, consulte:
O Utilitário interativo de codificação de polilinhas permite criar polilinhas codificadas em uma interface ou decodificar polilinhas para mostrar 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 Polyline (REST) ou Polyline (gRPC) objeto. É possível retornar uma polilinha na resposta no nível do trajeto, do trecho e da etapa.
Especifique qual polilinha retornar usando a máscara de campo de resposta :
No nível do trajeto: retorne uma polilinha na resposta incluindo
routes.polylinena máscara de 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 de trecho incluindo
routes.legs.steps.polyline.
Por exemplo, para retornar uma polilinha para todo o trajeto, 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, para cada trecho do trajeto e para 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, o trajeto retornado contém apenas um trecho. Portanto, a polilinha do trecho e do trajeto são iguais.
Se você adicionar um waypoint intermediário à solicitação, o trajeto retornado vai conter 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 usar pontos flutuantes dos pontos
Os pontos são especificados como valores de latitude e longitude, que são representados no formato de usar pontos flutuantes 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 usar pontos flutuantes.
Nos 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).
Nos computeRoutes (REST) e ComputeRoutes, isso é controlado por
polylineQuality.
Configurar o tipo de codificação de 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 polilinha codificada será usado, ou
GEO_JSON_LINESTRING, o que significa que o formato
GeoJSON LineString será usado.
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 informações de trânsito
Os exemplos mostrados acima retornam polilinhas básicas, ou seja, polilinhas sem informações de trânsito. Além disso, também é possível solicitar que a polilinha contenha informações de trânsito para o trajeto e para cada trecho do trajeto.
As polilinhas com informações 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ânsito NORMAL entre os pontos de polilinha 2 e 4:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Para fazer uma solicitação para calcular uma polilinha com informações de trânsito, defina as seguintes propriedades na solicitação:
Defina o campo da matriz
extraComputationscomoTRAFFIC_ON_POLYLINEpara ativar o cálculo de trânsito.Defina o
travelModecomoDRIVEouTWO_WHEELER. As solicitações de qualquer outro modo de viagem retornam um erro.Especifique a preferência de roteamento
TRAFFIC_AWAREouTRAFFIC_AWARE_OPTIMALna solicitação. Para mais informações, consulte Configurar qualidade versus latência.Defina uma máscara de campo de resposta que especifique o retorno das propriedades de resposta:
No nível do trajeto: retorne todas as informações de viagem na resposta incluindo
routes.travelAdvisoryna máscara de 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 informações de trânsito
Na resposta, as informações de trânsito são codificadas na polilinha e estão contidas no
travelAdvisory campo, do tipo
RouteLegTravelAdvisory
objeto (cada trecho) e
RouteTravelAdvisory objeto (trajeto).
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ânsito. Cada
objeto na matriz é representado por um
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 inicial de um intervalo especificado é o mesmo que o endpoint do intervalo anterior.
Cada intervalo é descrito por startPolylinePointIndex, endPolylinePointIndex e a categoria de velocidade correspondente. A ausência de índice inicial no 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ânsito eram as mesmas do índice 2 ao 4.
Renderizar polilinhas com informações de trânsito usando o SDK do Maps
Recomendamos mostrar polilinhas com informações 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 da 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 espessa no mapa, enquanto a velocidade "SLOW" pode ser mostrada como uma linha laranja espessa.
Os snippets a seguir adicionam uma polilinha azul espessa com segmentos geodésicos de Melbourne a Perth. Para mais informações, consulte 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
Usar polilinhas codificadas com a Pesquisa ao longo do trajeto
Use a Pesquisa de texto da API Places para pesquisar ao longo de uma rota calculada. Transmita a polilinha codificada de um trajeto pré-calculado da API Routes Compute Routes para a solicitação de Text Search. A resposta contém lugares que correspondem aos critérios de pesquisa e também estão localizados perto do trajeto especificado. Para mais detalhes, consulte Pesquisar ao longo de um trajeto.
Por exemplo, para retornar cafés ao longo do trajeto entre a origem e o destino:
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();