Eso es todo.

Para comenzar a desarrollar, consulta nuestra documentación para desarrolladores.

Activar la Google Maps JavaScript API

Para que puedas comenzar, te proporcionaremos orientación en la Google Developers Console a fin de que hagas primero algunas acciones:

  1. Crear o seleccionar un proyecto
  2. Activar la Google Maps JavaScript API y servicios relacionados
  3. Crear claves correspondientes
Continuar

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.

Primeros pasos

Antes de usar el servicio de matriz de distancia de la Google Maps JavaScript API, debes asegurarte de que Google Maps Distance Matrix API esté habilitada en la Google API Console, en el mismo proyecto que configuraste para la Google Maps JavaScript API.

Para ver tu lista de API habilitadas:

  1. Ingresa a Google API Console.
  2. Haz clic en el botón Select a project, luego selecciona el mismo proyecto que configuraste para la Google Maps JavaScript API y haz clic en Open.
  3. En la lista de API del Panel de control, busca Google Maps Distance Matrix API.
  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 ENABLE API para mostrar la pestaña Library. Como alternativa, en el menú lateral izquierdo, selecciona Library.
    2. Busca Google Maps Distance Matrix API y luego selecciónala en la lista de resultados.
    3. Selecciona ENABLE. Cuando finalice el proceso, Google Maps Distance Matrix API aparecerá en la lista de API del Panel de control.

Límites y políticas de uso

Cuotas

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

Nota: Cada consulta que se envía al servicio de matriz de distancia está limitada por la cantidad de elementos permitidos; la cantidad de sitios de origen multiplicada por la cantidad de sitios de destino define la cantidad de elementos.

Uso del servicio de matriz de distancia en el plan estándar

  • 2500 elementos gratis por día, calculados como la suma de las consultas del cliente y el servidor; habilitar facturación para acceder a las cuotas diarias por un costo de USD 0,50 cada 1000 elementos adicionales, hasta 100 000 elementos diarios.
  • 25 orígenes o 25 destinos como máximo por solicitud.
  • 100 elementos como máximo por solicitud.
  • 100 elementos como máximo por segundo, calculados como la suma de las consultas del cliente y el servidor.

Uso del servicio de matriz de distancia en el plan premium

  • Cuota gratuita diaria compartida de 100 000 elementos durante 24 horas; las solicitudes adicionales se cargarán a la compra anual de créditos de Maps API..
  • 25 orígenes o 25 destinos como máximo por solicitud.
  • 625 elementos como máximo por solicitud. Nota: Las solicitudes que usan el parámetro opcional departure_time cuando mode=driving tienen un límite de 100 cada una.
  • Ilimitado elementos del cliente por segundo y por proyecto. Ten en cuenta que la API del servidor tiene una cantidad límite de 1000 elementos por segundo.

El límite de índice se aplica por sesión de usuario, independientemente de la cantidad de usuarios que compartan el mismo proyecto.

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

Políticas

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

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: '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): una matriz que contiene una o más strings de direcciones, objetos google.maps.LatLng u objetos google.maps.Place a partir de los cuales se calcularán la distancia y el tiempo.
  • destinations (obligatorio): una matriz que contiene una o más strings de direcciones, objetos google.maps.LatLng u objetos google.maps.Place para 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 que travelMode es TRANSIT. En Opciones de transporte se describen valores válidos.
  • drivingOptions (opcional) especifica valores que se aplican solo a solicitudes en las que travelMode es 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:

  • 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á).
  • DRIVING (predeterminado) establece indicaciones de manejo estándares por la red de carreteras.
  • 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.
  • WALKING solicita indicaciones de traslado a pie por sendas peatonales y veredas (cuando estén disponibles).

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:
    • 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 subterráneo.
    • 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 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:
    • FEWER_TRANSFERS indica que, para la ruta calculada, se debe preferir una cantidad limitada de transbordos.
    • LESS_WALKING indica que, para la ruta calculada, se deben preferir 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 APIs Premium Plan 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 APIs Premium Plan, 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:
    • bestguess (predeterminado) indica que el valor duration_in_traffic mostrado debe ser el mejor cálculo en términos de tiempo de viaje a partir de lo que se conoce sobre las condiciones históricas del tráfico y el tráfico en tiempo real. Cuanto más se acerque departureTime al valor presente, mayor importancia cobrará el tráfico en tiempo real...
    • pessimistic indica que el valor duration_in_traffic devuelto debe ser superior al tiempo de viaje real en la mayoría de los días. Sin embargo, este valor puede ser inferior al tiempo de viaje real en ciertos días en que las condiciones de tráfico son particularmente desfavorables.
    • optimistic indica que el valor duration_in_traffic devuelto debe ser inferior al del tiempo de viaje real en la mayoría de los días. Sin embargo, este valor puede ser superior al tiempo de viaje real 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: '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.

{
  "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 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 APIs Premium Plan 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 == '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];
      }
    }
  }
}

Enviar comentarios sobre...

Google Maps JavaScript API
Google Maps JavaScript API
Si necesitas ayuda, visita nuestra página de asistencia.