Servicio Distance Matrix

Descripción general

El servicio Distance Matrix de Google computa la distancia y la duración de los viajes entre varios orígenes y destinos con un medio de transporte determinado.

Este servicio no muestra información detallada de las rutas. La información de las rutas, incluidas las polilíneas y las instrucciones textuales, se puede obtener si se pasan el origen y el destino deseados al servicio Directions.

Cómo comenzar

Antes de usar el servicio Distance Matrix en la API de Maps JavaScript, asegúrate de que la API de Distance Matrix esté habilitada en la consola de Google Cloud, en el mismo proyecto que configuraste para la API de Maps JavaScript.

Para ver tu lista de APIs habilitadas, haz lo siguiente:

1. Ve a la consola de Google Cloud.
2. Haz clic en el botón Seleccionar un proyecto, selecciona el mismo proyecto que configuraste para la API de Maps JavaScript y haz clic en Abrir.
3. En la lista de APIs del Panel, busca API de Distance Matrix.
4. Si ves la API en la lista, no necesitas hacer nada más. Si la API no está en la lista, habilítala:
   1. En la parte superior de la página, selecciona HABILITAR API para abrir la pestaña Biblioteca. También puedes seleccionar Biblioteca en el menú lateral izquierdo.
   2. Busca API de Distance Matrix y selecciónala en la lista de resultados.
   3. Selecciona HABILITAR. Cuando finalice el proceso, la API de Distance Matrix aparecerá en la lista de APIs del Panel.

Precios y políticas

Precios

El 16 de julio de 2018, entró en vigencia un nuevo plan de precios de pago por uso para Maps, Routes y Places. Si deseas obtener más información sobre los nuevos precios y límites de uso del servicio Distance Matrix de JavaScript, consulta el artículo Uso y facturación de la API de Distance Matrix.

Nota: Cada consulta que se envía al servicio Distance Matrix está limitada por la cantidad de elementos permitidos, la cual se define multiplicando la cantidad de orígenes por la cantidad de destinos.

Políticas

El uso del servicio Distance Matrix debe cumplir con las políticas que se describen para la API de Distance Matrix.

Solicitudes de Distance Matrix

El acceso al servicio Distance Matrix es asíncrono, ya que la API de Google Maps debe realizar una llamada a un servidor externo. Por esa razón, debes pasar un método de devolución de llamada para que se ejecute una vez que se complete la solicitud y procesar los resultados.

Puedes acceder al servicio Distance Matrix en tu código a través del objeto constructor google.maps.DistanceMatrixService. El método DistanceMatrixService.getDistanceMatrix() inicia una solicitud al servicio Distance Matrix y le pasa un literal del objeto DistanceMatrixRequest que contiene los orígenes, los destinos y el medio de transporte, así como un método de devolución de llamada que se ejecuta cuando se recibe 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: '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 ejemplo

DistanceMatrixRequest contiene los siguientes campos:

• origins (obligatorio): Es un array que contiene una o más strings de dirección, objetos google.maps.LatLng u objetos Place desde donde se calculan la distancia y el tiempo.
• destinations (obligatorio): Es un array que contiene una o más strings de dirección, objetos google.maps.LatLng u objetos de Place hacia donde se calcula, la distancia y el tiempo.
• travelMode (opcional): Es el medio de transporte que se usará para calcular las instrucciones sobre cómo llegar a un lugar. Consulta la sección sobre los medios de transporte.
• transitOptions (opcional): Son opciones que se aplican solo a las solicitudes en las que travelMode es TRANSIT. Los valores válidos se describen en la sección Opciones de transporte público.
• drivingOptions (opcional): Especifica valores que se aplican solo a solicitudes en las que travelMode es DRIVING. Los valores válidos se describen en la sección Opciones de manejo.
• unitSystem (opcional): Indica el sistema de unidades que se usará para mostrar la distancia. Se aceptan los siguientes valores:
  • google.maps.UnitSystem.METRIC (predeterminado)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways (opcional): Si es true, al calcular las rutas entre los orígenes y los destinos, se evitarán las autopistas cuando sea posible.
• avoidTolls (opcional): Si es true, al calcular las instrucciones sobre cómo llegar de un punto a otro, se incluirán rutas sin peajes cuando sea posible.

Medios de transporte

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

• BICYCLING solicita rutas en bicicleta por sendas para bicicletas y calles preferidas (actualmente, solo disponible en EE.UU. y algunas ciudades de Canadá).
• DRIVING (predeterminado) indica la ruta en auto estándar por la red de rutas.
• TRANSIT solicita instrucciones sobre cómo llegar a un lugar por medio de 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 público para ver las opciones disponibles en este tipo de solicitud.
• WALKING solicita instrucciones sobre cómo llegar a un lugar a pie por rutas peatonales y veredas (cuando estén disponibles).

