Matriz de distancia

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Descripción general

El servicio de matriz de distancia de Google calcula la distancia y la duración del recorrido entre varios orígenes y destinos mediante un modo de viaje determinado.

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

Cómo comenzar

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

Para ver tu lista de API habilitadas:

  1. Ve a Google Cloud Console.
  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 API 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 mostrar la pestaña Biblioteca. Como alternativa, en el menú lateral izquierdo, selecciona Biblioteca.
    2. Busca Distance Matrix API 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 API del Panel.

Precios y políticas

Precios

El 16 de julio de 2018, entró en vigencia un nuevo plan de precios prepagos para Maps, Routes y Places. Para obtener más información sobre los nuevos precios y límites de uso del servicio de matriz de distancia de JavaScript, consulta Uso y facturación para la API de Distance Matrix.

Nota: Cada consulta que se envía al servicio de matriz de distancia está limitada por la cantidad de elementos permitidos, donde la cantidad de orígenes multiplicada por la cantidad de destinos define la cantidad de elementos.

Límites de frecuencia

Ten en cuenta lo siguiente sobre los límites de frecuencia para las solicitudes adicionales:

El límite de frecuencia se aplica por sesión de usuario, independientemente de la cantidad de usuarios que compartan el mismo proyecto. Cuando cargas la API por primera vez, se te asigna una cuota inicial de elementos. Una vez que usas esta cuota, la API aplica límites de frecuencia sobre las solicitudes adicionales por segundo. Si se realizan demasiadas solicitudes en un período determinado, la API muestra un código de respuesta OVER_QUERY_LIMIT.

El límite de frecuencia por sesión evita el uso de servicios del cliente para solicitudes por lotes. Para solicitudes por lotes, usa el servicio web de la API de Distance Matrix.

Políticas

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

Solicitudes de matriz de distancia

El acceso al servicio de matriz de distancia es asíncrono, ya que la Google Maps API debe realizar una llamada a un servidor externo. Por ese motivo, debes pasar un método callback para que se ejecute después de completar la solicitud, a fin de procesar los resultados.

Puedes acceder al servicio de matriz de distancia dentro del código a través del objeto constructor google.maps.DistanceMatrixService. El método DistanceMatrixService.getDistanceMatrix() inicia una solicitud al 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, así como un método de devolución de llamada para ejecutar al momento de 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: '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 arreglo que contiene una o más strings de dirección, objetos google.maps.LatLng o objetos Place a partir de los cuales se calcula la distancia y el tiempo.
  • destinations (obligatorio): Es un arreglo que contiene una o más strings de direcciones, objetos google.maps.LatLng o objetos Place para los que se va a calcular la distancia y el tiempo.
  • travelMode (opcional): el medio de transporte que se usará para calcular las instrucciones sobre cómo llegar Consulta la sección sobre modos de viaje.
  • transitOptions (opcional): opciones que se aplican solo a las solicitudes en las que travelMode es TRANSIT. Los valores válidos se describen en la sección sobre 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): El sistema de unidades que se usará cuando se muestre la distancia. Se aceptan los siguientes valores:
    • google.maps.UnitSystem.METRIC (predeterminada)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (opcional): Si es true, las rutas entre orígenes y destinos se calcularán para evitar autopistas cuando sea posible.
  • avoidTolls (opcional): Si es true, las instrucciones sobre cómo llegar de un punto a otro se calcularán con rutas no gratuitas, siempre que 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 medios de transporte:

  • BICYCLING solicita indicaciones para llegar en bicicleta a través de ciclovías y calles preferidas (actualmente, solo está disponible en EE.UU. y algunas ciudades de Canadá).
  • DRIVING (predeterminado) indica las instrucciones estándar sobre cómo llegar en automóvil mediante la red de carreteras.
  • TRANSIT solicita instrucciones sobre cómo llegar a través de rutas de transporte público. Esta opción solo se puede especificar si la solicitud incluye una clave de API. Consulta la sección sobre las opciones de transporte público para ver las opciones disponibles en este tipo de solicitud.
  • WALKING solicita instrucciones sobre cómo llegar a pie por sendas peatonales y veredas (cuando estén disponibles).

Opciones de transporte

Actualmente, el servicio de transporte público es experimental. Durante esta fase, implementaremos límites de frecuencia para evitar abusos de la API. Eventualmente, aplicaremos un límite a las consultas totales por carga de mapa según el uso legítimo de la API.

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

