Matriz de distancia

Información general

El servicio de matriz de distancia de Google computa la distancia y la duración de viajes entre varios orígenes y destinos según determinados modos de viaje.

Este servicio no devuelve información detallada sobre rutas. La información sobre rutas, incluidas las polilíneas y las indicaciones textuales, puede obtenerse pasando el origen y el destino deseados al servicio de indicaciones.

Requisitos y límites de uso

Cuotas

Los siguientes límites de uso se encuentran en vigencia para el servicio de matriz de distancia:

• 25 orígenes o 25 destinos como máximo por solicitud; y
• 100 elementos (orígenes por destinos) por solicitud.

Las solicitudes también están limitadas por cifras. Si se solicitan demasiados elementos dentro de un período de tiempo determinado, se devolverá un código de respuesta OVER_QUERY_LIMIT.

Visualización de un mapa de Google Maps

El uso de la matriz de distancia debe relacionarse con la visualización de información en un mapa de Google Maps; por ejemplo, para determinar pares de orígenes y destinos cuyas distancias exigen un tiempo de manejo específico antes de solicitar y mostrar los destinos en cuestión en un mapa. Se prohíbe el uso del servicio en una aplicación en la que no se muestre un mapa de Google Maps.

Solicitudes de matriz de distancia

El acceso al servicio de matriz de distancia es asincrónico, ya que la Google Maps API debe realizar una llamada a un servidor externo. Por esta razón, a fin de procesar los resultados, debes pasar un método callback para la ejecución al completarse la solicitud.

Puedes acceder al servicio de matriz de distancia dentro de tu código a través del objeto google.maps.DistanceMatrixService. El método DistanceMatrixService.getDistanceMatrix() inicia una solicitud para el servicio de matriz de distancia y le pasa un literal de objeto DistanceMatrixRequest que contiene los orígenes, los destinos y el modo de viaje, además de un método callback para la ejecución al recibir la respuesta.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = "Greenwich, England";
var destinationA = "Stockholm, Sweden";
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: google.maps.TravelMode.DRIVING,
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

Ver el ejemplo (distance-matrix.html)

DistanceMatrixRequest contiene los siguientes campos:

• origins (obligatorio): conjunto que contiene una o más cadenas de direcciones, o bien uno o más objetos google.maps.LatLng, a partir de los cuales se calcularán la distancia y el tiempo.
• destinations (obligatorio): conjunto que contiene una o más cadenas de direcciones, o bien uno o más objetos google.maps.LatLng, hasta los cuales se calcularán la distancia y el tiempo.
• travelMode (opcional): modo de transporte que debe usarse al calcular indicaciones. Consulta la sección sobre modos de viaje.
• transitOptions (opcional): opciones que se aplican solo a solicitudes en las cuales travelMode es google.maps.TravelMode.TRANSIT. En Opciones de transporte se describen valores válidos.
• drivingOptions (opcional) especifica valores que se aplican solo a solicitudes en las cuales travelMode es google.maps.TravelMode.DRIVING. En Opciones de manejo se describen valores válidos.
• unitSystem (opcional): sistema de unidades que debe usarse al mostrar distancias. Valores aceptados:
  • google.maps.UnitSystem.METRIC (predeterminado)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (opcional): si el valor es true, en el cálculo de las rutas entre orígenes y destinos se evitarán las autopistas cuando sea posible.
• avoidTolls (opcional): si el valor es true, en el cálculo de indicaciones entre puntos se incluirán rutas sin peajes cuando sea posible.

Modos de viaje

Al calcular los tiempos y las distancias, puedes especificar el modo de transporte que se usará. Actualmente, se admiten los siguientes modos de viaje:

• google.maps.TravelMode.BICYCLING solicita indicaciones de circulación en bicicleta por sendas para bicicletas y calles preferidas (actualmente, solo disponible en Estados Unidos y en algunas ciudades de Canadá).
• google.maps.TravelMode.DRIVING (predeterminado) muestra indicaciones de manejo por la red de carreteras.
• google.maps.TravelMode.TRANSIT solicita indicaciones por rutas de transporte público. Esta opción solo puede especificarse si en la solicitud se incluye una clave de API. Consulta la sección Opciones de transporte para hallar las opciones disponibles en este tipo de solicitud.
• google.maps.TravelMode.WALKING solicita indicaciones de traslado a pie por sendas peatonales y aceras (cuanto está disponible).

Opciones de transporte

El servicio de transporte actualmente se encuentra en etapa experimental. Durante esta etapa, implementaremos límites de velocidad para evitar el uso abusivo de la API. Eventualmente, impondremos una restricción sobre las consultas totales por carga de mapa según el uso pertinente de la API.

Las opciones disponibles para una solicitud de matriz de distancia varían según el modo de viaje. En solicitudes de transporte, las opciones avoidHighways y avoidTolls no se tienen en cuenta. Puedes precisar opciones de rutas específicas para transportes a través del literal de objeto TransitOptions.

