Esta página foi traduzida pela API Cloud Translation.

Solicitar polilinhas do trajeto

O método computeRoutes (REST) e o método 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 uma rota, mas sem informações de trânsito incorporadas à polilinha. As solicitações que retornam uma poligonal básica são cobradas na tarifa básica de rotas. 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 poligonal. As solicitações de polilinhas com informações de trânsito são cobradas na tarifa Preferida de rotas. Saiba mais sobre o faturamento da API Routes. Para saber mais, consulte Configurar a qualidade da poligonal.

Para saber mais sobre polilinhas, consulte:

Informações conceituais sobre polilinhas
O Utilitário interativo de codificação de polilinhas permite criar polilinhas codificadas em uma interface ou decodificar polilinhas para exibição em um mapa. Por exemplo, use esse utilitário para decodificar uma polilinha criada pelo código abaixo.

Observação: caracteres especiais nas polilinhas retornadas pela API REST são codificados em JSON. Para mostrar essas polilinhas no Utilitário interativo de codificação de polilinhas, primeiro é necessário remover a codificação. Há muitos utilitários disponíveis para realizar uma decodificação JSON, como o Freeformatter.

Solicitar uma poligonal básica para uma rota, etapa ou etapa parcial

Uma polilinha é representada por um objeto Polyline (REST) ou Polyline (gRPC). Você pode retornar uma polilinha na resposta no nível da rota, do trecho e da etapa.

Especifique qual polilinha será retornada usando a máscara de campo de resposta:

No nível da rota, retorne uma poligonal na resposta incluindo routes.polyline na máscara de campo de resposta.
No nível do trecho, inclua routes.legs.polyline para retornar uma polilinha na resposta de cada trecho da rota.

Observação: cada trecho corresponde à viagem entre dois waypoints quando via é falso para que o waypoint indique uma parada no trajeto. Por exemplo, uma rota sem pontos de referência intermediários tem apenas um trecho. Uma rota que inclui um ponto de passagem intermediário com uma parada tem dois trechos. Uma rota que inclui um ponto de referência intermediário com via definido como verdadeiro tem um trecho.
No nível da etapa, retorne uma polilinha na resposta para cada etapa da etapa do percurso 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 poligonal para a rota, para cada trecho da rota 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, a rota retornada contém apenas uma perna. Portanto, a polilinha do trecho e da rota são as mesmas.

Se você adicionar um ponto de passagem intermediário à solicitação, o trajeto retornado 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 poligonal 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 em ComputeRoutes, isso é controlado por polylineEncoding.
O número de pontos que compõem a polilinha

Quanto mais pontos houver, mais suave será a poligonal (especialmente em curvas).

No método computeRoutes (REST) e em 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 poligonal. 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 de string de linha GeoJSON 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 poligonal 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 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áfego. Além disso, você também pode solicitar que a poligonal contenha informações de tráfego para o trajeto e para cada trecho dele.

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áfego são expressas em termos de categorias de velocidade (NORMAL, SLOW, TRAFFIC_JAM) para um determinado intervalo da poligonal 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 poligonal:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

Para fazer uma solicitação e calcular uma polilinha ciente do tráfego, defina as seguintes propriedades na solicitação:

Defina o campo de matriz extraComputations como TRAFFIC_ON_POLYLINE para ativar o cálculo de tráfego.
Defina travelMode como DRIVE ou TWO_WHEELER. As solicitações de qualquer outro modo de transporte retornam um erro.
Especifique a preferência de roteamento TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL na solicitação. Para mais informações, consulte Configurar qualidade x latência.
Defina uma máscara de campo de resposta que especifique o retorno das propriedades de resposta:
- No nível da rota, retorne todas as informações de viagem na resposta, incluindo routes.travelAdvisory na máscara de campo de resposta. Para retornar apenas as informações de tráfego, especifique routes.travelAdvisory.speedReadingIntervals.
- No nível do trecho, inclua routes.legs.travelAdvisory para retornar todas as informações de viagem na resposta de cada trecho do trajeto. Para retornar apenas as informações de tráfego, especifique routes.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 poligonal ciente do trânsito

Na resposta, os dados de tráfego são codificados na polilinha e contidos no campo travelAdvisory, do tipo de 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 sobre a 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 rota, como NORMAL, SLOW ou TRAFFIC_JAM. A matriz inteira de objetos abrange toda a polilinha do trajeto sem sobreposição. O ponto de início de um intervalo especificado é igual ao ponto final do intervalo anterior.

Cada intervalo é descrito pelo startPolylinePointIndex, endPolylinePointIndex e pela categoria de velocidade correspondente. Observe que a falta de um índice de início 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áfego foram as mesmas do índice 2 ao 4.

Renderizar polilinhas com informações de tráfego com o SDK do Maps

Recomendamos mostrar polilinhas com informações de tráfego 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 polilinha para Android e Recursos de polilinha 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 polilinha. Por exemplo, é possível mostrar a velocidade "NORMAL" como uma linha azul grossa no mapa, enquanto a velocidade "LENTA" pode ser mostrada como uma linha laranja grossa.

Os snippets a seguir adicionam uma polilinha azul grossa com segmentos geodésicos de Melbourne a Perth. Para mais informações, consulte Como personalizar a aparência (para Android) e Personalizar a poligonal (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