Opciones de transporte público

El servicio de transporte público actualmente se encuentra en etapa experimental. Durante esta etapa, implementaremos límites de frecuencia para evitar el abuso de la API. Eventualmente, impondremos un límite en la cantidad total de consultas por carga de mapa según el uso pertinente de la API.

Las opciones disponibles para una solicitud de Distance Matrix varían según el medio de transporte. En las solicitudes de transporte público, se ignoran las opciones avoidHighways y avoidTolls. Puedes especificar opciones de rutas específicas de transporte público a través del literal del objeto TransitOptions.

Las solicitudes de transporte público están sujetas al horario. Solo se mostrarán cálculos para horarios futuros.

El literal del 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 ignorará la hora de salida.
• departureTime (opcional) especifica la hora de salida deseada como un objeto Date. departureTime se ignorará si se especifica arrivalTime. Si no se especifica ningún valor para departureTime o arrivalTime, el valor predeterminado es ahora (es decir, la hora actual).
• modes (opcional) es un array que contiene uno o más literales del objeto TransitMode. Este campo solo puede especificarse si en la solicitud se incluye una clave de API. Cada TransitMode especifica un medio de transporte público preferido. Se permiten los siguientes valores:
  • BUS indica que, para la ruta calculada, debe priorizarse el transporte en autobús.
  • RAIL indica que, para la ruta calculada, debe priorizarse el transporte en tren, tranvía, tren ligero y metro.
  • SUBWAY indica que, para la ruta calculada, debe priorizarse el transporte en metro.
  • TRAIN indica que, para la ruta calculada, debe priorizarse el transporte en tren.
  • TRAM indica que, para la ruta calculada, debe priorizarse el transporte en tranvía y tren ligero.
• routingPreference (opcional) especifica las preferencias para las rutas de transporte público. Con esta opción, puedes personalizar las opciones que se muestran en lugar de aceptar la mejor ruta predeterminada que selecciona la API. Este campo solo puede especificarse si en la solicitud se incluye una clave de API. Se permiten los siguientes valores:
  • FEWER_TRANSFERS indica que, para la ruta calculada, debe priorizarse una cantidad limitada de transbordos.
  • LESS_WALKING indica que, para la ruta calculada, debe priorizarse una distancia limitada de recorrido a pie.

Opciones de manejo

Usa el objeto drivingOptions para especificar una hora de salida y, así, calcular la mejor ruta hacia tu destino en función de las condiciones de tráfico esperadas. También puedes especificar si quieres que el tiempo estimado en el tráfico sea pesimista, optimista o la mejor estimación en función de las condiciones de tráfico históricas y el tráfico en tiempo real.

El objeto drivingOptions contiene los siguientes campos:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Estos campos se explican a continuación:

• departureTime (obligatorio para que el literal del objeto drivingOptions sea válido) especifica la hora de salida deseada como un objeto Date. El valor debe establecerse en la hora actual o en una hora futura determinada. No puede ser un horario anterior. (La API convierte todas las fechas al estándar UTC para garantizar un manejo uniforme en todas las zonas horarias). Si incluyes departureTime en la solicitud, la API muestra la mejor ruta en función de las condiciones de tráfico esperadas en ese momento, además del tiempo previsto en el tráfico (duration_in_traffic) en la respuesta. Si no especificas una hora de salida (es decir, si la solicitud no incluye drivingOptions), se suele mostrar una buena ruta sin tener en cuenta las condiciones de tráfico.
• trafficModel (opcional) especifica las suposiciones que se usarán cuando se calcule el tiempo en el tráfico. Esta configuración afecta el valor que se muestra en el campo duration_in_traffic de la respuesta, que contiene el tiempo previsto en el tráfico según los promedios históricos. La configuración predeterminada es best_guess. Se permiten los siguientes valores:
  • bestguess (predeterminado) indica que el valor duration_in_traffic que se muestra debe ser la mejor estimación del tiempo de viaje según lo que se conoce sobre las condiciones del tráfico histórico y el tráfico en tiempo real. Cuanto más se acerque el valor de departureTime al momento presente, más importancia cobrará el tráfico en tiempo real.
  • pessimistic indica que el valor de duration_in_traffic que se muestra debe ser mayor que el tiempo de viaje real la mayoría de los días; no obstante, es posible que se supere este valor determinados días en que las condiciones de tráfico son particularmente desfavorables.
  • optimistic indica que el valor de duration_in_traffic que se muestra debe ser menor que el tiempo de viaje real la mayoría de los días, aunque puede llegar a ser mejor en determinados días en que las condiciones de tráfico sean particularmente buenas.

