Esta página foi traduzida pela API Cloud Translation.

Solicitar polilinhas do trajeto

A codificação de polilinha é um algoritmo de compactação com perdas que permite armazenar uma série de coordenadas, como um trajeto, como uma única string. O processo de codificação converte um valor binário em uma série de códigos de caracteres para caracteres ASCII usando o esquema de codificação base64. Para uma descrição completa do processo de codificação, consulte Formato do algoritmo de polilinhas codificadas.

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 faturadas de acordo com a taxa do Routes Basic. Saiba mais sobre o faturamento da API Routes.
polilinha 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) aplicáveis a um determinado intervalo da polilinha. As solicitações de polilinhas com reconhecimento de tráfego são faturadas de acordo com a taxa preferencial do Routes. Saiba mais sobre o faturamento da API Routes. Saiba mais em Configurar a qualidade da polilinha.

Para saber mais sobre polilinhas, consulte:

Configure a qualidade vs. latência para informações sobre como configurar a qualidade da polilinha.
O formato de algoritmo de polilinhas codificadas descreve o algoritmo de codificação de uma polilinha.
O utilitário interativo de codificação de polilinhas permite criar polilinhas codificadas em uma IU 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 têm escape em JSON. Para exibir essas polilinhas no utilitário interativo de codificação de polilinhas, primeiro é necessário remover o escape delas. Há muitos utilitários disponíveis para realizar um unescape de JSON, como o Freeformatter.

Solicitar uma polilinha básica para um trajeto, trecho ou etapa

Uma polilinha é representada por um objeto polilinha (REST) ou polilinha (gRPC). Você pode retornar uma polilinha na resposta no nível do trajeto, trecho e 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.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.

Observação: cada trecho corresponde à viagem entre dois waypoints quando via é falso para que o waypoint indique uma parada no trajeto. Por exemplo, um trajeto sem waypoints intermediários tem apenas um trecho. Um trajeto que inclui um waypoint intermediário com uma parada tem dois trechos. Um trajeto que inclui um waypoint intermediário com via definido como verdadeiro tem um trecho.
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 passo 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 dele e 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 único trecho. Portanto, a polilinha do trecho e do trajeto são as mesmas.

Se você adicionar um waypoint intermediário à solicitação, o trajeto retornado 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 outra para o trajeto inteiro:

{
  "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"
      }
    }
  ]
}

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 especifica como codificar a polilinha como ENCODED_POLYLINE (padrão), o que significa usar o algoritmo de codificação de polilinha, ou GEO_JSON_LINESTRING, que significa usar o formato GeoJSON LineString.

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'

Solicitar uma polilinha sensível ao trânsito

Os exemplos mostrados acima retornam polilinhas básicas, ou seja, polilinhas sem informações sobre o 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 dele.

As polilinhas que reconhecem o 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 da polilinha inicial (inclusivos) e finais (exclusivos).

Por exemplo, a resposta a seguir mostra o tráfego NORMAL entre os pontos de polilinha 2 e 4:

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

Para fazer uma solicitação para calcular uma polilinha sensível ao 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 a travelMode como DRIVE ou TWO_WHEELER. Solicitações para qualquer outro meio 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 da resposta:
- No nível do trajeto, retorne todas as informações de viagem na resposta incluindo routes.travelAdvisory na máscara do campo correspondente. Para retornar apenas as informações de tráfego, especifique routes.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á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 polilinha sensível ao trânsito

Na resposta, os dados de tráfego são codificados na polilinha e contidos no campo travelAdvisory, do objeto RouteLegTravelAdvisory (cada trecho) e objeto RouteTravelAdvisory (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 de trânsito. Cada objeto na matriz é representado por um objeto SpeedReadingInterval (REST) ou SpeedReadingInterval (gRPC).

Um objeto SpeedReadingInterval inclui 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 é 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 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 foram as mesmas do índice 2 para o índice 4.

Renderizar polilinhas com informações de trânsito usando o SDK do Maps

Recomendamos exibir polilinhas de acordo com o 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 polilinha para Android e Recursos de polilinha para iOS.

Exemplo de renderização de polilinhas

Os usuários do SDK do Maps podem 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 "SLOW" pode aparecer como uma linha laranja grossa.

Os snippets a seguir adicionam uma polilinha azul grossa com segmentos geodésicos de Melbourne até 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