Serviço Directions

Visão geral

Calcule rotas (usando diversos métodos de transporte) usando o objeto DirectionsService. O objeto se comunica com serviço Directions da Google Maps API, que recebe solicitações de rotas e retorna resultados calculados. Processe essas rotas você mesmo ou use o objeto DirectionsRenderer para renderizar esses resultados.

Para informar a origem ou o destino em uma solicitação de rotas, especifique uma string de consulta (por exemplo, "Chicago, IL" ou "Darwin, NSW, Australia"), um valor LatLng ou um objeto google.maps.Place.

O serviço Directions pode retornar rotas em várias partes usando uma série de pontos de referência. As rotas são exibidas como uma polilinha desenhando a rota em um mapa ou também como uma série de descrições textuais em um elemento <div> (por exemplo, "Vire à direita na rampa da Williamsburg Bridge").

Solicitações de rotas

O acesso ao serviço Directions é assíncrono, pois a Google Maps API precisa chamar um servidor externo. Por isso, passe um método de retorno de chamada a ser executado na conclusão da solicitação. Esse método de retorno de chamada processa os resultados. Observe que o serviço Directions pode retornar mais de um itinerário possível como uma matriz de routes[] separadas.

Para usar as rotas em Google Maps JavaScript API, crie um objeto do tipo DirectionsService e chame DirectionsService.route() para iniciar uma solicitação ao serviço Directions, passando um literal de objeto DirectionsRequest contendo os termos de entrada e um método de retorno de chamada para execução no recebimento da resposta.

O literal de objeto DirectionsRequest contém os seguintes campos:

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

Esses campos são explicados a seguir:

• origin (obrigatório) especifica a localização de partida para o cálculo de rotas. Esse valor pode ser especificado como uma String (por exemplo, "Chicago, IL"), como um valor LatLng ou como um objeto google.maps.Place. Para usar um objeto google.maps.Place, especifique um place ID, uma string de consulta ou uma localização LatLng. Recupere IDs de locais dos serviços Geocoding, Place Search e Place Autocomplete na Google Maps JavaScript API. Para obter um exemplo sobre como usar IDs de local da Place Autocomplete, consulte Place Autocomplete e rotas.
• destination (obrigatório) especifica a localização de chegada para o cálculo de rotas. As opções são as mesmas do campo origin descrito acima.
• travelMode (obrigatório) especifica o modo de transporte a usar no cálculo de rotas. Os valores válidos são especificados em Modos de transporte abaixo.
• transitOptions (opcional) especifica valores aplicados apenas a solicitações em que travelMode é google.maps.TravelMode.TRANSIT. Os valores válidos são descritos em opções de transporte público abaixo.
• drivingOptions (opcional) — especifica valores aplicados apenas a solicitações em que travelMode é google.maps.TravelMode.DRIVING. Os valores válidos são descritos em opções de condução abaixo.

• unitSystem (opcional) especifica o sistema de unidades a ser usado para exibir resultados. Valores válidos são especificados na seção Sistemas de unidade abaixo.

• waypoints[] (opcional) especifica uma matriz de vários DirectionsWaypoint. Pontos de referência alteram uma rota desviando-a por locais específicos. Um ponto de referência é especificado como um literal de objeto com os campos mostrados abaixo:

  • location especifica a localização do ponto de referência, como um LatLng, como um objeto google.maps.Place ou como uma String que será geocodificada.
  • stopover é um valor booleano que indica se o ponto de referência é uma parada na rota que, na prática, divide a rota em duas.

  (Para saber mais sobre pontos de referência, consulte a seção Usar pontos de referência em rotas abaixo.)

• optimizeWaypoints (opcional) especifica que a rota usando os waypoints informados pode ser otimizada para fornecer a rota mais curta possível. Se true, o serviço Directions retorna os waypoints reordenados em um campo waypoint_order. (Para obter mais informações, consulte Usar pontos de referência em rotas abaixo.)
• provideRouteAlternatives (opcional) quando definida como true especifica que o serviço Directions pode fornecer mais de uma rota alternativa na resposta. Observe que fornecer rotas alternativas pode aumentar o tempo de resposta do servidor.
• avoidHighways (opcional) quando definida como true indica que as rotas calculadas devem evitar as rodovias principais, se possível.
• avoidTolls (opcional) quando definida como true indica que as rotas calculadas devem evitar rodovias com pedágios, se possível.
• region (opcional) especifica o código de região como um valor de ccTLD ("domínio de nível superior") de dois caracteres. (Para saber mais, consulte Direcionamento de região abaixo.)

Veja a seguir um exemplo de DirectionsRequest:

{
  origin: "Chicago, IL",
  destination: "Los Angeles, CA",
  waypoints: [
    {
      location:"Joplin, MO",
      stopover:false
    },{
      location:"Oklahoma City, OK",
      stopover:true
    }],
  provideRouteAlternatives: false,
  travelMode: google.maps.TravelMode.DRIVING,
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: google.maps.TrafficModel.PESSIMISTIC
  }
  unitSystem: UnitSystem.IMPERIAL
}

Modos de transporte

No cálculo de rotas, é necessário especificar o modo de transporte a ser usado. No momento, são permitidos os seguintes modos de transporte:

