Se usó la API de Cloud Translation para traducir esta página.

Solicita polilíneas de rutas

El método computeRoutes (REST) y el método ComputeRoutes (gRPC) muestran la ruta representada por una polilínea como parte de la respuesta. Estas APIs devuelven dos tipos de polilíneas:

Polilínea básica (predeterminada), que representa una ruta, pero sin tráfico información incorporada en la polilínea. Solicitudes que muestran una polilínea básica se facturan con la tarifa básica de Routes. Obtén más información sobre la facturación de la API de Routes.
Polilíneas con información sobre el tráfico: Contienen información sobre las condiciones de tráfico a lo largo de la ruta. Las condiciones de tráfico se expresan en términos de categorías de velocidad (NORMAL, SLOW, TRAFFIC_JAM) aplicables en un intervalo determinado del polilinea. Las solicitudes de polilíneas adaptadas al tráfico se facturan a la(s) Tarifa preferida de las rutas. Más información sobre la facturación de API de Routes. Para obtener más información, consulta Cómo configurar la calidad de los polilineas.

Para obtener más información sobre los polilíneas, consulta los siguientes recursos:

Información conceptual sobre polilíneas
Utilidad codificadora de polilínea interactiva te permite crear polilíneas codificadas en una IU o decodificar polilíneas para mostrarlas un mapa. Por ejemplo, usa esta utilidad para decodificar una polilínea creada por el siguiente código.

Nota: Los caracteres especiales en los polilíneas que muestra la API de REST están escapados de JSON. Para mostrar estas polilíneas en la Utilidad codificadora de polilínea interactiva, primero debes quitarles la barra de escape. Hay muchas utilidades disponibles para realizar una desescape de JSON, como Freeformatter.

Solicita una polilínea básica para una ruta, un tramo o un paso

Una polilínea se representa con un objeto Polyline (REST) o Polyline (gRPC). Puedes mostrar una polilínea en la respuesta a nivel de la ruta, el tramo y el paso.

Especifica qué polilínea mostrar con la máscara de campo de respuesta:

A nivel de la ruta, muestra una polilínea en la respuesta incluyendo routes.polyline en la máscara del campo de respuesta.
A nivel del segmento, muestra una polilínea en la respuesta para cada etapa del ruta incluyendo routes.legs.polyline.

Nota: Cada tramo corresponde al viaje entre dos puntos de referencia cuando via es falso para que el punto de referencia indique una parada en la ruta. Por ejemplo, una ruta sin puntos de referencia intermedios tiene solo una etapa. Una ruta que incluye un punto de referencia intermedio con una parada tiene dos tramos. Una ruta que incluye un punto de referencia intermedio con via establecido como verdadero tiene una etapa.
En el nivel del paso, muestra una polilínea en la respuesta para cada paso de del segmento incluyendo routes.legs.steps.polyline.

Por ejemplo, para devolver una polilínea para toda la ruta, para cada tramo y para cada paso de cada etapa:

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'

Esta solicitud devuelve la siguiente respuesta, que incluye la polilínea para el ruta, para cada tramo de la ruta y para cada paso del tramo:

