Cómo especificar las ubicaciones de una ruta

Para calcular una ruta, debes especificar, como mínimo, las ubicaciones del origen y el destino de la ruta. Debes definir estas ubicaciones como puntos de referencia en la ruta.

Además de origen y destino, puedes especificar diferentes tipos de puntos de referencia y cómo manejarlos para una ruta. Para obtener más información y ejemplos, consulta los siguientes temas:

Cómo especificar ubicaciones para una ruta

Para representar una ubicación, debes crear un objeto Waypoint (REST) o Waypoint (gRPC). En la definición de punto de referencia, puedes especificar una ubicación de cualquiera de las siguientes maneras:

Puedes especificar ubicaciones para todos los puntos de referencia de una solicitud de la misma manera o puedes combinarlos. Por ejemplo, puedes usar coordenadas de latitud y longitud para el punto de referencia de origen y un ID de lugar para el punto de referencia de destino.

Para mayor eficiencia y precisión, usa los IDs de lugar en lugar de coordenadas de latitud y longitud o cadenas de direcciones. Los IDs de lugar son exclusivamente explícitos y proporcionan beneficios de geocodificación para el enrutamiento, como puntos de acceso y variables de tráfico. Ayudan a evitar las siguientes situaciones que pueden resultar de otras formas de especificar una ubicación:

  • El uso de coordenadas de latitud y longitud puede hacer que la ubicación se ajuste a la ruta más cercana a esas coordenadas, que podrían no ser un punto de acceso a la propiedad, o incluso una ruta que conduce de forma rápida o segura al destino.
  • La API de Routes debe geocodificar primero las strings de dirección para convertirlas en coordenadas de latitud y longitud antes de que se pueda calcular una ruta. Esta conversión puede afectar el rendimiento.

Cómo especificar una ubicación como un ID de lugar

Puedes usar un ID de lugar para especificar la ubicación de un punto de referencia. Debido a que las coordenadas de latitud y longitud se ajustan a las rutas, es posible que un ID de lugar ofrezca mejores resultados en algunas circunstancias.

Recupera IDs de lugar de la API de Geocoding y la API de Places (incluido Place Autocomplete). Para obtener más información sobre los IDs de lugar, consulta la descripción general de los IDs de lugar.

En el siguiente ejemplo, se usa la propiedad placeId para pasar un ID de lugar para origin y destination:

{
  "origin":{
    "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o"
  },
  "destination":{
    "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU"
  },
  ...
}

Cómo especificar una ubicación como coordenadas de latitud y longitud

Para definir la ubicación en un punto de referencia, especifica Location (REST) o Location(gRPC) mediante coordenadas de latitud y longitud.

Por ejemplo, especifica un punto de referencia para la ruta origin y destination con las coordenadas latitude y longitude:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
...
}

Especifica una ubicación como una cadena de dirección

Las cadenas de dirección son direcciones literales representadas por una cadena (como “1600 Amphitheatre Parkway, Mountain View, CA”). La geocodificación es el proceso de convertir una cadena de dirección en coordenadas de latitudes y longitudes (como la latitud 37.423021 y la longitud -122.083739).

Cuando pasas una cadena de dirección como la ubicación de un punto de referencia, la API de Routes geocodifica internamente la cadena para convertirla en coordenadas de latitud y longitud.

Por ejemplo, a fin de calcular una ruta, debes especificar un punto de referencia para la ruta origin y destination con strings de direcciones:

{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "450 Serra Mall, Stanford, CA 94305, USA"
  },
  ...
}

En este ejemplo, la API de Routes geocodifica ambas direcciones para convertirlas en coordenadas de latitud y longitud.

Si el valor de la dirección es ambiguo, la API de Routes puede invocar una búsqueda para desambiguar de direcciones similares. Por ejemplo, "1st Street" podría ser un valor completo o parcial para "1st Street NE" o "1st St SE". Este resultado puede ser diferente del que muestra la API de Geocoding. Para evitar posibles interpretaciones erróneas, usa los IDs de lugar.

Establece la región de la dirección.