• google.maps.TravelMode.DRIVING (padrão) indica rotas de condução padrão usando a rede de vias.
• google.maps.TravelMode.BICYCLING solicita uma rota para bicicleta por ciclovias e ruas preferenciais.
• google.maps.TravelMode.TRANSIT solicita rotas usando vias de transporte público.
• google.maps.TravelMode.WALKING solicita rotas de caminhada usando vias para pedestres e calçadas.

Consulte os dados de cobertura do Google Maps para determinar a abrangência do suporte a rotas no país. Solicitações de rotas para uma região em que o tipo de rota não está disponível retornam DirectionsStatus="ZERO_RESULTS".

Rotas para caminhada podem não incluir vias para pedestres claras. Portanto, essas rotas retornam avisos no DirectionsResult, que é preciso exibir se o DirectionsRenderer padrão não é usado.

Opções de transporte público

No momento, o serviço de transporte público é "experimental". Implementaremos limites de utilização nessa fase para evitar uso abusivo da API. Mais à frente, implementaremos um limite de total de consultas por carregamento de mapa com base no uso normal da API.

As opções disponíveis para uma solicitação de rotas variam entre modos de transporte. Na solicitação de rotas de transporte público, as opções avoidHighways, avoidTolls, waypoints[] e optimizeWaypoints são ignoradas. Especifique opções de rotas específicas de transporte público usando o literal de objeto TransitOptions.

As rotas de transporte público dependem do horário. Somente são retornadas rotas para horários no futuro.

O literal de objeto TransitOptions contém os seguintes campos:

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

Esses campos são explicados a seguir:

• arrivalTime (opcional) especifica o horário de chegada desejado como um objeto Date. Se o horário de chegada é especificado, o horário de partida é ignorado.
• departureTime (opcional) especifica o horário de partida desejado como um objeto Date. departureTime é ignorado se arrivalTime é especificado. Se nenhum valor é especificado para departureTime ou arrivalTime, o padrão é agora (ou seja, o horário atual).
• modes[] (opcional) é uma matriz contendo um ou mais literais de objeto TransitMode. Esse campo somente pode ser incluído em solicitações com chave de API. Cada TransitMode especifica um modo de transporte público preferencial. Os valores a seguir são permitidos:
  • google.maps.TransitMode.BUS indica que a rota calculada deve dar preferência ao transporte por ônibus.
  • google.maps.TransitMode.RAIL indica que a rota calculada deve dar preferência ao transporte por trem, bonde e metrô.
  • google.maps.TransitMode.SUBWAY indica que a rota calculada deve dar preferência ao transporte por metrô.
  • google.maps.TransitMode.TRAIN indica que a rota calculada deve dar preferência ao transporte por trem.
  • google.maps.TransitMode.TRAM indica que a rota calculada deve dar preferência ao transporte por bonde.
• routingPreference (opcional) especifica preferências para rotas de transporte público. Use essa opção para direcionar as opções retornadas em vez de aceitar a melhor rota padrão escolhida pela API. Esse campo só pode ser especificado para solicitações que incluem uma chave de API. Os valores a seguir são permitidos:
  • google.maps.TransitRoutePreference.FEWER_TRANSFERS indica que a rota calculada deve dar preferência a uma quantidade limitada de baldeações.
  • google.maps.TransitRoutePreference.LESS_WALKING indica que a rota calculada deve dar preferência a uma quantidade limitada de caminhada.

Veja abaixo um exemplo de DirectionsRequest por transporte público:

{
  origin: "Hoboken NJ",
  destination: "Carroll Gardens, Brooklyn",
  travelMode: google.maps.TravelMode.TRANSIT,
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: [google.maps.TransitMode.BUS],
    routingPreference: google.maps.TransitRoutePreference.FEWER_TRANSFERS
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Opções de condução

Especifique opções de rota para rotas de condução usando o objeto DrivingOptions. Informe um ID de cliente da Google Maps API for Work no carregamento da API para incluir um campo drivingOptions na DirectionsRequest.

O objeto DrivingOptions contém os seguintes campos:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Esses campos são explicados a seguir:

• departureTime (obrigatório para que o literal de objeto drivingOptions seja válido) especifica o horário de partida como um objeto Date. O valor deve ser definido como o horário atual ou algum horário no futuro. Seu valor não deve estar no passado. (A API converte todas as datas para UTC para garantir o processamento consistente entre fusos horários.) Para clientes da Google Maps API for Work, se departureTime é incluído na solicitação, a API retorna a melhor rota considerando as condições de trânsito esperadas no momento e inclui o tempo previsto no trânsito (duration_in_traffic) na resposta. Se o horário de partida não é especificado (ou seja, a solicitação não inclui drivingOptions), a rota retornada é normalmente uma boa rota sem considerar condições de trânsito.
• trafficModel (opcional) especifica as suposições a serem usadas no cálculo do tempo no trânsito. Essa configuração afeta o valor retornado no campo duration_in_traffic da resposta, que contém a previsão de tempo baseada em médias históricas. O padrão é best_guess. Os valores a seguir são permitidos:
  • google.maps.TrafficModel.BEST_GUESS (padrão) ou o valor de string best_guess indica que o valor duration_in_traffic retornado deve ser a melhor estimativa do tempo de percurso, considerando o que se sabe sobre as condições históricas e as informações em tempo real do trânsito. As informações de trânsito em tempo real são mais importantes quando departureTime é mais próximo do horário atual.
  • google.maps.TrafficModel.PESSIMISTIC ou o valor de string pessimistic indica que o valor duration_in_traffic retornado deve ser maior do que o tempo de percurso real na maioria dos dias, mas dias ocasionais com condições de trânsito particularmente ruins podem exceder esse valor.
  • google.maps.TrafficModel.OPTIMISTIC ou o valor de string optimistic indica que o valor duration_in_traffic retornado deve ser menor do que o tempo de percurso real na maioria dos dias, mas dias ocasionais com condições de trânsito particularmente boas podem ser mais rápidos do que esse valor.

Veja a seguir um exemplo de DirectionsRequest para rotas de condução:

{
  origin: "Chicago, IL",
  destination: "Los Angeles, CA",
  travelMode: google.maps.TravelMode.DRIVING,
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: "optimistic"
  }
}