Las solicitudes de transporte están sujetas a la hora. Solo se devolverán para horas futuras.

El literal de objeto TransitOptions contiene los siguientes campos:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

Estos campos se explican a continuación:

• arrivalTime (opcional) especifica la hora de llegada deseada como un objeto Date. Si se especifica la hora de llegada, se ignora la hora de partida.
• departureTime (opcional) especifica la hora de partida deseada como un objeto Date. Se ignorará departureTime si se especifica arrivalTime. El valor predeterminado es este momento (es decir, la hora actual) si no se especifican valores para departureTime o arrivalTime.
• modes (opcional) es un conjunto que contiene uno o más literales de objeto TransitMode. Este campo solo puede incluirse si en la solicitud se incluye una clave de API. En cada TransitMode se especifica un modo de transporte preferido. Se permiten los siguientes valores:
  • google.maps.TransitMode.BUS indica que para la ruta calculada debe preferirse el transporte en autobús.
  • google.maps.TransitMode.RAIL indica que para la ruta calculada debe preferirse el transporte en tren, tranvía y subterráneo.
  • google.maps.TransitMode.SUBWAY indica que para la ruta calculada debe preferirse el transporte en subterráneo.
  • google.maps.TransitMode.TRAIN indica que para la ruta calculada debe preferirse el transporte en tren.
  • google.maps.TransitMode.TRAM indica que para la ruta calculada debe preferirse el transporte en tranvía.
• routingPreference (opcional) especifica preferencias para rutas de transporte. Con esta opción, puedes restringir las opciones devueltas en lugar de aceptar la mejor ruta predeterminada seleccionada por la API. Este campo solo puede especificarse si en la solicitud se incluye una clave de API. Se permiten los siguientes valores:
  • google.maps.TransitRoutePreference.FEWER_TRANSFERS indica que para la ruta calculada debe preferirse un número limitado de transbordos.
  • google.maps.TransitRoutePreference.LESS_WALKING indica que para la ruta calculada deben preferirse traslados a pie limitados.

Opciones de manejo

Puedes especificar opciones de rutas para recorridos de manejo a través del objeto DrivingOptions. Debes proporcionar un id. de cliente de Google Maps API for Work al cargar la API si deseas incluir un campo drivingOptions en DistanceMatrixRequest.

El objeto DrivingOptions contiene los siguientes campos:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Estos campos se explican a continuación:

• departureTime (obligatorio para que el literal de objeto drivingOptions sea válido) especifica la hora de partida deseada como un objeto Date. El valor debe fijarse en la hora actual o en una hora futura determinada. No puede ser un horario pasado. (La API convierte todas las fechas al parámetro UTC para garantizar un manejo uniforme en todas las zonas horarias). Para los clientes de Google Maps API for Work, si incluyes departureTime en la solicitud, la API devuelve la mejor ruta conforme a las condiciones de tráfico que se esperan en el horario en cuestión e incluye la hora prevista con tráfico (duration_in_traffic) en la respuesta. Si no especificas una hora de partida (es decir, si en la solicitud no se incluye drivingOptions), se devolverá una ruta generalmente recomendada sin considerar las condiciones del tráfico.
• trafficModel (opcional) especifica las suposiciones que deben aplicarse al calcular el tiempo con tráfico. Esta configuración afecta el valor devuelto en el campo duration_in_traffic en la respuesta, que contiene el tiempo previsto en el tráfico según promedios históricos. El valor predeterminado es best_guess. Se permiten los siguientes valores:
  • google.maps.TrafficModel.BEST_GUESS (predeterminado) o el valor de cadena best_guess indican que el campo duration_in_traffic devuelto debe ser el mejor cálculo en términos de tiempo de viaje a partir de lo que se conoce sobre condiciones de tráfico históricas y tráfico en tiempo real. Cuanto más se acerque departureTime al valor presente, mayor importancia cobrará el tráfico en tiempo real...
  • google.maps.TrafficModel.PESSIMISTIC o el valor de cadena pessimistic indican que el campo duration_in_traffic devuelto debe tener un valor superior al del tiempo de viaje real en la mayoría de los días. Sin embargo, este valor puede excederse en ciertos días en que las condiciones de tráfico son particularmente desfavorables.
  • google.maps.TrafficModel.OPTIMISTIC o el valor de cadena optimistic indican que el campo duration_in_traffic devuelto debe tener un valor inferior al del tiempo de viaje real en la mayoría de los días. Sin embargo, este valor puede sobrar en ciertos días en que las condiciones de tráfico son particularmente favorables.

A continuación, se muestra un ejemplo de DistanceMatrixRequest para rutas de manejo en el que se incluyen una hora de partida y un modelo de tráfico:

{
  origins: [{lat: 55.93, lng: -3.118}, "Greenwich, England"],
  destinations: ["Stockholm, Sweden", {lat: 50.087, lng: 14.421}],
  travelMode: google.maps.TravelMode.DRIVING,
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: "optimistic"
  }
}