A continuación, se muestra un ejemplo de DistanceMatrixRequest para rutas en automóvil, que incluye una hora de salida 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: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Respuestas de Distance Matrix

Una llamada exitosa al servicio Distance Matrix muestra un objeto DistanceMatrixResponse y un objeto DistanceMatrixStatus. Estos objetos se pasan a la función de devolución de llamada que especificaste en la solicitud.

El objeto DistanceMatrixResponse contiene información sobre la distancia y la duración de cada par de origen y destino para el que se puede calcular una ruta.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "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 Distance Matrix

A continuación, se explican los campos admitidos en una respuesta.

• originAddresses es un array que contiene las ubicaciones que se pasan en el campo origins de la solicitud de Distance Matrix. Las direcciones se muestran a medida que el geocodificador les asigna un formato.
• destinationAddresses es un array que contiene las ubicaciones que se pasan en el campo destinations, en el formato que muestra el geocodificador.
• rows es un array de objetos DistanceMatrixResponseRow, y cada fila corresponde a un origen.
• elements son elementos secundarios de rows y corresponden a una vinculación del origen de la fila con cada destino. Contienen información sobre el estado, la duración, la distancia y la tarifa (si está disponible) para cada par de origen y destino.
• Cada element contiene los siguientes campos:
  • status: Consulta la sección Códigos de estado para obtener una lista de los posibles códigos de estado.
  • duration: Indica el tiempo que se demora en recorrer esta ruta, expresado en segundos (el campo value) y como text. El formato del valor textual depende del unitSystem especificado en la solicitud (o se expresa en el sistema métrico si no se indicó ninguna preferencia).
  • duration_in_traffic: Indica el tiempo que se demora en recorrer esta ruta según las condiciones de tráfico actuales, expresadas en segundos (el campo value) y como text. El formato del valor textual depende del unitSystem especificado en la solicitud (o se expresa en el sistema métrico si no se indicó ninguna preferencia). El duration_in_traffic solo se devuelve cuando hay datos de tráfico disponibles, el mode se configura como driving. departureTime se incluye como parte del distanceMatrixOptions en la solicitud.
  • distance: Es la distancia total de esta ruta, expresada en metros (value) y como text. El formato del valor textual depende del unitSystem especificado en la solicitud (o se expresa en el sistema métrico si no se indicó ninguna preferencia).
  • fare: Contiene la tarifa total (es decir, los costos totales de los pasajes) de esta ruta. Esta propiedad se muestra solo para las solicitudes de transporte público y para los proveedores de transporte público que disponen de información sobre las tarifas. La información incluye lo siguiente:
    • currency: Es un código de moneda ISO 4217 que indica la moneda en la que se expresa el importe.
    • value: Es el importe total de la tarifa expresado en la moneda especificada más arriba.

Códigos de estado

En la respuesta de Distance Matrix, se incluye un código de estado para la respuesta completa, así como un estado para cada elemento.

Códigos de estado de la respuesta

Los códigos de estado que se aplican a DistanceMatrixResponse se pasan en el objeto DistanceMatrixStatus y, además, incluyen lo siguiente:

• OK: La solicitud es válida. Este estado puede mostrarse aun cuando no se encuentra ninguna ruta entre los orígenes y los destinos. Consulta la sección Códigos de estado de los elementos para obtener información sobre el estado de los elementos.
• INVALID_REQUEST: La solicitud enviada no es válida. A menudo, esto se debe a que faltan campos obligatorios. Consulta la lista de campos admitidos más arriba.
• MAX_ELEMENTS_EXCEEDED: El producto de los orígenes y destinos supera el límite por consulta.
• MAX_DIMENSIONS_EXCEEDED: Tu solicitud contenía más de 25 orígenes o más de 25 destinos.
• OVER_QUERY_LIMIT: Tu aplicación solicitó demasiados elementos durante el período permitido. La solicitud debería completarse con éxito si realizas un nuevo intento después de un tiempo razonable.
• REQUEST_DENIED: El servicio rechazó el uso del servicio Distance Matrix en tu página web.
• UNKNOWN_ERROR: No se pudo procesar una solicitud de Distance Matrix debido a un error del servidor. La solicitud podría completarse con éxito si realizas un nuevo intento.

Códigos de estado de los elementos

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

• NOT_FOUND: No se pudo geocodificar el origen o el destino de este par.
• OK: La respuesta contiene un resultado válido.
• ZERO_RESULTS: No se encontró ninguna ruta entre el origen y el destino.

Cómo analizar los resultados

El objeto DistanceMatrixResponse contiene un row para cada origen que se pasó en la solicitud. Cada fila contiene un campo element para cada vinculación de ese origen con los destinos proporcionados.

function callback(response, status) {
  if (status == '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];
      }
    }
  }
}