Sistemas de unidades

Por padrão, as rotas são calculadas e exibidas usando o sistema de unidades do país ou da região de origem. (Observação: origens indicadas usando coordenadas de latitude/longitude em vez de endereços usam sempre o padrão de unidades métricas.) Por exemplo, uma rota que parte de "Chicago, IL" para "Toronto, ONT" exibirá resultados em milhas, enquanto a rota inversa exibirá resultados em quilômetros. Substitua o sistema de unidades definindo um sistema explicitamente na solicitação por meio de um dos seguintes valores de UnitSystem:

• UnitSystem.METRIC especifica o uso do sistema métrico. As distâncias são mostradas em quilômetros.
• UnitSystem.IMPERIAL especifica o uso do sistema imperial (inglês). As distâncias são mostradas em milhas.

Observação: essa definição de sistema de unidades afeta apenas o texto exibido para o usuário. O resultado de rotas também contém valores de distância, não exibidos ao usuário, que são sempre expressos em metros.

Direcionamento de região em Directions

O serviço Directions da Google Maps API retorna resultados influenciados pelo domínio (região ou país) de onde o bootstrap de JavaScript foi carregado. (Como a maioria dos usuários carrega https://maps.google.com/, há uma definição implícita de domínio para os Estados Unidos.) Se você carrega o bootstrap de um domínio compatível diferente, obtém resultados influenciados por esse domínio. Por exemplo, pesquisas de "San Francisco" podem retornar resultados diferentes em aplicativos carregando https://maps.google.com/ (Estados Unidos) ou carregando http://maps.google.es/ (Espanha).

Também é possível configurar o serviço Directions para retornar resultados direcionados a uma região específica usando o parâmetro region. Esse parâmetro aceita um código de região especificado como uma subtag de idioma region da IANA. Na maioria das vezes, essas tags são mapeadas diretamente para valores de dois caracteres de ccTLD ("domínio de nível superior"), como "uk" em "co.uk", por exemplo. Em alguns casos, a tag region também permite códigos ISO-3166-1, que ocasionalmente diferem dos valores de ccTLD ("GB" para "Grã-Bretanha", por exemplo).

Consulte os dados de cobertura do Google Maps para determinar a abrangência do suporte a rotas no país.

Renderização de rotas

Para iniciar uma solicitação de rotas para o DirectionsService com o método route(), é necessário passar um retorno de chamada a ser executado na conclusão da solicitação do serviço. Esse retorno de chamada retorna um DirectionsResult e um código DirectionsStatus na resposta.

Status da consulta de rotas

O DirectionsStatus pode retornar os seguintes valores:

• OK indica que a resposta contém um DirectionsResult válido.
• NOT_FOUND indica que pelo menos uma das localizações especificadas na origem, no destino ou nos pontos de referência da solicitação não foram geocodificadas.
• ZERO_RESULTS indica que não foi possível encontrar rotas entre a origem e o destino.
• MAX_WAYPOINTS_EXCEEDED indica que foi fornecida uma quantidade excessiva de DirectionsWaypoint na DirectionsRequest. A quantidade máxima de pontos de referência é 8, mais a origem e o destino. Clientes da Google Maps API for Work podem usar 23 pontos de referência, mais a origem e o destino. Não são permitidos pontos de referência nas rotas de transporte público.
• INVALID_REQUEST indica que a DirectionsRequest fornecida é inválida. As causas mais comuns desse código de erro são solicitações sem origem ou destino, ou uma solicitação de transporte público que inclui pontos de referência.
• OVER_QUERY_LIMIT indica que a página enviou um número excessivo de solicitações no período permitido.
• REQUEST_DENIED indica que a página não tem permissão para usar o serviço Directions.
• UNKNOWN_ERROR indica que não foi possível processar uma solicitação de rotas devido a um erro de servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.

Verifique se a consulta de rotas retornou resultados válidos conferindo esse valor antes de processar o resultado.

Exibição do DirectionsResult

O DirectionsResult contém o resultado da consulta de rotas que você mesmo pode processar ou passar para um objeto DirectionsRenderer, que processa automaticamente a exibição do resultado em um mapa.

Para exibir um DirectionsResult usando um DirectionsRenderer, basta fazer o seguinte:

1. Crie um objeto DirectionsRenderer.
2. Chame setMap() no renderizador para associá-lo ao mapa passado.
3. Chame setDirections() no renderizador, passando DirectionsResult como mencionado acima. Como o renderizador não é um MVCObject, ele detectará automaticamente todas as alterações em suas propriedades e atualizará o mapa quando as rotas associadas forem alteradas.

O exemplo a seguir calcula rotas entre duas localizações na Route 66, com a origem e o destino definidos pelos valores "start" e "end" informados nas listas suspensas. O DirectionsRenderer processa a exibição da polilinha entre as localizações indicadas e o posicionamento dos marcadores na origem, no destino e em todos os pontos de referência, se for o caso.

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById("map"), mapOptions);
  directionsDisplay.setMap(map);
}

