Servicios web del API de Google Maps

El API de rutas de Google

  1. Introducción
  2. Destinatarios
  3. Límites
  4. Solicitudes de rutas
    1. Parámetros de solicitud
    2. Medios de transporte
    3. Cómo usar hitos en las rutas
    4. Restricciones de vías
    5. Sistemas de unidades
    6. Cómo especificar la región
  5. Respuestas de rutas
    1. Salida JSON
    2. Salida XML
    3. Elementos de las respuestas de rutas

Si vas a utilizar este servicio en una aplicación de JavaScript, consulta la documentación de la clase DirectionsService de la versión 3 del API de Google Maps.

Introducción

El API de rutas de Google es un servicio que utiliza una solicitud HTTP para calcular rutas para llegar de una ubicación a otra. Puedes buscar rutas de varios métodos de transporte, como en transporte público, en coche, a pie o en bicicleta. Las rutas pueden especificar los orígenes, los destinos y los hitos como cadenas de texto (por ejemplo, "Chicago, IL" o "Darwin, NT, Australia") o como coordenadas de latitud/longitud. El API de rutas puede devolver rutas segmentadas mediante una serie de hitos.

Por lo general, este servicio está diseñado para calcular rutas a partir de direcciones estáticas (conocidas previamente) para la ubicación del contenido de la aplicación en un mapa. Sin embargo, este servicio no está diseñado para responder en tiempo real a la información introducida por el usuario, por ejemplo. Para calcular rutas dinámicas (por ejemplo, en un elemento de interfaz de usuario), consulta la documentación sobre el servicio de rutas de la versión 3 del API de JavaScript.

El cálculo de indicaciones es un proceso que consume mucho tiempo y muchos recursos. Siempre que sea posible, realiza un cálculo previo de las direcciones conocidas (mediante el servicio descrito) y almacena los resultados en una memoria caché temporal que tú mismo hayas diseñado.

Destinatarios

Este documento está dirigido a los desarrolladores de sitios web y de sitios para móviles que quieran utilizar datos de cómputo de rutas en los mapas proporcionados por una de las API de Google Maps. Ofrece una introducción al uso del API y material de referencia sobre los parámetros disponibles.

Límites de uso

El uso del API de rutas de Google está sujeto a un límite de 2.500 solicitudes de rutas al día. Todas las búsquedas de indicaciones contarán como una única solicitud respecto al límite diario cuando el modo de transporte es en coche, a pie o en bicicleta. La búsqueda de indicaciones en transporte público contará como cuatro solicitudes.

Las solicitudes individuales de indicaciones en coche, a pie o en bicicleta pueden contar como un máximo de ocho hitos intermedios en la solicitud. Para los clientes del API de Google Maps for Business, se admiten hasta 100.000 solicitudes de rutas al día (y cada una de ellas puede incluir hasta 23 hitos). Los hitos no están disponibles en las rutas de transporte público.

Ten en cuenta también que las URL del API de rutas de Google no pueden superar los 2.048 caracteres (antes de la codificación de URL). Dado que algunas URL del servicio de indicaciones pueden incluir varias ubicaciones a lo largo de una ruta, te recomendamos que tengas en cuenta este límite a la hora de crear tus URL.

Nota: el API de rutas solo se puede utilizar en combinación con la presentación de resultados en un mapa de Google. No se permite utilizar los datos del servicio de rutas sin mostrar un mapa correspondiente a los datos de rutas solicitados. Además, al calcular rutas se generan avisos sobre derechos de autor y advertencias que se deben mostrar al usuario de algún modo. Para obtener información detallada sobre el uso permitido, consulta las limitaciones de licencia de las condiciones de servicio del API de Google Maps.

Solicitudes de rutas

Una solicitud del API de rutas tiene el siguiente formato:

http://maps.googleapis.com/maps/api/directions/output?parameters

En esta solicitud, output debe ser uno de los valores que se indican a continuación:

  • json (recomendado) indica el formato de salida en Notación de objetos JavaScript (JavaScript Object Notation, JSON).
  • xml indica el formato de salida como un archivo XML.

Para acceder al API de rutas a través de HTTPS, utiliza la siguiente dirección:

https://maps.googleapis.com/maps/api/directions/output?parameters

Se recomienda utilizar HTTPS para aplicaciones que incluyan datos de usuario sensibles, como una ubicación de usuario, en las solicitudes.

Parámetros de solicitud

Algunos parámetros son obligatorios y otros opcionales. Como en las URL estándar, todos los parámetros se separan con el carácter &. A continuación, se indican los parámetros admitidos y sus posibles valores.

