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

Solicita polilíneas de rutas

Los métodos computeRoutes (REST) y 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): representa una ruta, pero sin información sobre el tráfico incorporada en la polilínea. Las 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 adaptadas al tráfico, contienen información sobre el estado del tráfico en la ruta. Las condiciones del tráfico se expresan en términos de las categorías de velocidad (NORMAL, SLOW, TRAFFIC_JAM) aplicables a un intervalo determinado de la polilínea. Las solicitudes de polilíneas adaptadas al tráfico se facturan con la tarifa de Routes Preferred. Obtén más información sobre la facturación de la API de Routes. Para obtener más información, consulta Cómo configurar la calidad de las polilíneas.

Para obtener más información sobre las polilíneas, consulta lo siguiente:

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

Nota: Los caracteres especiales de las polilíneas que muestra la API de REST tienen caracteres de escape JSON. Para mostrar estas polilíneas en la utilidad de codificador de polilínea interactiva, primero debes quitarles el escape. Hay muchas utilidades disponibles para realizar un escape de JSON, como Freeformatter.

Cómo solicitar una polilínea básica para una ruta, una etapa 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 se debe devolver 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 tramo, muestra una polilínea en la respuesta para cada tramo de la ruta incluyendo routes.legs.polyline.

Nota: Cada tramo corresponde al viaje entre dos puntos de referencia cuando el valor de 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 segmentos. Una ruta que incluye un punto de referencia intermedio con el via establecido en verdadero tiene un segmento.
En el nivel del paso, muestra una polilínea en la respuesta para cada paso del segmento incluyendo routes.legs.steps.polyline.

Por ejemplo, para mostrar una polilínea correspondiente a toda la ruta, a cada segmento y a cada paso de cada segmento, 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"
}' \
-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 muestra la siguiente respuesta, que incluye la polilínea para la ruta, para cada segmento de la ruta y para cada paso de la etapa:

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

Debido a que esta solicitud solo contiene un origen y un destino, la ruta que se muestra solo contiene un segmento. Por lo tanto, la polilínea para el tramo y la ruta es la misma.

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

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 muestra dos segmentos, cada uno con una polilínea única, y una polilínea para 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 los valores aumentan debido a errores de redondeo de punto flotante.

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

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

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

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 se usará el Formato del algoritmo de polilínea codificada, o GEO_JSON_LINESTRING, lo que significa que se usará el formato GeoJSON LineString.

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 o OVERVIEW (valor predeterminado). Con OVERVIEW, la polilínea se compone de una pequeña cantidad de puntos y tiene una latencia de solicitud más baja que HIGH_QUALITY.

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

{
  "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 adaptada al tráfico

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

Las polilíneas adaptadas al tráfico contienen información sobre el estado del tráfico en 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 polilínea de respuesta. Los intervalos se definen según los índices de sus puntos de polilínea inicial (inclusivo) y final (exclusivo).

Por ejemplo, en la siguiente respuesta, se muestra el tráfico NORMAL entre los puntos de polilínea 2 y 4:

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

Si deseas realizar una solicitud para calcular una polilínea adaptada al tráfico, configura las siguientes propiedades en la solicitud:

Establece el campo de array extraComputations en TRAFFIC_ON_POLYLINE para habilitar el cálculo del tráfico.
Establece travelMode en DRIVE o TWO_WHEELER. Las solicitudes para cualquier otro medio de viaje muestran un error.
Especifica la preferencia de enrutamiento TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL en la solicitud. Para obtener más información, consulta Cómo configurar la calidad en comparación con la 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, incluye routes.travelAdvisory en la máscara del campo de respuesta. Para mostrar solo la información del tráfico, especifica routes.travelAdvisory.speedReadingIntervals.
- A nivel del segmento, muestra toda la información de viaje en la respuesta para cada etapa de la ruta incluyendo routes.legs.travelAdvisory. Para mostrar solo la información del 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'

Respuesta de ejemplo para una polilínea adaptada al tráfico

En la respuesta, los datos de tráfico se codifican en la polilínea y se encuentran en el campo travelAdvisory, del tipo de objeto RouteLegTravelAdvisory (cada etapa) y en el 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. El array completo de objetos cubre toda la polilínea de la ruta sin superposición. El punto de inicio de un intervalo especificado es el mismo que el punto de finalización del intervalo anterior.

Cada intervalo se describe mediante sus startPolylinePointIndex, endPolylinePointIndex y la categoría de velocidad correspondiente. Ten en cuenta que la falta de índice de inicio dentro del intervalo corresponde al índice 0 de acuerdo con las 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 adaptadas al tráfico con el SDK de Maps

Te recomendamos que muestres en el mapa las polilíneas adaptadas al tráfico con las distintas funciones que ofrecen los SDK de Google Maps, incluidos los colores, los trazos y los patrones personalizados a lo largo de los estiramientos de las polilíneas. Para obtener más información sobre el uso de polilíneas, consulta Funciones de polilínea para Android y Funciones de polilínea 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, es posible que decidamos mostrar la velocidad "NORMAL" como una línea azul gruesa en el mapa, mientras que la velocidad "SLOW" se puede mostrar como una línea gruesa de color naranja.

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