function calcRoute() {
  var start = document.getElementById("start").value;
  var end = document.getElementById("end").value;
  var request = {
    origin:start,
    destination:end,
    travelMode: google.maps.TravelMode.DRIVING
  };
  directionsService.route(request, function(result, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay.setDirections(result);
    }
  });
}

No corpo do HTML:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

Ver o exemplo (directions-simple.html)

O exemplo a seguir mostra as rotas usando modos de transporte diferentes entre Haight-Ashbury e Ocean Beach em São Francisco, CA:

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;
var haight = new google.maps.LatLng(37.7699298, -122.4469157);
var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  map = new google.maps.Map(document.getElementById("map"), mapOptions);
  directionsDisplay.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById("mode").value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that Javascript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay.setDirections(response);
    }
  });
}

No corpo do HTML:

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

Ver o exemplo (directions-travel-modes.html)

Além de processar a exibição da polilinha e todos os marcadores associados, um DirectionsRenderer também processa a exibição textual de rotas como uma série de etapas. Para isso, basta chamar setPanel() no DirectionsRenderer, passando o <div> para a exibição das informações. Essa ação garante a exibição das informações de direito autoral apropriadas, bem como de todos os avisos associados ao resultado.

As rotas textuais são fornecidas usando a configuração de idioma preferencial do navegador ou o idioma especificado no carregamento do JavaScript da API usando o parâmetro language. (Para obter mais informações, consulte Localização.) Nas rotas de transporte público, o horário é exibido usando o fuso horário do ponto do transporte público.

O exemplo a seguir é idêntico ao mostrado acima, mas inclui um painel <div> para a exibição de rotas:

var directionsDisplay;
var directionsService = new google.maps.DirectionsService();
var map;

function initialize() {
  directionsDisplay = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  map = new google.maps.Map(document.getElementById("map"), mapOptions);
  directionsDisplay.setMap(map);
  directionsDisplay.setPanel(document.getElementById("directionsPanel"));
}

function calcRoute() {
  var start = document.getElementById("start").value;
  var end = document.getElementById("end").value;
  var request = {
    origin:start,
    destination:end,
    travelMode: google.maps.TravelMode.DRIVING
  };
  directionsService.route(request, function(response, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      directionsDisplay.setDirections(response);
    }
  });
}

No corpo do HTML:

<div id="map" style="float:left;width:70%; height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height 100%"></div>

Ver o exemplo (directions-panel.html)

O objeto DirectionsResult

Ao enviar uma solicitação de rotas ao DirectionsService, você recebe uma resposta que consiste em um código de status e um resultado, que é um objeto DirectionsResult. O DirectionsResult é um literal de objeto com os seguintes campos:

• geocoded_waypoints[] contém uma matriz de objetos DirectionsGeocodedWaypoint, cada um contendo detalhes sobre a geocodificação da origem, do destino e dos pontos de referência.
• routes[] contém uma matriz de objetos DirectionsRoute. Cada rota indica uma forma de ir da origem ao destino fornecidos na DirectionsRequest. Geralmente, apenas uma rota é retornada para uma determinada solicitação, a menos que o campo provideRouteAlternatives seja definido como true, permitindo o retorno de várias rotas.

Pontos de referência geocodificados de rotas

Um DirectionsGeocodedWaypoint contém detalhes sobre a geocodificação da origem, do destino e dos pontos de referência.

O DirectionsGeocodedWaypoint é um literal de objeto com os seguintes campos:

• geocoder_status indica o código de status resultante da operação de geocodificação. Esse campo pode conter os seguintes valores:
  • "OK" indica que nenhum erro ocorreu; o endereço foi analisado e pelo menos um código geográfico foi retornado.
  • ZERO_RESULTS indica que o código geográfico foi bem-sucedido, mas não retornou resultados. Isso poderá ocorrer se o geocodificador receber um address que não existe.

• partial_match indica que o geocodificador não retornou uma correspondência exata para a solicitação original, mas conseguiu corresponder parte do endereço solicitado. Pode ser recomendável verificar se a solicitação original inclui erros de ortografia e/ou um endereço incompleto.

  Correspondências parciais ocorrem com mais frequência para endereços que não existem na localidade onde você passou a solicitação. Elas também podem ser retornadas quando uma solicitação corresponde a dois ou mais locais na mesma localidade. Por exemplo, "21 Henr St, Bristol, UK" retornará uma correspondência parcial para Henry Street e Henrietta Street. Observe que, se uma solicitação incluir um componente de endereço com um erro ortográfico, o serviço de geocodificação poderá sugerir um endereço alternativo. Sugestões acionadas dessa maneira também serão marcadas como correspondências parciais.