Parámetros obligatorios

  • origin: define la dirección o el valor de latitud/longitud textual de la ubicación desde la que quieras calcular las rutas. Si introduces la dirección como una cadena, el servicio de indicaciones codificará de forma geográfica la cadena para convertirla en coordenadas de latitud/longitud que permitan calcular las rutas. Si introduces coordenadas, asegúrate de que no haya espacios entre los valores de longitud y latitud.
  • destination: define la dirección o el valor de latitud/longitud textual de la ubicación desde la que quieras calcular las rutas. Si introduces la dirección como una cadena, el servicio de indicaciones codificará de forma geográfica la cadena para convertirla en coordenadas de latitud/longitud que permitan calcular las rutas. Si introduces coordenadas, asegúrate de que no haya espacios entre los valores de longitud y latitud.
  • sensor: indica si la solicitud de indicaciones procede de un dispositivo con un sensor de ubicación. Este valor debe ser true o false.

Los usuarios del API de Google Maps for Business deben incluir parámetros client y signature válidos junto con sus solicitudes de distancia. Para obtener más información, consulta el capítulo Servicios web del API de Google Maps for Business.

Parámetros opcionales

  • mode (el valor predeterminado es driving): especifica el medio de transporte que se utilizará al calcular las indicaciones. Los valores válidos se especifican en la sección Modos de viaje. Si estableces el modo a "transporte público", también debes especificar una hora de salida (departure_time) o una hora de llegada (arrival_time).
  • waypoints: especifica un conjunto de hitos. Para modificar una ruta, los hitos establecen las ubicaciones específicas por las que debe pasar. Es posible especificar un hito mediante coordenadas de latitud/longitud o como una dirección que se codificará de forma geográfica. Los hitos solo son válidos para las indicaciones en coche, a pie y en bicicleta. Para obtener más información sobre los hitos, consulta la sección Cómo usar hitos en las rutas que aparece a continuación.
  • alternatives: si se establece en true, indica que el servicio de rutas puede devolver más de una ruta alternativa. Ten en cuenta que la obtención de rutas alternativas puede incrementar el tiempo de respuesta del servidor.
  • avoid: indica que la ruta o las rutas calculadas deben evitar determinados elementos. A continuación, se indican los dos argumentos que admite actualmente este parámetro.
    • tolls indica que la ruta calculada debe evitar los peajes de carretera y de puentes.
    • highways indica que la ruta calculada debe evitar las autopistas y las autovías.
    Para obtener más información, consulta la sección Restricciones de vías que aparece a continuación.
  • units: especifica el sistema de unidades que se utilizará para mostrar los resultados. Los valores válidos se especifican en la sección Sistemas de unidades que aparece a continuación.
  • region: es el código de país, especificado como un valor de dos caracteres ccTLD ("dominio de nivel superior"). (Para obtener más información, consulta la sección Cómo especificar la región que aparece a continuación).
  • departure_time especifica la hora de salida que quieres para las indicaciones en trasporte público en segundos a partir de la medianoche del 1 de enero de 1970 UTC. Se debe especificar una hora de salida (departure_time) o una hora de llegada (arrival_time) al solicitar indicaciones en transporte público.
  • arrival_time especifica la hora de llegada que quieres para las indicaciones en trasporte público en segundos a partir de la medianoche del 1 de enero de 1970 UTC. Se debe especificar una hora de salida (departure_time) o una hora de llegada (arrival_time) al solicitar indicaciones en transporte público.

Los parámetros arrival_time y departure_time solo se aplican a las indicaciones en tránsito. Se debe especificar uno de estos parámetros cada vez que solicites indicaciones en transporte público.

Ejemplos de solicitudes de indicaciones

La siguiente solicitud permite obtener indicaciones de Toronto (Ontario) a Montreal (Quebec).

http://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&sensor=false

Al cambiar los parámetros mode y avoid, puedes modificar la solicitud inicial para que permita obtener indicaciones para un viaje panorámico en bicicleta que evite las principales autopistas.

http://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&sensor=false&avoid=highways&mode=bicycling

La siguiente solicitud permite buscar indicaciones en transporte público de Brooklyn (Nueva York) a Queens (Nueva York). Al solicitar indicaciones en transporte público, asegúrate de que especificar una hora de salida (departure_time) o de llegada (arrival_time). Ten en cuenta que, en este ejemplo, la hora de salida especificada es las 09:45 a.m. de 30 de julio de 2012. Actualiza el parámetro a un momento del futuro antes de enviar la solicitud.