Si pasas una cadena de dirección incompleta como la ubicación de un punto de referencia, la API podría usar coordenadas de latitud y longitud geocodificadas incorrectas. Por ejemplo, realizas una solicitud y especificas "Toledo" como el origen y "Madrid" como el destino para una ruta en automóvil:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE"
}

En este ejemplo, "Toledo" se interpreta como una ciudad en el estado de Ohio, en Estados Unidos, no en España. Por lo tanto, la solicitud muestra un array vacío, lo que significa que no existe ninguna ruta:

{
  []
}

Puedes configurar la API para que muestre resultados personalizados según una región en particular si incluyes el parámetro regionCode. Este parámetro especifica el código de región como un ccTLD ("dominio de nivel superior") de dos caracteres. La mayoría de los códigos de ccTLD son idénticos a los códigos ISO 3166-1, con algunas excepciones notables. Por ejemplo, el ccTLD del Reino Unido es "uk" (.co.uk), mientras que su código ISO 3166-1 es "gb" (técnicamente para la entidad del "Reino Unido de Gran Bretaña e Irlanda del Norte").

Una solicitud de instrucciones sobre cómo llegar de "Toledo" a "Madrid" que incluye el parámetro regionCode muestra los resultados adecuados porque "Toledo" se interpreta como una ciudad de España:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE",
  "regionCode": "es"
}

La respuesta ahora contiene la ruta calculada desde Toledo, España, hasta Madrid, España:

{
  "routes": [
    {
      "distanceMeters": 75330,
      "duration": "4137s",
      ...
    }
  ]
}

Especifica una ubicación como Plus Code

Muchas personas no tienen una dirección exacta, lo que puede dificultar la recepción de las entregas. O bien, es posible que las personas con una dirección prefieran aceptar entregas en ubicaciones más específicas, como una entrada trasera o una estación de carga.

Los Plus Codes son como las direcciones de las personas o los lugares que no tienen una dirección real. En lugar de direcciones con nombres de calles y números, los Plus Codes se basan en coordenadas de latitud y longitud, y se muestran como números y letras.

Google desarrolló los Plus Codes para brindar el beneficio de las direcciones a todo el mundo. Un Plus Code es una referencia de ubicación codificada, derivada de las coordenadas de latitud y longitud, que representa un área: 1/8,000 de un grado por 1/8,000 de un grado (alrededor de 14 m x 14 m en el ecuador) o menos. Puedes utilizar los Plus Codes como reemplazo de las direcciones en los lugares donde estas no existen, donde los edificios no están numerados o las calles no tienen nombre.

Los Plus Codes deben tener el formato de un código global o compuesto:

  • Un código global se compone de un código de área de 4 caracteres y de 6 caracteres o más código local.

    Por ejemplo, para la dirección "1600 Amphitheatre Parkway, Mountain View, CA", el código global es "849V" y el código local es "CWC8+R9". Luego, utiliza el Plus Code de 10 caracteres completo para especificar el valor de la ubicación como "849VCWC8+R9".

  • Un código compuesto se compone de un código local de 6 caracteres o más combinado con una ubicación explícita.

    Por ejemplo, la dirección "450 Serra Mall, Stanford, CA 94305, EE.UU." tiene el código local "CRHJ+C3". En el caso de una dirección compuesta, combina el código local con la parte de la ciudad, el estado, el código postal y el país de la dirección en el formato “CRHJ+C3 Stanford, CA 94305, EE.UU.”.

    Por ejemplo, calcula una ruta especificando un punto de referencia para la ruta origin y destination con los Plus Codes:

    {
  "origin":{
    "address": "849VCWC8+R9"
  },
  "destination":{
    "address": "CRHJ+C3 Stanford, CA 94305, USA"
  },
  "travelMode": "DRIVE"
}

Los Plus Codes son compatibles con las APIs de Google Maps Platform, incluidas Place Autocomplete, Place Details, la API de Directions y la API de Geocoding. Por ejemplo, puedes usar la API de Geocoding para aplicar la geocodificación inversa a una ubicación especificada por coordenadas de latitud y longitud, y así determinar el Plus Code de la ubicación.