• place_id é um identificador único de um local que pode ser usado com outras Google APIs. Por exemplo, use place_id com a biblioteca Google Places API para obter detalhes sobre um estabelecimento local, como número de telefone, horário de funcionamento, comentários de usuários e muito mais. Consulte a visão geral de IDs de local.
• types[] é uma matriz indicando o tipo do resultado retornado. Essa matriz contém um conjunto de zero ou mais tags que identificam o tipo de recurso retornado no resultado. Por exemplo, um código geográfico de "Chicago" retorna "locality", que indica que "Chicago" é uma cidade, e retorna também "political", indicando que é uma entidade política.

Rotas

O objeto legado DirectionsTrip foi renomeado para DirectionsRoute. Observe que agora uma rota é a jornada completa, do início ao fim, em vez de simplesmente um trecho de uma rota pai.

Uma DirectionsRoute contém um único resultado da origem e do destino especificados. Essa rota pode consistir em um ou mais trechos (do tipo DirectionsLeg), dependendo da especificação de pontos de referência. A rota também contém informações de direitos autorais e avisos que devem ser exibidas ao usuário juntamente com as rotas.

A DirectionsRoute é um literal de objeto com os seguintes campos:

• legs[] contém uma matriz de objetos DirectionsLeg. Cada objeto contém informações sobre um trecho da rota entre duas localizações da rota especificada. É definido um trecho separado para cada ponto de referência ou destino especificado. (Uma rota sem pontos de referência contém exatamente uma DirectionsLeg.) Cada trecho consiste em uma série de DirectionStep.
• waypoint_order contém uma matriz que indica a ordem dos pontos de referência na rota calculada. Se optimizeWaypoints: true foi passado para DirectionsRequest, a matriz pode conter uma ordem alterada.
• overview_path contém uma matriz de LatLng que representa um caminho aproximado (suavizado) das rotas resultantes.
• overview_polyline contém um único objeto points que inclui uma representação de polilinha codificada da rota. Essa polilinha é um caminho aproximado (suavizado) da rota resultante.
• bounds contém um LatLngBounds, indicando os limites da polilinha ao longo dessa rota específica.
• copyrights contém o texto de direitos autorais a ser exibido para essa rota.
• warnings[] contém um conjunto de avisos a serem exibidos ao mostrar a rota. Se você não usa o objeto DirectionsRenderer fornecido, deve processar e exibir esses avisos por conta própria.
• fare contém o total das passagens (ou seja, o custo total das tarifas) para essa rota. Essa propriedade é retornada somente para solicitações de transporte público e somente para rotas quando as informações de passagens estão disponíveis para todos os trechos do percurso. Essas informações incluem:
  • currency: um código de moeda ISO 4217 que indica a moeda da quantia.
  • value: o total de passagens na moeda especificada com o parâmetro acima.

Trechos das rotas

O objeto legado DirectionsRoute foi renomeado para DirectionsLeg.

Um DirectionsLeg define um único trecho da jornada da origem ao destino na rota calculada. Rotas que não contêm pontos de referência terão um só "trecho", mas rotas que definem um ou mais pontos de referência terão um ou mais trechos, correspondendo aos trechos específicos da jornada.

O DirectionsLeg é um literal de objeto com os seguintes campos:

• steps[] contém uma matriz de objetos DirectionsStep com informações sobre cada etapa separada do trecho da jornada.

• distance indica a distância total percorrida nesse trecho como um objeto Distance no seguinte formato:

  • value indica a distância em metros
  • text contém uma representação da distância em string, que por padrão é exibida nas unidades usadas na origem. (Por exemplo, milhas são usadas para origens nos Estados Unidos.) Substitua esse sistema de unidades definindo especificamente um UnitSystem na consulta original. Observe que, independentemente do sistema de unidades usado, o campo distance.value sempre contém um valor expresso em metros.

  Esses campos podem ser indefinidos se a distância é desconhecida.

• duration indica a duração total desse trecho como um objeto Duration no seguinte formato:

  • value indica a duração em segundos.
  • text contém uma representação da duração em string.

  Esses campos podem ser indefinidos se a duração é desconhecida.

• duration_in_traffic indica a duração total do trecho considerando as condições de trânsito atuais. duration_in_traffic somente é retornada para clientes da Google Maps API for Work quando dados de tráfego estão disponíveis, mode é definido como driving e departureTime é incluído como parte do campo drivingOptions na solicitação. duration_in_traffic contém os seguintes campos:

  • value indica a duração em segundos.
  • text contém uma representação legível da duração.
• arrival_time contém uma estimativa do tempo de chegada para o trecho. Essa propriedade é retornada apenas para rotas de transporte público. O resultado é retornado como um objeto Time com três propriedades:
  • value é o tempo especificado como um objeto Date do JavaScript.
  • text é o tempo especificado como uma string. O tempo é exibido no fuso horário da parada do transporte público.
  • time_zone contém o fuso horário da estação. O valor é o nome do fuso horário conforme a definição do banco de dados de fusos horários da IANA. Por exemplo: "America/New_York".