http://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&sensor=false&departure_time=1343605500&mode=transit

Medios de transporte

Al calcular indicaciones, puedes especificar el mode de transporte que quieras utilizar. De forma predeterminada, las rutas se calculan como indicaciones para llegar en coche (driving). A continuación, se indican los modos de viaje que se admiten actualmente.

  • driving (predeterminado) proporciona rutas estándar para llegar en coche a través de la red de carreteras.
  • walking solicita rutas a pie a través de aceras y rutas peatonales (según disponibilidad).
  • bicycling solicita rutas para llegar en bicicleta a través de carriles bici y vías preferenciales para bicicletas (según disponibilidad).
  • transit solicita indicaciones a través de rutas de transporte público (según disponibilidad).

Nota: es posible que las rutas peatonales y para ciclistas no sean claras. En esos casos, aparecerán warnings en los resultados devueltos para las rutas sobre cómo llegar a pie o en bicicleta que deberás mostrar al usuario.

Cómo usar hitos en las rutas

Al calcular rutas mediante el API de rutas, también puedes especificar hitos para las indicaciones en coche, a pie o en bicicleta. Los hitos no están disponibles en las rutas de transporte público. Los hitos permiten calcular rutas que pasen por ubicaciones adicionales, de modo que la ruta devuelta atraviese hitos concretos.

Los hitos se especifican mediante el parámetro waypoints, que consta de una o varias direcciones o ubicaciones separadas por el carácter de plecas (|).

Por ejemplo, la siguiente URL inicia una solicitud para obtener una ruta de Boston (Massachusetts) a Concord (Massachusetts) que atraviese Charlestown y Lexington, en ese orden:

http://maps.googleapis.com/maps/api/directions/json?origin=Boston,MA&destination=Concord,MA&waypoints=Charlestown,MA|Lexington,MA&sensor=false

De forma predeterminada, el servicio de rutas calcula una ruta que atraviese los hitos especificados en el orden indicado. Opcionalmente, puedes introducir optimize:true como el primer argumento del parámetro waypoints, de manera que el servicio de rutas reordene los hitos de forma más eficaz para optimizar la ruta proporcionada. Esta optimización es el resultado de aplicar el Problema del viajante.

Si el servicio de rutas optimiza el orden de los hitos de acuerdo a tus instrucciones, se devolverá el nuevo orden en el campo waypoint_order del objeto routes. El campo waypoint_order devuelve valores basados en cero.

En el ejemplo que aparece a continuación, se calcula la ruta de un viaje por carretera desde Adelaida, en el sur de Australia, para recorrer las principales regiones vinícolas del sur de Australia mediante la optimización de rutas.

http://maps.googleapis.com/maps/api/directions/json?origin=Adelaide,SA&destination=Adelaide,SA&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA&sensor=false

Si se examina la ruta calculada, se puede ver que se han utilizado los hitos en el siguiente orden para calcularla:

"waypoint_order": [ 1, 0, 2, 3 ]

Restricciones

Es posible aplicar determinadas restricciones al cálculo de las rutas. Para indicar las restricciones, se puede utilizar el parámetro avoid y un argumento de ese parámetro que indique la restricción que se debe evitar. Actualmente, se admiten las dos restricciones siguientes:

  • avoid=tolls
  • avoid=highways

Nota: al añadir restricciones, no se impide que las rutas devueltas incluyan los elementos restringidos, sino que se modifica el resultado para mostrar rutas más favorables.

Sistemas de unidades

Los resultados del servicio de indicaciones contienen text en campos distance que se pueden mostrar cuando el usuario indique la distancia de un "paso" de la ruta. De forma predeterminada, este texto utiliza el sistema de unidades utilizado en la región o en el país de origen. (Nota: los orígenes expresados en coordenadas en lugar de mediante direcciones se convierten siempre en unidades métricas de forma predeterminada).

Por ejemplo, una ruta de "Chicago, IL" a "Toronto, ONT" mostrará los resultados en millas, mientras que la ruta inversa mostrará los resultados en kilómetros. Para anular este sistema de unidades predeterminado, basta con que definas en el parámetro units de la solicitud uno de ellos de forma explícita mediante cualquiera de los siguientes valores :

  • metric indica el uso del sistema métrico. Las distancias en formato textual se devuelven en kilómetros y en metros.
  • imperial indica el uso del sistema imperial (británico). Las distancias en formato textual se devuelven en millas y en pies.

Nota: este parámetro de sistema de unidades solo afecta al parámetro text que se muestra en los campos distance. Los campos distance también incluyen values, que siempre se expresan en metros.