Las solicitudes de transporte están sujetas a la hora. Los cálculos solo se mostrarán para las 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 salida.
  • departureTime (opcional) especifica la hora de salida deseada como un objeto Date. departureTime se ignorará si se especifica arrivalTime. El valor predeterminado es ahora (es decir, la hora actual) si no se especifica ningún valor para departureTime o arrivalTime.
  • modes (opcional) es un arreglo que contiene uno o más literales de objeto TransitMode. Este campo solo se puede incluir si la solicitud 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 subterráneo.
    • 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 restringir las opciones que se muestran en lugar de aceptar la mejor ruta predeterminada seleccionada por la API. Este campo solo se puede especificar si la solicitud incluye una clave de API. Se permiten los siguientes valores:
    • FEWER_TRANSFERS indica que para la ruta calculada debe preferirse un número limitado de transbordos.
    • LESS_WALKING indica que, para la ruta calculada, se deben preferir traslados a pie limitados.

Opciones de manejo

Usa el objeto drivingOptions a fin de especificar una hora de salida para calcular la mejor ruta a 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 vivo.

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 salida deseada como un objeto Date. El valor se debe establecer en la hora actual o en una hora futura. No puede ser en el pasado. (La API convierte todas las fechas a UTC para garantizar un manejo coherente 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), la ruta que se muestra suele ser una buena ruta sin tener en cuenta las condiciones del tráfico.

    Nota: Si no se especifica la hora de salida, la elección de la ruta y la duración se basan en la red de ruta y las condiciones de tráfico promedio independientes del tiempo. Los resultados de una solicitud determinada pueden variar con el tiempo debido a los cambios en la red de rutas, las condiciones promedio del tráfico actualizadas y la naturaleza distribuida del servicio. Los resultados también pueden variar entre rutas casi equivalentes en cualquier momento o frecuencia.

  • 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 en 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 el estado del tráfico histórico y el tráfico en vivo. Cuanto más se acerque departureTime a la actualidad, más importante será el tráfico en vivo.
    • pessimistic indica que el valor de duration_in_traffic que se muestra debe ser más largo que el tiempo de viaje real en la mayoría de los días, aunque en algunos casos con condiciones de tráfico particularmente malas pueden exceder este valor.
    • optimistic indica que el valor de duration_in_traffic que se muestra debe ser más corto que el tiempo de viaje real en la mayoría de los días, aunque en algunos casos con condiciones de tráfico particularmente buenas, este valor puede ser más rápido.

A continuación, se muestra un ejemplo de DistanceMatrixRequest para rutas en automóvil, incluida 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 la matriz de distancia

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

El objeto DistanceMatrixResponse contiene información sobre distancia y duración de cada par de origen y destino para el que se podría 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 la matriz de distancia

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

  • originAddresses es un arreglo que contiene las ubicaciones que se pasaron 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 arreglo que contiene las ubicaciones pasadas en el campo destinations, en el formato que muestra el geocodificador.
  • rows es un arreglo de objetos DistanceMatrixResponseRow, y cada fila corresponde a un origen.
  • elements son elementos secundarios 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 la tarifa (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 los posibles códigos de estado.
    • duration: El tiempo que tarda esta ruta, expresado en segundos (el campo value) y como text. El valor textual tiene un formato según el unitSystem especificado en la solicitud (o en métrica, si no se suministró ninguna preferencia).
    • duration_in_traffic: El tiempo que tarda esta ruta en tener en cuenta las condiciones de tráfico actuales, expresadas en segundos (el campo value) y como text. El valor textual tiene un formato según el unitSystem especificado en la solicitud (o en métrica, si no se suministró ninguna preferencia). duration_in_traffic solo se muestra a los clientes del plan premium de Google Maps Platform cuando hay datos de tráfico disponibles, el mode se establece en driving y departureTime se incluye 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 tiene un formato según el unitSystem especificado en la solicitud (o en métrica, si no se suministró ninguna preferencia).
    • fare: Contiene la tarifa total (es decir, el costo total del boleto) para esta ruta. Esta propiedad solo se muestra para solicitudes de transporte y en el caso de proveedores de transporte que cuentan con información de 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 en la moneda especificada anteriormente.

Códigos de estado

La respuesta de Distance Matrix incluye un código de estado para toda la respuesta, así como 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 y, además, incluyen lo siguiente:

  • OK: La solicitud es válida. Este estado se puede mostrar incluso si no se encontraron rutas entre los orígenes y los destinos. Consulta Códigos de estado de elementos para obtener información sobre el estado a nivel de los 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 compatibles más arriba.
  • MAX_ELEMENTS_EXCEEDED: El producto de 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 dentro del período permitido. La solicitud debería completarse correctamente si vuelves a intentarlo después de un período razonable.
  • REQUEST_DENIED: el servicio rechazó el uso del servicio de matriz de distancia en tu página web.
  • UNKNOWN_ERROR: No se pudo procesar una solicitud a la matriz de distancia debido a un error del servidor. La solicitud puede tener éxito si vuelves a intentarlo.

Códigos de estado de 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 esta sincronización.
  • OK: la respuesta contiene un resultado válido.
  • ZERO_RESULTS: No se encontró ninguna ruta entre el origen y el destino.

Cómo procesar 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 sincronizació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];
      }
    }
  }
}