• departure_time contém uma estimativa do tempo de partida do trecho, especificada como um objeto Time. O departure_time só está disponível para rotas de transporte público.
• start_location contém a LatLng da origem do trecho. Como o serviço Directions calcula rotas entre localizações usando a opção de transporte mais próxima (geralmente uma via) nos pontos de partida e chegada, start_location pode ser diferente da origem fornecida para o trecho se, por exemplo, não há uma estrada próxima da origem.
• end_location contém a LatLng do destino do trecho. Como DirectionsService calcula rotas entre localizações usando a opção de transporte mais próxima (geralmente uma via) nos pontos de partida e chegada, end_location pode ser diferente do destino fornecido para o trecho se, por exemplo, não há uma estrada próxima do destino.
• start_address contém o endereço legível (normalmente uma rua) resultante da geocodificação inversa da partida do trecho.
• end_address contém o endereço legível (normalmente uma rua) resultante da geocodificação inversa da chegada do trecho.

Etapas das rotas

Uma DirectionsStep é a menor unidade de uma rota e contém uma única etapa, que descreve uma única instrução específica na jornada. Por exemplo: “Vire à esquerda na W. 4th St." A etapa não só descreve a instrução, como também contém informações de distância e duração indicando como a etapa está relacionada à etapa seguinte. Por exemplo, uma etapa "Siga para I-80 West" pode conter uma duração de "37 quilômetros" e "40 minutos", indicando que a próxima etapa está a 37 quilômetros/40 minutos da presente etapa.

Ao usar o serviço Directions para obter rotas de transporte público, a matriz de etapas inclui informações específicas de transporte público adicionais no formato de um objeto transit. Se a rota inclui diversos modos de transporte, são fornecidas instruções detalhadas para etapas de caminhada ou condução em uma matriz steps[]. Por exemplo, uma etapa de caminhada incluirá instruções da localização de partida à de chegada: "Ande até Innes Ave & Fitch St". Essa etapa inclui instruções detalhadas de caminhada para a rota na matriz steps[]. Por exemplo: "Siga na direção noroeste", "Vire à esquerda no Arelious Walker" e "Vire à esquerda na Innes Ave".

A DirectionsStep é um literal de objeto com os seguintes campos:

• html_instructions contém instruções para a etapa em uma string de texto.
• distance contém a distância percorrida nesta etapa até a próxima etapa como um objeto Distance. (Veja a descrição em DirectionsLeg acima.) Esse campo poderá ser indefinido se a distância for desconhecida.
• duration contém uma estimativa do tempo necessário para executar esta etapa até a próxima etapa como um objeto Duration. (Veja a descrição em DirectionsLeg acima.) Esse campo poderá ser indefinido se a duração for desconhecida.
• start_location contém a LatLng geocodificada do ponto de partida da etapa.
• end_location contém a LatLng do ponto de chegada da etapa.
• polyline contém um único objeto points que inclui uma representação de polilinha codificada da etapa. Essa polilinha é um caminho aproximado (suavizado) da etapa.
• steps[] é um literal de objeto DirectionsStep que contém instruções detalhadas para etapas de caminhada ou condução em rotas de transporte público. Subetapas só estão disponíveis para rotas de transporte público.
• travel_mode contém o TravelMode usado nessa etapa. As rotas de transporte público podem incluir uma combinação de rotas de caminhada e transporte público.
• path contém uma matriz de LatLngs descrevendo a rota dessa etapa.
• transit contém informações específicas de transporte público, como horários de partida e chegada e o nome da linha de transporte público.

Informações específicas de transporte público

Rotas de transporte público retornam informações adicionais que não são relevantes para outros modos de transporte. Essas propriedades adicionais são expostas pelo objeto TransitDetails, retornado como uma propriedade de DirectionsStep. No objeto TransitDetails, é possível extrair informações adicionais para os objetos TransitStop, TransitLine, TransitAgency e VehicleType, como descrito a seguir.

Detalhes de transporte público

O objeto TransitDetails expõe as seguintes propriedades:

• arrival_stop contém um objeto TransitStop que representa a estação/parada de chegada com as seguintes propriedades:
  • name o nome da estação/parada. Por exemplo: "Union Square".
  • location é a localização da estação/parada, representada como uma LatLng.
• departure_stop contém um objeto TransitStop que representa a estação/parada de partida.
• arrival_time contém o horário da chegada, especificado como um objeto Time com três propriedades:
  • value é o tempo especificado como um objeto Date do JavaScript.
  • text é o tempo especificado como uma string. O tempo é exibido no fuso horário da parada do transporte público.
  • time_zone contém o fuso horário da estação. O valor é o nome do fuso horário conforme a definição do banco de dados de fusos horários da IANA. Por exemplo: "America/New_York".
• departure_time contém o horário de partida, especificado como um objeto Time.
• headsign especifica a direção na qual você viaja nessa linha, conforme indicado no veículo ou na parada de partida. Essa parada é, com frequência, a estação terminal.
• headway especifica o número esperado de segundos entre partidas da mesma parada no momento, se disponível. Por exemplo, com um valor de 600 para headway, você terá uma espera de 10 minutos se perder o ônibus.
• line contém um literal de objeto TransitLine, com informações sobre a linha de transporte público usada nessa etapa. TransitLine fornece o nome e operador da linha, juntamente com outras propriedades descritas na documentação de referência de TransitLine.
• num_stops contém o número de paradas da etapa. Esse número inclui a parada de chegada, mas não a de partida. Por exemplo, se a sua rota envolve partir da parada A, passar pelas paradas B e C para então chegar na parada D, num_stops retorna 3.