Cómo especificar la región

También puedes especificar que el servicio de indicaciones devuelva resultados asociados a una región en concreto mediante el parámetro region. Este parámetro emplea un argumento ccTLD (dominio de nivel superior geográfico) que especifica la influencia de la región. La mayoría de los códigos de dominio de nivel superior son idénticos a los códigos ISO 3166-1, con algunas excepciones importantes. 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 de "Reino Unido de Gran Bretaña e Irlanda del Norte").

Puede utilizar cualquier dominio en el que la principal aplicación de Google Maps haya publicado indicaciones para llegar en coche.

Por ejemplo, una solicitud de rutas de "Toledo" a "Madrid" devuelve un resultado cuando region se establece en es, ya que "Toledo" se interpreta como la ciudad española:

http://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&region=es&sensor=false

{
  "status": "OK",
  "routes": [ {
    "summary": "AP-41",
    "legs": [ {
        ...
    } ],
    "copyrights": "Map data ©2010 Europa Technologies, Tele Atlas",
    "warnings": [ ],
    "waypoint_order": [ ]
  } ]
}

Por el contrario, una solicitud de rutas de "Toledo" a "Madrid" enviadas sin el parámetro region no devolverá ningún resultado, ya que "Toledo" se interpreta como la ciudad en Ohio (Estados Unidos):

http://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&sensor=false

{
  "status": "ZERO_RESULTS",
  "routes": [ ]
}

Respuestas de rutas

Las respuestas de ruta se devuelven en el formato que indica la marca de output en la ruta de la solicitud de la URL.

Resultado JSON

A continuación, se muestra un ejemplo de solicitud HTTP para calcular la ruta desde Chicago, IL a Los Ángeles, CA que atraviese dos hitos en Joplin, MO y en Oklahoma City, OK:

http://maps.googleapis.com/maps/api/directions/json?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&sensor=false

El resultado JSON se muestra a continuación. Dado que los resultados de rutas pueden ser muy ampulosos, los elementos que se repiten se han omitido por motivos de claridad.