{
  "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 esta solicitud solo contiene un origen y un destino, la ruta que se muestra solo contiene un tramo. Por lo tanto, la polilínea de la etapa y la de la ruta son las mismas.

Si agregas un punto de referencia intermedio a la solicitud, la ruta que se muestra contiene dos tramos:

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'

Esta solicitud devuelve dos segmentos, cada uno con una polilínea única, y una polilínea toda la ruta:

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

Calidad de las polilíneas

La calidad de una polilínea se puede describir de la siguiente manera:

La precisión de punto flotante de los puntos

Los puntos se especifican como valores de latitud y longitud, que se representan en formato de punto flotante de precisión simple. Esto funciona bien para valores pequeños (que se pueden representar con precisión), pero la precisión disminuye a medida que aumentan los valores debido a los errores de redondeo de punto flotante.

En el método computeRoutes (REST) y ComputeRoutes, esto se controla con polylineEncoding.
La cantidad de puntos que conforman la polilínea

Cuantos más puntos haya, más suave será la polilínea (especialmente en ).

En el método computeRoutes (REST) y ComputeRoutes, esto se controla con polylineQuality.

Cómo configurar el tipo de codificación de polilínea

Usa la opción de solicitud polylineEncoding para controlar el tipo de polilínea. La propiedad polylineEncoding controla si la polilínea se codificará como ENCODED_POLYLINE (predeterminado), lo que significa que Formato del algoritmo de polilínea codificada se usará, o GEO_JSON_LINESTRING, lo que significa que Formato LineString de GeoJSON que se usará.

Por ejemplo, en el cuerpo de la solicitud, haz lo siguiente:

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'

Cómo configurar la calidad de las polilíneas

polylineQuality especifica la calidad de la polilínea como HIGH_QUALITY. OVERVIEW (predeterminado). Con OVERVIEW, la polilínea se compone de una pequeña y tiene una latencia de solicitud menor que HIGH_QUALITY.

Por ejemplo, en el cuerpo de la solicitud:

{
  "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",
  ...
}

Cómo solicitar una polilínea que tenga en cuenta el tráfico

En los ejemplos anteriores, se devuelven polilíneas básicas; es decir, polilíneas sin información sobre el tráfico. Además, también puedes solicitar que el polilinea contenga información de tráfico para la ruta y para cada tramo de la ruta.

Las polilíneas con información sobre el tráfico contienen información sobre las condiciones del tráfico a lo largo de la ruta. Las condiciones del tráfico se expresan en términos de categorías de velocidad (NORMAL, SLOW, TRAFFIC_JAM) para un intervalo determinado de la respuesta polilínea. Los intervalos se definen según los índices de su inicio (inclusive) y finalizando (exclusivo) los puntos de polilínea.

Por ejemplo, la siguiente respuesta muestra el tráfico de NORMAL entre los puntos 2 y 4 del polilinea:

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

Para realizar una solicitud para calcular un polilínea que tenga en cuenta el tráfico, establece las siguientes propiedades en la solicitud:

Establece el campo del array extraComputations como TRAFFIC_ON_POLYLINE para habilitar el cálculo del tráfico.
Establece travelMode como DRIVE o TWO_WHEELER. Las solicitudes de cualquier otro modo de viaje muestran un error.
Especifica el enrutamiento TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL preferencia en la solicitud. Para obtener más información, consulta Cómo configurar la calidad latencia.
Establece una máscara de campo de respuesta que especifique que se deben mostrar las propiedades de la respuesta:
- A nivel de la ruta, muestra toda la información de viaje en la respuesta. Para ello, haz lo siguiente: incluido routes.travelAdvisory en la máscara de campo de respuesta. Para mostrar solo la información de tráfico, especifica routes.travelAdvisory.speedReadingIntervals.
- A nivel de la etapa, muestra toda la información de viaje en la respuesta para cada tramo de la ruta incluyendo routes.legs.travelAdvisory. Para mostrar solo la información de tráfico, especifica 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'

Ejemplo de respuesta para una polilínea que tiene en cuenta el tráfico

En la respuesta, los datos de tráfico se codifican en la polilínea y se contienen en el campo travelAdvisory, de tipo objeto RouteLegTravelAdvisory (cada tramo) y objeto RouteTravelAdvisory (ruta).

Por ejemplo:

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

Tanto RouteTravelAdvisory como RouteLegTravelAdvisory incluyen un campo de array llamado speedReadingIntervals que contiene información sobre la velocidad del tráfico. Cada objeto del array está representado por un objeto SpeedReadingInterval (REST) o SpeedReadingInterval (gRPC).

Un objeto SpeedReadingInterval incluye la lectura de velocidad para un intervalo de ruta, como NORMAL, SLOW o TRAFFIC_JAM. Todo el array de objetos cubre toda la polilínea de la ruta sin superponerse. El punto de inicio de un intervalo especificado es el mismo que el punto final del intervalo anterior.

Cada intervalo se describe mediante su startPolylinePointIndex, endPolylinePointIndex y la categoría de velocidad correspondiente. Observa que la falta de índice de inicio dentro del intervalo corresponde al índice 0. de acuerdo con el Prácticas de proto3.

Los valores startPolylinePointIndex y endPolylinePointIndex no siempre son consecutivos. Por ejemplo:

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

En este caso, las condiciones de tráfico fueron las mismas del índice 2 al 4.

Renderiza polilíneas que tengan en cuenta el tráfico con el SDK de Maps

Te recomendamos que muestres las polilíneas que reconocen el tráfico en el mapa usando las diversas características que ofrecen los SDK de Google Maps, incluidos los colores personalizados, los trazos y a lo largo de los estiramientos de la polilínea. Para obtener más información sobre el uso de polilíneas, ver Funciones de polilínea para Android y Características de polilíneas para iOS.

Ejemplo de renderización de polilínea

Los usuarios del SDK de Maps tienen la oportunidad de definir una lógica de asignación personalizada entre las categorías de velocidad y los esquemas de renderización de polilíneas. Por ejemplo, se podría decidir mostrar la velocidad "NORMAL" como una línea azul gruesa en el mapa, mientras que la velocidad "LENTA" podría mostrarse como una línea naranja gruesa.

En los siguientes fragmentos, se agrega una polilínea azul gruesa con segmentos geodésicos desde Melbourne hasta Perth. Para obtener más información, consulta Cómo personalizar los aspectos (para Android) y Cómo personalizar la polilínea (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