Linha de transporte público

O objeto TransitLine expõe as seguintes propriedades:

• name contém o nome completo da linha. Por exemplo: "7 Avenue Express" ou "14th St Crosstown".
• short_name contém o nome curto da linha. Normalmente, esse valor é um número de linha, como "2" ou "M14".
• agencies contém uma matriz do tipo TransitAgency. Cada objeto TransitAgency oferece informações sobre o operador da linha, incluindo as seguintes propriedades:
  • name contém o nome da agência de transporte público.
  • url contém o URL da agência.
  • phone contém o número de telefone da agência.

  Se você está renderizando as rotas de transporte público manualmente, em vez de usar o objeto DirectionsRenderer, precisa exibir os nomes e URLs das agências de transporte público que participam nos resultados da viagem.

• url contém o URL da linha de transporte público, como fornecido pela agência de transporte público.
• icon contém um URL do ícone associado à linha. A maioria das cidades usa ícones genéricos, que variam de acordo com o tipo de veículo. Algumas linhas de transporte público, como o sistema de metrô de Nova Iorque, têm ícones específicos para essa linha.
• color contém a cor normalmente usada para a sinalização da linha. A cor será especificada como uma string hexadecimal, como: #FF0033.
• text_color contém a cor de texto normalmente usada para a sinalização da linha. A cor será especificada como uma string hexadecimal.
• vehicle contém um objeto Vehicle que inclui as seguintes propriedades:
  • name contém o nome do veículo da linha. Por exemplo: "Metrô".
  • type contém o tipo de veículo usado na linha. Consulte a documentação sobre tipo de veículo para obter uma lista completa dos valores permitidos.
  • icon contém um URL do ícone normalmente associado a esse tipo de veículo.
  • local_ icon contém um URL do ícone associado localmente a esse tipo de veículo.

Tipo de veículo

O objeto VehicleType expõe as seguintes propriedades:

Valor	Definição
VehicleType.RAIL	Trem.
VehicleType.METRO_RAIL	Metrô leve.
VehicleType.SUBWAY	Metrô subterrâneo.
VehicleType.TRAM	Bonde.
VehicleType.MONORAIL	Monotrilho.
VehicleType.HEAVY_RAIL	Trem pesado.
VehicleType.COMMUTER_TRAIN	Trem suburbano.
VehicleType.HIGH_SPEED_TRAIN	Trem de alta velocidade.
VehicleType.BUS	Ônibus.
VehicleType.INTERCITY_BUS	Ônibus intermunicipal.
VehicleType.TROLLEYBUS	Trole.
VehicleType.SHARE_TAXI	Um transporte compartilhado é um veículo que pode deixar e coletar passageiros em qualquer ponto de sua rota.
VehicleType.FERRY	Balsa.
VehicleType.CABLE_CAR	Um veículo que opera por meio de um cabo, normalmente terrestre. Bondes aéreos podem ser do tipo VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT	Um bonde aéreo.
VehicleType.FUNICULAR	Um veículo puxado por cabo em declives acentuados. Um funicular geralmente consiste em dois vagões que funcionam como contrapesos um para o outro.
VehicleType.OTHER	Todos os demais veículos retornarão esse tipo.

Inspeção de DirectionsResults

Os componentes de DirectionsResults — DirectionsRoute, DirectionsLeg, DirectionsStep e TransitDetails — podem ser examinados e usados durante a análise das respostas de rotas.

Importante: Se você está renderizando as rotas de transporte público manualmente, em vez de usar o objeto DirectionsRenderer, precisa exibir os nomes e URLs das agências de transporte público que participam nos resultados da viagem.

O exemplo a seguir plota rotas de caminhada para algumas atrações turísticas na cidade de Nova York. Examinamos a DirectionsStep da rota para adicionar marcadores em cada etapa e anexar informações em uma InfoWindow com texto de instruções para a etapa.

Como estamos calculando direções de caminhada, também exibimos todos os avisos para o usuário em um painel <div> separado.

var map;
var directionsDisplay;
var directionsService;
var stepDisplay;
var markerArray = [];