Respuestas de la matriz de distancia

Una llamada exitosa al servicio de matriz de distancia devuelve un objeto DistanceMatrixResponse y un objeto DistanceMatrixStatus. Estos se pasan a la función de callback que especificaste en la solicitud.

El objeto DistanceMatrixResponse contiene información sobre distancia y duración de cada par de origen y destino para los cuales puede calcularse una ruta.

{
  "origin_addresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destination_addresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

Resultados de la matriz de distancia

Los campos admitidos en una respuesta se explican a continuación.

• originAddresses es un conjunto que contiene las ubicaciones transferidas en el campo origins de la solicitud de matriz de distancia. Las direcciones se devuelven a medida que el geocodificador las modifica.
• destinationAddresses es un conjunto que contiene las ubicaciones transferidas en el campo destinations, en el formato devuelto por el geocodificador.
• rows es un conjunto de objetos DistanceMatrixResponseRow y cada fila corresponde a un origen.
• elements son hijos de rows y corresponden a una sincronización del origen de la fila con cada destino. Contienen información sobre el estado, la duración, la distancia y el monto (si está disponible) para cada par de origen y destino.
• Cada element contiene los siguientes campos:
  • status: Consulta Códigos de estado para obtener una lista de códigos de estado posibles.
  • duration: El período de tiempo que se necesita para recorrer esta ruta, expresado en segundos (campo value) y como text. El valor textual recibe formato según el objeto unitSystem especificado en la solicitud (o unidades métricas, si no existen preferencias).
  • duration_in_traffic: período de tiempo que se necesita para recorrer esta ruta, teniendo en cuenta las condiciones actuales del tráfico expresadas en segundos (campo value) y como text. El valor textual recibe formato según el objeto unitSystem especificado en la solicitud (o unidades métricas, si no existen preferencias). El campo duration_in_traffic solo se devuelve a clientes de Google Maps API for Work en cuyo caso haya disponibles datos sobre el tráfico, se fije el valor de mode en driving y se incluya departureTime como parte del campo distanceMatrixOptions en la solicitud.
  • distance: La distancia total de esta ruta, expresada en metros (value) y como text. El valor textual recibe formato según el objeto unitSystem especificado en la solicitud (o unidades métricas, si no existen preferencias).
  • fare: contiene los gastos totales (es decir, los costos totales de los tiques) de esta ruta. Esta propiedad se devuelve únicamente para solicitudes de transporte y en el caso de proveedores de transporte, cuando se encuentre disponible información sobre gastos. La información incluye lo siguiente:
    • currency: código de moneda ISO 4217 que indica la divisa en la cual se expresa el monto.
    • value: monto total expresado en la moneda antes especificada.

Códigos de estado

En la respuesta de matriz de distancia se incluyen un código de estado para la respuesta en conjunto y un estado para cada elemento.

Códigos de estado de respuesta

Los códigos de estado que se aplican a DistanceMatrixResponse se pasan en el objeto DistanceMatrixStatus e incluyen lo siguiente:

• OK: la solicitud es válida. Este estado puede devolverse aun cuando no se encuentren rutas entre los orígenes y los destinos. Para hallar información sobre estados en el nivel de los elementos, consulta Códigos de estado de elementos.
• INVALID_REQUEST: la solicitud proporcionada no es válida. A menudo, esto se debe a la falta de campos obligatorios. Consulta la lista de campos admitidos presentada arriba.
• MAX_ELEMENTS_EXCEEDED: el producto de orígenes y destinos excede el límite por consulta.
• MAX_DIMENSIONS_EXCEEDED: tu solicitud contiene más de 25 orígenes o más de 25 destinos.
• OVER_QUERY_LIMIT: tu aplicación solicitó demasiados elementos dentro del período de tiempo permitido. La solicitud debe completarse con éxito si realizas un nuevo intento después de un tiempo razonable.
• REQUEST_DENIED: el servicio no permitió que tu página web usara el servicio de matriz de distancia.
• UNKNOWN_ERROR no se pudo procesar una solicitud de indicaciones debido a un error en el servidor. La solicitud puede tener éxito si realizas un nuevo intento.

Códigos de estado de elementos

Los siguientes códigos de estado se aplican a objetos DistanceMatrixElement específicos:

• NOT_FOUND: el origen o destino de esta sincronización no pudieron someterse a geocodificación.
• OK: la respuesta contiene un resultado válido.
• ZERO_RESULTS: no fue posible hallar una ruta entre el origen y el destino.

Cómo procesar los resultados

El objeto DistanceMatrixResponse contiene un elemento row para cada origen transferido en la solicitud. Cada fila contiene un campo element para cada sincronización de dicho origen junto con los destinos proporcionados.

function callback(response, status) {
  if (status == google.maps.DistanceMatrixStatus.OK) {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}