{
  "status": "OK",
  "routes": [ {
    "summary": "I-40 W",
    "legs": [ {
      "steps": [ {
        "travel_mode": "DRIVING",
        "start_location": {
          "lat": 41.8507300,
          "lng": -87.6512600
        },
        "end_location": {
          "lat": 41.8525800,
          "lng": -87.6514100
        },
        "polyline": {
          "points": "a~l~Fjk~uOwHJy@P"
        },
        "duration": {
          "value": 19,
          "text": "1 min"
        },
        "html_instructions": "Head \u003cb\u003enorth\u003c/b\u003e on \u003cb\u003eS Morgan St\u003c/b\u003e toward \u003cb\u003eW Cermak Rd\u003c/b\u003e",
        "distance": {
          "value": 207,
          "text": "0.1 mi"
        }
      },
      ...
      ... additional steps of this leg
    ...
    ... additional legs of this route
      "duration": {
        "value": 74384,
        "text": "20 hours 40 mins"
      },
      "distance": {
        "value": 2137146,
        "text": "1,328 mi"
      },
      "start_location": {
        "lat": 35.4675602,
        "lng": -97.5164276
      },
      "end_location": {
        "lat": 34.0522342,
        "lng": -118.2436849
      },
      "start_address": "Oklahoma City, OK, USA",
      "end_address": "Los Angeles, CA, USA"
    } ],
    "copyrights": "Map data ©2010 Google, Sanborn",
    "overview_polyline": {
      "points": "a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\\~mbDzeVh_Wr|Efc\\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC"
    },
    "warnings": [ ],
    "waypoint_order": [ 0, 1 ],
    "bounds": {
      "southwest": {
        "lat": 34.0523600,
        "lng": -118.2435600
      },
      "northeast": {
        "lat": 41.8781100,
        "lng": -87.6297900
      }
    }
  } ]
}

Por lo general, solo se devuelve una entrada en el conjunto de "routes" para búsquedas de indicaciones. Sin embargo, es posible que el servicio de rutas devuelva varias rutas si transmites alternatives=true.

Ten en cuenta que, normalmente, estos resultados se deben analizar si quieres extraer valores de ellos. El análisis JSON es relativamente sencillo. Para ver algunos patrones de diseño recomendados, consulta la sección Análisis de JSON.

Resultado XML

En este ejemplo, el API de rutas solicita una respuesta xml para la consulta idéntica anterior.

http://maps.googleapis.com/maps/api/directions/xml?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&sensor=false

A continuación, se muestra la respuesta en formato XML a esta solicitud.

<DirectionsResponse>
 <status>OK</status>
 <route>
  <summary>I-40 W</summary>
  <leg>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>41.8507300</lat>
     <lng>-87.6512600</lng>
    </start_location>
    <end_location>
     <lat>41.8525800</lat>
     <lng>-87.6514100</lng>
    </end_location>
    <polyline>
     <points>a~l~Fjk~uOwHJy@P</points>
    </polyline>
    <duration>
     <value>19</value>
     <text>1 min</text>
    </duration>
    <html_instructions>Head <b>north</b> on <b>S Morgan St</b> toward <b>W Cermak Rd</b></html_instructions>
    <distance>
     <value>207</value>
     <text>0.1 mi</text>
    </distance>
   </step>
   ...
   ... additional steps of this leg
  ...
  ... additional legs of this route
   <duration>
    <value>74384</value>
    <text>20 hours 40 mins</text>
   </duration>
   <distance>
    <value>2137146</value>
    <text>1,328 mi</text>
   </distance>
   <start_location>
    <lat>35.4675602</lat>
    <lng>-97.5164276</lng>
   </start_location>
   <end_location>
    <lat>34.0522342</lat>
    <lng>-118.2436849</lng>
   </end_location>
   <start_address>Oklahoma City, OK, USA</start_address>
   <end_address>Los Angeles, CA, USA</end_address>
  <copyrights>Map data ©2010 Google, Sanborn</copyrights>
  <overview_polyline>
   <points>a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\~mbDzeVh_Wr|Efc\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC</points>
  </overview_polyline>
  <optimized_waypoint_index>0</optimized_waypoint_index>
  <optimized_waypoint_index>1</optimized_waypoint_index>
  <bounds>
   <southwest>
    <lat>34.0523600</lat>
    <lng>-118.2435600</lng>
   </southwest>
   <northeast>
    <lat>41.8781100</lat>
    <lng>-87.6297900</lng>
   </northeast>
  </bounds>
 </route>
</DirectionsResponse>

Ten en cuenta que la respuesta XML está formada por un único <DirectionsResponse> y por dos elementos de nivel superior:

  • <status> contiene los metadatos de la solicitud. Consulta la sección sobre códigos de estado que aparece a continuación.
  • Cero o más elementos <route> que contengan un conjunto único de información de las rutas entre el origen y el destino cada uno.

Te recomendamos que utilices json como la marca de salida preferida (a menos que tu servicio deba utilizar xml por cualquier motivo). Debes prestar atención al procesar árboles XML para asegurarte de hacer referencia a los elementos y nodos adecuados. Para ver algunos patrones de diseño recomendados para realizar el procesamiento de salida, consulta la sección sobre análisis de XML con XPath.

En el resto de esta documentación se utilizará la sintaxis JSON. En la mayoría de los casos, el formato de salida no es relevante para ilustrar conceptos o nombres de campos en la documentación. Sin embargo, debes tener en cuenta las siguientes diferencias sutiles:

  • Los resultados XML se incluyen en un elemento de respuestas <DirectionsResponse> raíz.
  • Los resultados JSON indican entradas con varios elementos mediante varios conjuntos (steps), mientras que los resultados XML lo hacen mediante varios elementos en singular (<step>).
  • Los elementos en blanco se muestran en forma de conjuntos vacíos en los resultados JSON, mientras que en los resultados XML están ausentes. Por ejemplo, una respuesta que no genera ningún resultado, devolverá una matriz routes vacía en JSON y ningún elemento <route> en XML.

Elementos de las respuestas de rutas

Las respuestas de rutas constan de los siguientes elementos raíces:

  • "status" contiene los metadatos de la solicitud. Consulta la sección sobre códigos de estado que aparece a continuación.
  • "routes" contiene un conjunto de rutas desde el origen al destino. Consulta la sección Rutas incluida a continuación.

Las rutas constan de Tramos y de Pasos anidados.

Códigos de estado

El campo "status" del objeto de respuesta de rutas contiene el estado de la solicitud y puede incluir información sobre depuración para ayudarte a descubrir el motivo por el que no funciona el servicio de rutas. El campo "status" puede contener los siguientes valores:

  • OK indica que la respuesta contiene un resultado (result) válido.
  • NOT_FOUND indica que al menos una de las ubicaciones especificadas en el origen, el destino o los hitos de la solicitud no se pudo codificar de forma geográfica.
  • ZERO_RESULTS indica que no se pudo encontrar ninguna ruta entre el origen y el destino.
  • MAX_WAYPOINTS_EXCEEDED indica que se proporcionaron demasiados hitos (waypoints) en la solicitud. El número máximo permitido para waypoints es 8, además del origen y del destino. Para los clientes del API de Google Maps for Business, se admiten consultas con un máximo de 23 hitos.
  • INVALID_REQUEST indica que la solicitud enviada no era válida.
  • OVER_QUERY_LIMIT indica que el servicio ha recibido demasiadas solicitudes de tu aplicación en el tiempo permitido.
  • REQUEST_DENIED indica que el servicio ha denegado el uso del servicio de rutas a tu aplicación.
  • UNKNOWN_ERROR indica que no se ha podido procesar una solicitud de rutas debido a un error del servidor. Puede que la solicitud se realice correctamente si lo intentas de nuevo.

Rutas

Cuando el API de rutas devuelve resultados, los ubica en un conjunto de routes (JSON). Aunque el servicio no devuelva ningún resultado (por ejemplo, si no existe la dirección), el API devolverá un conjunto de routes vacío. (las respuestas XML están formadas por cero o varios elementos <route>).

Cada elemento del conjunto de routes contiene un resultado único del origen y del destino especificados. Esta ruta puede constar de uno o varios legs, en función de los hitos que se hayan especificado. Además, la ruta también incluye información de derechos de autor y advertencias que se deben mostrar al usuario junto con la información de la ruta.

Cada ruta del campo routes puede contener los siguientes campos:

  • summary contiene una breve descripción textual sobre la ruta que permita identificarla y distinguirla de otras alternativas.
  • legs[] contiene un conjunto que consta de información sobre un tramo de la ruta comprendido entre dos ubicaciones de la ruta proporcionada. Se presentará un tramo diferente por cada hito o destino especificado (Una ruta sin hitos contendrá exactamente un tramo dentro del conjunto de legs). Cada tramo consta de una serie de pasos (steps). Para obtener más información, consulta la sección sobre tramos de rutas que aparece a continuación.
  • waypoint_order incluye un conjunto que indica el orden de los hitos de la ruta calculada. Estos hitos se pueden volver a ordenar si en la solicitud se transmitió optimize:true en el parámetro waypoints.
  • overview_polyline contiene un objeto que consta de un conjunto de puntos (points) codificados que representan una ruta aproximada (suavizada) de las indicaciones resultantes.
  • bounds contiene el cuadro delimitador de la ventana gráfica de esta ruta.
  • copyrights contiene el texto de los derechos de autor que se mostrará con la ruta. Debes encargarte directamente de la gestión y presentación de esta información.
  • warnings[] contiene un conjunto de advertencias que se visualizará cuando se muestren las rutas. Debes encargarte directamente de la gestión y presentación de estas advertencias.

Tramos

Cada elemento del conjunto de legs especifica un tramo único del trayecto desde el origen al destino de la ruta calculada. Las rutas que no contengan hitos constarán de un único "tramo", mientras que las rutas en las que se hayan definido uno o varios hitos constarán de uno o varios tramos correspondientes a los tramos específicos del trayecto.

Cada tramo del campo legs puede contener los siguientes campos:

  • steps[] contiene un conjunto de pasos que proporciona información sobre cada uno de los pasos del tramo de un trayecto. (Para obtener más información, consulta la sección sobre pasos de rutas que aparece a continuación).
  • distance es un campo que indica la distancia total que abarca el tramo y que consta de los siguientes elementos:

    • value indica la distancia en metros.
    • text contiene una representación interpretable por humanos de la distancia, expresada en las unidades utilizadas en el origen (o modificada en el parámetro units de la solicitud). (Por ejemplo, se utilizarán millas o pies para cualquier punto de origen que se encuentre dentro de Estados Unidos). Ten en cuenta que el campo distance.value siempre contendrá un valor expresado en metros, independientemente del sistema de unidad que se represente en el texto.

    Si no se conoce la distancia, es posible que estos campos no aparezcan.

  • duration es un campo que indica el tiempo total necesario para recorrer el tramo y que consta de los siguientes elementos:

    • value indica la duración en segundos.
    • text contiene una representación interpretable por humanos de la duración.

    Si no se conoce la duración, es posible que estos campos no aparezcan.

  • arrival_time contiene la hora estimada de llegada de este tramo. Esta propiedad solo se transmite para rutas de transporte público. El resultado se devuelve como un objeto Time con tres propiedades:
    • value: valor de tiempo especificado como objeto de fecha (Date) de JavaScript,
    • text: valor de tiempo especificado como cadena (el valor de tiempo se muestra en la zona correspondiente situada en la parte superior de la parada de transporte público),
    • time_zone contiene la zona donde se muestra el valor de tiempo de esta estación (el valor es el nombre de la zona donde se muestra el valor de tiempo, tal y como se define en la base de datos de zonas de tiempo de IANA, por ejemplo, "América/Nueva_York").
  • departure_time contiene la hora estimada de llegada de este tramo, especificada como un objeto Time. El elemento departure_time solo se transmite para rutas de transporte público.
  • start_location contiene las coordenadas de latitud/longitud del origen del tramo. Dado que el API de rutas utiliza la opción de transporte más cercana a los puntos de partida y de llegada (normalmente, carreteras) para calcular las rutas entre dos ubicaciones, es posible que el valor start_location no coincida con el origen del tramo si, por ejemplo, no hay carreteras cercanas al mismo.
  • end_location contiene las coordenadas de latitud/longitud del destino dado del tramo. Dado que el API de rutas utiliza la opción de transporte más cercana a los puntos de partida y de llegada (normalmente, carreteras) para calcular las rutas entre dos ubicaciones, es posible que el valor end_location no coincida con el destino del tramo si, por ejemplo, no hay carreteras cerca del mismo.
  • start_address contiene una dirección interpretable por humanos (normalmente una calle) que refleja el valor start_location de dicho tramo.
  • end_address contiene una dirección interpretable por humanos (normalmente una calle) que refleja el valor end_location de dicho tramo.

Pasos

Cada elemento del conjunto de steps define un paso único de las rutas calculadas. Un paso es la unidad más atómica de una ruta, que consta de un único paso que describe una instrucción específica y única del trayecto. Por ejemplo, "Gira a la izquierda en la calle W. 4th St.". Un paso no solo describe una instrucción, sino que también contiene información sobre la distancia y sobre el tiempo con respecto al paso siguiente. Por ejemplo, es posible que el paso etiquetado como "Tome la interestatal 80 oeste" especifique una duración de "60 kilómetros" y de "40 minutos" para indicar que el siguiente paso se encuentra a 60 kilómetros/40 minutos.

Cuando se utiliza el API de rutas para buscar rutas de transporte público, el conjunto de pasos incluye información de transporte público en forma de un conjunto transit_details. Si en las rutas se incluyen varios medios de transporte, se proporcionarán rutas detalladas para los pasos a pie y en coche en un conjunto sub_steps. Por ejemplo, un paso a pie incluirá rutas desde las ubicaciones de partida y de llegada: "Camina hasta la calle Innes Ave & Fitch St". Este paso incluirá rutas a pie detalladas para la ruta del conjunto sub_steps, por ejemplo: "Dirígete hacia el noroeste", "Gira a la izquierda en Arelious Walker" y "Gira a la izquierda en Innes Ave".

Cada paso del campo steps puede contener los siguientes campos:

  • html_instructions contiene instrucciones de formato para este paso, presentadas en forma de cadena de texto HTML.
  • distance contiene la distancia que hay que recorrer desde un paso hasta el siguiente. Para obtener más información sobre este campo, consulta la sección sobre tramos de rutas que aparece a continuación. Si no se conoce la distancia, es posible que este campo no esté definido.
  • duration contiene el tiempo normal necesario para realizar un paso antes de pasar al siguiente (consulta la descripción en la sección Tramos de rutas indicada a continuación). Si no se conoce la duración, es posible que este campo no esté definido.
  • start_location es un conjunto único de campos de lat y de lng que indica la ubicación del punto de partida de un paso determinado.
  • end_location es un conjunto único de campos de lat y de lng que indica la ubicación del punto de partida de un paso determinado.
  • sub_steps contiene indicaciones detalladas para ir a pie o indicaciones para ir en transporte público. Los subpasos solo están disponibles cuando travel_mode se establece en "transit". El conjunto sub_steps es del mismo tipo que steps.
  • transit_details contiene información específica del transporte público. Este campo solo se muestra cuando travel_mode se establece en "transit". Consulta la sección de Información de transporte público a continuación.

Detalles de transporte público

Las rutas de transporte público devuelven información adicional que no es relevante para otros medios de transporte. Estas propiedades adicionales se exponen a través del objeto transit_details, que se muestra como un campo de un elemento en el conjunto steps[]. A partir del objeto TransitDetails, puedes acceder a información adicional sobre la parada, la línea y la compañía de transporte público.

Un objeto transit_details puede contener los campos indicados a continuación.

  • arrival_stop y departure_stop contienen información sobre la parada o la estación para esta parte del recorrido. Los detalles de la parada pueden incluir:
    • name: nombre de la estación o la parada (por ejemplo, "Union Square"),
    • location: ubicación de la estación o parada de transporte público, representada como campos lat y lng.
  • arrival_time y departure_time contienen las horas de salida y de llegada para esta parte del viaje, con las siguientes tres propiedades:
    • text: valor de tiempo especificado como cadena. El valor de tiempo se muestra en la zona correspondiente situada en la parte superior de la parada de transporte público.
    • value: hora especificada con el formato Unix o los segundos desde la medianoche del 1 de enero de 1970 UTC.
    • time_zone contiene la zona donde se muestra el valor de tiempo de esta estación. El valor es el nombre de la zona donde se muestra el valor de tiempo, tal y como se define en la base de datos de zonas de tiempo de IANA, por ejemplo, "América/Nueva_York".
  • headsign especifica la dirección en la que viaja la línea, tal y como aparece en el vehículo o en la parada de salida. Generalmente esta será la última estación.
  • headway especifica el número previsto de segundos entre salidas de la misma parada en ese momento. Por ejemplo, con un valor headway de 600, podrías prever una espera de diez minutos si perdieras el autobús.
  • num_stopscontiene el número de paradas de este paso, contando la parada de llegada, pero no la de salida. Por ejemplo, si las rutas implican salir de la parada A, pasando por las paradas B y C hasta llegar a la parada D, num_stops devolverá 3 paradas.
  • line contiene información sobre la línea de transporte público utilizada en este paso y puede incluir las siguientes propiedades:
    • name contiene el nombre completo de la línea de transporte público. Por ejemplo: "7 Avenue Express".
    • short_name contiene el nombre abreviado de la línea de transporte público. Generalmente este será un número de línea como, por ejemplo, "M7" o "355".
    • color contiene el color que se utiliza normalmente para señalizar la línea de transporte público en cuestión. El color se especificará como una cadena hexadecimal similar a esta: #FF0033.
    • agencies contiene un conjunto de objetos TransitAgency, cada uno de los cuales proporciona información sobre el operador de la línea, incluidas las siguientes propiedades:
      • name contiene el nombre de la empresa de transporte público.
      • url contiene la URL de la empresa de transporte público.
      • phone contiene el número de teléfono de la empresa de transporte público.

      Debes mostrar los nombres de las URL de las compañías de transporte público que ofrecen servicios en los resultados.

    • url contiene la URL de esta línea de transporte público tal y como la proporciona la empresa de transporte.
    • icon contiene la URL correspondiente al icono asociado a esta línea.
    • text_color contiene el color del texto que se utiliza normalmente para señalizar la línea en cuestión. El color se especificará como una cadena hexadecimal.
    • vehicle contiene el tipo de vehículo utilizado en la línea en cuestión. Puede incluir las siguientes propiedades:
      • name contiene el nombre del vehículo de la línea. Por ejemplo: "Subway" (metro).
      • type contiene el tipo de vehículo utilizado en la línea en cuestión. Para obtener una lista completa de los valores admitidos, consulta la documentación sobre el tipo de vehículo.
      • icon contiene la URL correspondiente a un icono asociado al tipo de vehículo en cuestión.

Tipo de vehículo

La propiedad vehicle.type puede devolver uno de los siguientes valores:

Valor Definición
RAIL Ferrocarril
METRO_RAIL Tren ligero
SUBWAY Metro ligero
TRAM Tranvía
MONORAIL Monorraíl
HEAVY_RAIL Tren pesado
COMMUTER_TRAIN Tren de cercanías
HIGH_SPEED_TRAIN Tren de alta velocidad
BUS Autobús
INTERCITY_BUS Autocar
TROLLEYBUS Trolebús
SHARE_TAXI Taxi colectivo (vehículo que recoge y deposita a los pasajeros en cualquier lugar de la ruta que se le ha asignado)
FERRY Ferry
CABLE_CAR Teleférico (vehículo que se desplaza por un cable, generalmente sobre el suelo; estos vehículos pueden ser del tipo GONDOLA_LIFT)
GONDOLA_LIFT Telecabina (teleférico)
FUNICULAR Funicular (vehículo que se utiliza para subir pendientes mediante un cable; suele estar formado por dos cabinas que actúan como contrapeso una de la otra)
OTHER Para el resto de vehículos se devolverá este tipo.

Autenticación obligatoria

Tienes que acceder a Google+ para realizar esta acción.

Acceder a...

Desarrolladores de Google necesita tu permiso para realizar esta acción.