function initialize() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById("map"), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsDisplay = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById("start").value;
  var end = document.getElementById("end").value;
  var request = {
      origin: start,
      destination: end,
      travelMode: google.maps.TravelMode.WALKING
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == google.maps.DirectionsStatus.OK) {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsDisplay.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

No corpo do HTML:

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

Ver o exemplo (directions-complex.html)

Usar pontos de referência em rotas

Como observado em DirectionsRequest, também é possível especificar pontos de referência (do tipo DirectionsWaypoint) no cálculo de rotas usando o serviço Directions para rotas de caminhada, bicicleta ou condução. Os pontos de referência não estão disponíveis em rotas de transporte público. Os pontos de referência permitem que você calcule rotas ao longo de localizações adicionais. A rota retornada passa pelos pontos de referência informados.

A quantidade máxima de pontos de referência é 8, mais a origem e o destino. Clientes da Google Maps API for Work podem usar 23 pontos de referência, mais a origem e o destino. Não são permitidos pontos de referência nas rotas de transporte público.

Um ponto de referência consiste nos seguintes campos:

• location (obrigatório) especifica o endereço do ponto de referência.
• stopover (opcional) indica se o ponto de referência é uma parada real na rota (true) ou apenas uma preferência para que a rota passe por essa localização (false). Por padrão, paradas são true.

Por padrão, o serviço Directions calcula uma rota pelos pontos de referência fornecidos, na ordem em que eles são apresentados. Opcionalmente, passe optimizeWaypoints: true na DirectionsRequest para permitir que o serviço Directions otimize a rota fornecida organizando os pontos de referência em uma ordem mais eficiente. (Essa otimização é uma aplicação do problema do caixeiro-viajante.) Todos os pontos de referência devem ser paradas para que o serviço Directions otimize a rota.

Se você instrui o serviço Directions a otimizar a ordem dos pontos de referência, a ordem é retornada no campo waypoint_order do objeto DirectionsResult.

O exemplo a seguir calcula rotas através dos Estados Unidos usando diversos pontos de partida, chegada e referência. (Para selecionar vários pontos de referência, pressione Ctrl+clique durante a seleção de itens na lista.) Observe que examinamos routes.start_address e routes.end_address para obtermos o texto de cada ponto de partida e chegada da rota.

function initMap() {
  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer;
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 6,
    center: {lat: 41.85, lng: -87.65}
  });
  directionsDisplay.setMap(map);

  document.getElementById('submit').addEventListener('click', function() {
    calculateAndDisplayRoute(directionsService, directionsDisplay);
  });
}

function calculateAndDisplayRoute(directionsService, directionsDisplay) {
  var waypts = [];
  var checkboxArray = document.getElementById('waypoints');
  for (var i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true
      });
    }
  }

  directionsService.route({
    origin: document.getElementById('start').value,
    destination: document.getElementById('end').value,
    waypoints: waypts,
    optimizeWaypoints: true,
    travelMode: google.maps.TravelMode.DRIVING
  }, function(response, status) {
    if (status === google.maps.DirectionsStatus.OK) {
      directionsDisplay.setDirections(response);
      var route = response.routes[0];
      var summaryPanel = document.getElementById('directions-panel');
      summaryPanel.innerHTML = '';
      // For each route, display summary information.
      for (var i = 0; i < route.legs.length; i++) {
        var routeSegment = i + 1;
        summaryPanel.innerHTML += '<b>Route Segment: ' + routeSegment +
            '</b><br>';
        summaryPanel.innerHTML += route.legs[i].start_address + ' to ';
        summaryPanel.innerHTML += route.legs[i].end_address + '<br>';
        summaryPanel.innerHTML += route.legs[i].distance.text + '<br><br>';
      }
    } else {
      window.alert('Directions request failed due to ' + status);
    }
  });
}

Ver o exemplo (directions-waypoints.html).

Rotas arrastáveis

Os usuários podem modificar rotas de bicicleta, caminhada ou condução usando um DirectionsRenderer dinamicamente, se arrastáveis, permitindo que o usuário selecione e altere rotas clicando e arrastando os caminhos resultantes no mapa. Indique se a exibição do renderizador permite rotas arrastáveis definindo a propriedade draggable como true. Rotas de transporte público não podem ser arrastáveis.

Quando uma rota é arrastável, o usuário pode selecionar qualquer ponto (ou ponto de referência) do caminho no resultado renderizado e mover o componente indicado para uma nova localização. O DirectionsRenderer é atualizado dinamicamente para mostrar o caminho modificado. Quando o ponto é liberado, um ponto de referência temporário é adicionado ao mapa (indicado por um pequeno marcador branco). A seleção e a movimentação de um segmento de caminho alteram esse trecho da rota. A seleção e a movimentação de um marcador de ponto de referência (incluindo os pontos de partida e de chegada) alteram os trechos da rota que passam pelo ponto de referência.

Como as rotas arrastáveis são modificadas e renderizadas no lado do cliente, monitore e processe o evento directions_changed no DirectionsRenderer para ser notificado quando o usuário modificar as rotas exibidas.

O código a seguir mostra uma viagem de ida e volta de Sidnei através do sertão australiano de New South Wales. O código monitora o evento directions_changed para atualizar a distância total de todos os trechos da jornada.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: -24.345, lng: 134.46}  // Australia.
  });

  var directionsService = new google.maps.DirectionsService;
  var directionsDisplay = new google.maps.DirectionsRenderer({
    draggable: true,
    map: map,
    panel: document.getElementById('right-panel')
  });

  directionsDisplay.addListener('directions_changed', function() {
    computeTotalDistance(directionsDisplay.getDirections());
  });

  displayRoute('Perth, WA', 'Sydney, NSW', directionsService,
      directionsDisplay);
}

function displayRoute(origin, destination, service, display) {
  service.route({
    origin: origin,
    destination: destination,
    waypoints: [{location: 'Cocklebiddy, WA'}, {location: 'Broken Hill, NSW'}],
    travelMode: google.maps.TravelMode.DRIVING,
    avoidTolls: true
  }, function(response, status) {
    if (status === google.maps.DirectionsStatus.OK) {
      display.setDirections(response);
    } else {
      alert('Could not display directions due to: ' + status);
    }
  });
}

function computeTotalDistance(result) {
  var total = 0;
  var myroute = result.routes[0];
  for (var i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }
  total = total / 1000;
  document.getElementById('total').innerHTML = total + ' km';
}

Ver o exemplo (directions-draggable.html).