Serviço Directions

Observação: bibliotecas do lado do servidor

Nesta página, descrevemos o serviço do lado do cliente disponível com a API Maps JavaScript. Se você quiser trabalhar com o serviço da Web do Google Maps no seu servidor, consulte o Cliente Node.js para serviços do Google Maps (link em inglês). A página no link também apresenta os clientes Java, Python e Go para serviços do Google Maps.

Visão geral

Consulte também a Referência da API Maps JavaScript: Directions

Você pode calcular rotas (com diferentes meios de transporte) usando o objeto DirectionsService. Ele se comunica com o serviço Directions da API Google Maps, que recebe solicitações de rotas e retorna um caminho eficiente. O tempo de viagem é o principal fator a ser otimizado, mas outros fatores, como distância, quantidade de curvas etc., podem ser considerados. Esses resultados de rota podem ser controlados manualmente ou renderizados pelo objeto DirectionsRenderer.

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 Place.

O serviço Directions pode retornar rotas em várias partes usando uma série de waypoints. As rotas são mostradas como uma polilinha desenhando o trajeto 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 ponte de Williamsburg".

Começar

Antes de usar o serviço Directions na API Maps JavaScript, verifique se a API Directions está ativada no console do Google Cloud, no mesmo projeto configurado para a API Maps JavaScript.

Para ver a lista de APIs ativadas:

1. Acesse o console do Google Cloud.
2. Clique no botão Selecionar um projeto, escolha o que você configurou para a API Maps JavaScript e selecione Abrir.
3. Na lista de APIs do Painel, procure API Directions.
4. Se achar a API na lista, pode prosseguir. Caso contrário, faça o seguinte para ativar a API:
   1. Na parte de cima da página, selecione ATIVAR API para abrir a guia Biblioteca. Outra opção é selecionar Biblioteca no menu lateral esquerdo.
   2. Pesquise e selecione API Directions na lista de resultados.
   3. Clique em ATIVAR. Quando o processo terminar, a API Directions vai aparecer na lista de APIs do Painel.

Preços e políticas

Preços

Em 16 de julho de 2018, um novo plano de pagamento por uso entrou em vigor para as APIs Maps, Routes e Places. Se quiser saber mais sobre os novos limites de preço e uso do serviço JavaScript Directions, consulte Utilização e faturamento referente à API Directions.

Políticas

O uso do serviço Directions precisa estar de acordo com as políticas descritas para a API Directions.

Solicitações do serviço Directions

O acesso ao serviço Directions é assíncrono porque a API Google Maps precisa chamar um servidor externo. Por isso, você precisa passar um método de callback a ser executado quando a solicitação for concluída. Esse método de callback processa os resultados. O serviço Directions pode retornar mais de um itinerário como uma matriz de routes[] diferentes.

Para usar rotas na API Maps JavaScript, crie um objeto do tipo DirectionsService e chame DirectionsService.route() para iniciar uma solicitação ao serviço Directions, transmitindo um literal de objeto DirectionsRequest que contém os termos de entrada e um método de callback a ser executado ao receber a resposta.

O literal do 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,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

Esses campos são explicados a seguir:

• origin (obrigatório) especifica o local de início a partir de onde a rota deve ser calculada. Esse valor pode ser especificado como uma String (por exemplo, "Chicago, IL"), um valor de LatLng ou um objeto Place. Se você usar um objeto Place, poderá especificar um ID de lugar, uma string de consulta ou um local LatLng. Recupere IDs de locais dos serviços Geocoding, Place Search e Place Autocomplete na API Maps JavaScript. Para um exemplo que usa IDs de lugar do Place Autocomplete, consulte Place Autocomplete e Directions.
• destination (obrigatório) especifica o local final para que a rota deve ser calculada. As opções são as mesmas do campo origin descrito acima.
• travelMode (obrigatório) especifica que modo de transporte usar ao calcular a rota. Os valores válidos são especificados em Meios de transporte abaixo.
• transitOptions (opcional): especifica valores utilizados apenas para solicitações em que travelMode é TRANSIT. Os valores válidos são descritos em Opções de transporte público abaixo.
• drivingOptions (opcional): especifica valores utilizados apenas para solicitações em que travelMode é DRIVING. Os valores válidos são descritos em Opções de condução abaixo.

• unitSystem (opcional) especifica que sistema de medidas usar ao mostrar resultados. Os valores válidos são especificados em Sistemas de medidas abaixo.

• waypoints[] (opcional) especifica uma matriz de DirectionsWaypoints. Os waypoints mudam um trajeto desviando-o por localizações específicas. Um waypoint é especificado como um literal de objeto com os campos mostrados abaixo:

  • location especifica o local do waypoint, como um LatLng, um objeto Place ou uma String que será geocodificada.
  • stopover é um valor booleano que indica que o waypoint é uma parada no trajeto, o que resulta na divisão do trajeto em dois.

  Para mais informações sobre waypoints, consulte Usar waypoints nos trajetos abaixo.

• optimizeWaypoints (opcional) especifica que o trajeto que usa os waypoints fornecidos pode ser otimizado reorganizando os waypoints em uma ordem mais eficiente. Se true, o serviço Directions vai retornar waypoints reorganizado em um campo waypoint_order. Para mais informações, consulte Usar waypoints nos trajetos abaixo.
• provideRouteAlternatives (opcional), quando este campo é definido como true, ele especifica que o serviço Directions pode fornecer mais de uma opção de trajeto na resposta. Fornecer opções de trajeto pode aumentar o tempo de resposta do servidor. Disponível apenas para solicitações sem waypoints intermediários.
• avoidFerries (opcional), quando definido como true, indica que os trajetos calculados precisam evitar balsas, se possível.
• avoidHighways (opcional), quando este campo é definido como true, ele indica que os trajetos calculados devem evitar as principais rodovias, se possível.
• avoidTolls (opcional), quando este campo é definido como true, ele indica que os trajetos calculados devem evitar vias com pedágios, se possível.
• region (opcional) especifica o código regional, apresentado como um valor ccTLD ("domínio de nível superior") de dois caracteres. Para mais informações, consulte Direcionamento de região abaixo.

Observação: o campo durationInTraffic foi descontinuado. Anteriormente, ele era usado para os clientes do Plano Premium da Plataforma Google Maps especificarem se as condições atuais de trânsito deveriam ser consideradas no resultado. Agora, use o campo drivingOptions.

Confira abaixo 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: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Meios de transporte

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

• DRIVING (Padrão) indica rotas de carro padrão usando a rede de estradas.
• BICYCLING solicita rotas de bicicleta usando ciclovias e ruas preferenciais.
• TRANSIT solicita rotas usando trajetos de transporte público.
• WALKING solicita rotas a pé usando faixas de pedestres e calçadas.

Consulte os detalhes da cobertura da Plataforma Google Maps para determinar o nível de compatibilidade de um país com as rotas. Se você solicitar rotas para uma região em que esse tipo de rota não está disponível, a resposta vai retornar o DirectionsStatus+"ZERO_RESULTS".

Observação: é possível que as rotas a pé não incluam caminhos claros para pedestres. Nesse caso, elas retornam avisos no DirectionsResult. Esses avisos devem sempre ser mostrados ao usuário. Se você não usar o DirectionsRenderer padrão, deverá garantir que os avisos sejam exibidos.

Opções de transporte público

As opções disponíveis para uma solicitação de rotas variam entre os meios de transporte. Ao solicitar rotas de transporte público, avoidHighways, avoidTolls, waypoints[] e optimizeWaypoints serão ignorados. Use o literal do objeto TransitOptions para definir opções de trajeto específicas para transporte público.

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

O literal do 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. O horário de partida é ignorado quando o de chegada é informado.
• departureTime (opcional) especifica o horário de partida desejado como um objeto Date. departureTime é ignorado quando arrivalTime é informado. Se não for especificado nenhum valor para departureTime ou arrivalTime, o valor padrão será o horário atual (agora).
• modes[] (opcional) é uma matriz que contém um ou mais literais de objeto TransitMode. Esse campo só é incluído em solicitações com uma chave de API. Cada TransitMode especifica um meio de transporte preferencial. Estes são os valores permitidos:
  • BUS indica preferência ao deslocamento por ônibus no trajeto calculado.
  • RAIL indica preferência ao deslocamento por trem, bonde, veículo leve sobre trilhos (VLT) e metrô no trajeto calculado.
  • SUBWAY indica preferência ao deslocamento por metrô no trajeto calculado.
  • TRAIN indica preferência ao deslocamento por trem no trajeto calculado.
  • TRAM indica preferência ao deslocamento por bonde e veículo leve sobre trilhos (VLT) no trajeto calculado.
• routingPreference (opcional) especifica preferências para trajetos por transporte público. Com esse recurso, é possível direcionar as opções retornadas em vez de aceitar o melhor trajeto padrão escolhido pela API. Só é possível especificar esse campo quando a solicitação inclui uma chave de API. Estes são os valores permitidos:
  • FEWER_TRANSFERS indica preferência por um número limitado de transferências no trajeto calculado.
  • LESS_WALKING indica preferência por pouca caminhada no trajeto calculado.

Confira uma amostra do DirectionsRequest por transporte público:

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

Opções de condução

Você pode especificar opções de trajeto para rotas de carro usando o objeto DrivingOptions.

O objeto DrivingOptions contém estes 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 desejado como um objeto Date. O valor precisa ser definido como o horário atual ou no futuro, nunca no passado. A API converte todas as datas para UTC e assim garante o processamento consistente entre fusos horários. Para clientes do Plano Premium da Plataforma Google Maps, se você incluir departureTime na solicitação, a API vai retornar o melhor trajeto com base nas condições de trânsito esperadas no momento e incluir o horário previsto no trânsito (duration_in_traffic) na resposta. Se você não especificar um horário de partida (ou seja, a solicitação não inclui drivingOptions), será retornado um trajeto que normalmente é bom, sem considerar as condições de trânsito.
• trafficModel (opcional) especifica as premissas a serem usadas no cálculo do tempo em trânsito. Essa configuração afeta o valor retornado no campo duration_in_traffic na resposta, que contém o tempo previsto no trânsito com base nas médias históricas. O padrão é bestguess. Estes são os valores permitidos:
  • bestguess (padrão) indica que o valor retornado de duration_in_traffic deve ser a melhor estimativa do tempo de viagem, considerando as informações de condições de trânsito históricas e em tempo real. Quanto mais próximo de agora for o departureTime, mais importante será o trânsito em tempo real.
  • pessimistic indica que o valor retornado de duration_in_traffic deve ser maior que o tempo de viagem na maioria dos dias, embora ele possa ser maior em alguns dias em que as condições de trânsito são particularmente ruins.
  • optimistic indica que o valor retornado de duration_in_traffic deve ser menor que o tempo de viagem na maioria dos dias, embora ele possa ser menor em alguns dias em que as condições de trânsito são particularmente boas.

Atenção: quando o horário de partida não é especificado, as opções de trajeto e duração se baseiam na rede viária e nas condições médias de trânsito (independente da hora), não nas condições de trânsito atuais. Consequentemente, os trajetos podem incluir vias que estão temporariamente fechadas. Os resultados das solicitações variam por causa de mudanças na malha rodoviária, de atualizações nas condições de trânsito e da natureza distribuída do serviço. Eles também variam entre trajetos quase equivalentes a qualquer momento ou frequência.

Observação: para garantir que sua solicitação use as informações do trânsito em tempo real, defina o departureTime como agora. As solicitações que usam informações do trânsito têm uma taxa mais alta. Saiba mais sobre o faturamento dos produtos da Plataforma Google Maps.

Veja abaixo um exemplo de DirectionsRequest para rotas de carro:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  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 mostradas usando o sistema de unidades do país ou da região de origem. Observação: locais de origens expressos com coordenadas de latitude/longitude em vez de endereços sempre terão como padrão unidades métricas. Por exemplo, um trajeto de "Chicago, IL" para "Toronto, ONT" mostra resultados em milhas, enquanto o trajeto inverso mostra resultados em quilômetros. É possível substituir esse sistema de medidas configurando outro sistema explicitamente na solicitação usando um dos valores de UnitSystem a seguir:

• 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 configuração do sistema de medidas afeta apenas o texto mostrado ao usuário. O resultado de rotas também contém valores de distância, não mostrados ao usuário, que são sempre expressos em metros.

Direcionamento de região no Directions

O serviço Directions da API Google Maps retorna resultados de endereço influenciados pelo domínio (região ou país) de que você carregou o bootstrap do JavaScript. Como a maioria dos usuários carregam https://maps.googleapis.com/, ele define um domínio implícito 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 por "São Francisco" podem retornar resultados diferentes para aplicativos que carregam https://maps.googleapis.com/ (Estados Unidos) e aplicativos que carregam http://maps.google.es/ (Espanha).

Você também pode definir o serviço Directions para retornar resultados direcionados para uma região específica usando o parâmetro region. Esse parâmetro usa um código regional, especificado como uma subtag de região Unicode de dois caracteres (não numéricos). Na maioria dos casos, essas tags são convertidas diretamente em valores de dois caracteres ccTLD ("domínio de nível superior"), como "uk" em "co.uk", por exemplo. Em alguns casos, a tag de region também é compatível com códigos ISO-3166-1, que, às vezes, diferem dos valores ccTLD ("GB" para "Grã-Bretanha", por exemplo).

Quando usar o parâmetro region:

• Especifique apenas um país ou região. Vários valores são ignorados e podem resultar em uma solicitação com falha.
• Use apenas subtags de região de dois caracteres (formato CLDR Unicode). Todas as outras entradas vão resultar em erros.

O direcionamento de região é compatível apenas com países e regiões que aceitam rotas. Consulte os detalhes da cobertura da Plataforma Google Maps para ver a cobertura internacional da API Directions.

Renderização das rotas

Iniciar uma solicitação de rota para o DirectionsService com o método route() requer a passagem de um retorno de chamada que será executado na conclusão da solicitação de serviço. Essa chamada de retorno mostra um código de DirectionsResult e de DirectionsStatus na resposta.

Status da consulta das rotas

O DirectionsStatus pode retornar os seguintes valores:

• OK indica que a resposta contém um DirectionsResult válido.
• NOT_FOUND indica que não foi possível geocodificar pelo menos um dos locais especificados na origem, no destino ou nos waypoints da solicitação.
• ZERO_RESULTS indica que não foi possível encontrar nenhum trajeto entre a origem e o destino.
• MAX_WAYPOINTS_EXCEEDED indica que muitos campos DirectionsWaypoint foram fornecidos no DirectionsRequest. Consulte a seção abaixo sobre limites de waypoints.
• MAX_ROUTE_LENGTH_EXCEEDED indica que o trajeto solicitado é muito longo e não pode ser processado. Esse erro ocorre quando rotas mais complexas são retornadas. Tente reduzir o número de waypoints, curvas ou instruções.
• INVALID_REQUEST indica que o DirectionsRequest fornecido era inválido. 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 waypoints.
• OVER_QUERY_LIMIT indica que a página da Web enviou solicitações em excesso dentro do período permitido.
• REQUEST_DENIED indica que a página da Web 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 rota devido a um erro do servidor. Se você tentar novamente, a solicitação poderá ser bem-sucedida.

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

Mostrar a interface DirectionsResult

O DirectionsResult contém o resultado da consulta de rota, que você pode manipular manualmente ou passar para um objeto DirectionsRenderer, que pode manipulá-lo automaticamente mostrando o resultado em um mapa.

Para mostrar um DirectionsResult usando um DirectionsRenderer, faça o seguinte:

1. Crie um objeto DirectionsRenderer.
2. Chame setMap() no renderizador para vinculá-lo ao mapa passado.
3. Chame setDirections() no renderizador, passando a ele o DirectionsResult, como indicado acima. Como o renderizador é um MVCObject, ele vai detectar automaticamente quaisquer mudanças nas propriedades e atualizará o mapa quando suas rotas associadas forem alteradas.

O exemplo a seguir calcula rotas entre dois locais na Route 66, onde a origem e o destino são definidos pelos valores de "start" e "end" especificados nas listas suspensas. O DirectionsRenderer é responsável pela exibição da polilinha entre os locais indicados e por posicionar os marcadores na origem, destino e waypoints, se aplicável.

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsRenderer.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>

Exemplo

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

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.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 == 'OK') {
      directionsRenderer.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>

Exemplo

Um DirectionsRenderer não somente manipula a exibição da polilinha e dos marcadores associados, como também pode manipular a exibição textual de rotas na forma de uma série de etapas. Para fazer isso, chame setPanel() no DirectionsRenderer, transmitindo o <div> em que as informações serão mostradas. 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 serão fornecidas no idioma preferido do navegador ou no idioma especificado ao carregar a API JavaScript usando o parâmetro language. Para mais informações, consulte Localização. Nas rotas de transporte público, o horário é mostrado 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> no qual as rotas são mostradas:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.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: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.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>

Exemplo

O objeto DirectionsResult

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

• geocoded_waypoints[] contém uma matriz de objetos DirectionsGeocodedWaypoint, cada um com detalhes sobre a geocodificação da origem, do destino e dos waypoints.
• routes[] contém uma matriz de objetos DirectionsRoute. Cada trajeto indica um modo de ir da origem ao destino, fornecido no DirectionsRequest. Geralmente, apenas um trajeto é retornado para qualquer solicitação especificada, a menos que o campo provideRouteAlternatives da solicitação esteja definido como true, o que permite que vários trajetos sejam retornados.

Observação: a propriedade via_waypoint foi descontinuada em trajetos alternativos. A 3.27 é a última versão da API que adiciona outras por meio de waypoints em trajetos alternativos. Para as versões 3.28 e mais recentes da API, você pode continuar implementando rotas arrastáveis usando o serviço Directions, desativando o recurso de arrastar de trajetos alternativos. Somente o trajeto principal deve ser arrastável. Os usuários podem arrastar o trajeto principal até que ele corresponda a um trajeto alternativo.

Waypoints geocodificados das rotas

Um DirectionsGeocodedWaypoint contém detalhes sobre a geocodificação da origem, do destino e dos waypoints.

O DirectionsGeocodedWaypoint é um literal de objeto que contém 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 geocódigo foi retornado.
  • "ZERO_RESULTS" indica que o geocódigo deu certo, mas não retornou resultados. Isso pode ocorrer se o geocodificador recebeu um address inexistente.

• 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. Convém 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ê enviou a solicitação. Elas também podem ser retornadas quando uma solicitação corresponde a dois ou mais locais na mesma localidade. Por exemplo, "Hillpar St, Bristol, UK" vai retornar uma correspondência parcial para Henry Street e Henrietta Street. Se uma solicitação incluir um componente de endereço com um erro ortográfico, o serviço de geocodificação pode sugerir um endereço alternativo. Sugestões acionadas dessa maneira também vão ser marcadas como correspondências parciais.

• place_id é um identificador único de um local, que pode ser usado com outras APIs do Google. Por exemplo, você pode usar place_id com a biblioteca da API Google Places para ver detalhes de uma empresa local, como número de telefone, horário de funcionamento, avaliações de usuários e muito mais. Consulte a perspectiva geral do ID de local.
• types[] é uma matriz que indica 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 geocódigo de "Chicago" retorna "região", que indica que "Chicago" é uma cidade, e também retorna "político", indicando que é uma entidade política.

Trajetos das rotas

Observação: o objeto DirectionsTrip legado foi renomeado como DirectionsRoute. Agora uma rota é a jornada completa, do início ao fim, em vez de um trecho de uma rota principal.

Um DirectionsRoute contém um único resultado da origem e do destino especificados. Esse trajeto pode ser composto de um ou mais trechos (do tipo DirectionsLeg), o que é determinado pela especificação de waypoints. O trajeto também contém informações de direitos autorais e avisos que precisam ser mostrados ao usuário com os dados do trajeto.

O DirectionsRoute é um literal de objeto que contém os seguintes campos:

• legs[] contém uma matriz de objetos DirectionsLeg, cada um deles contendo informações sobre um trecho do trajeto determinado de dois locais dentro do trajeto especificado. É definido um trecho separado para cada waypoint ou destino especificado. Um trajeto sem waypoints contém exatamente um DirectionsLeg. Cada trecho consiste em uma série de DirectionSteps.
• waypoint_order contém uma matriz que indica a ordem dos waypoints no trajeto calculado. Essa matriz pode conter uma ordem diferente se o DirectionsRequest tiver recebido optimizeWaypoints: true.
• overview_path consiste de uma matriz de LatLngs que representam um caminho aproximado (suavizado) das rotas resultantes.
• overview_polyline contém um único objeto points que contém uma representação da polilinha codificada do trajeto. Essa polilinha é um caminho aproximado (suavizado) da rota resultante.
• bounds contém um LatLngBounds indicando os limites da polilinha ao longo deste trajeto especificado.
• copyrights contém o texto de direitos autorais a ser mostrado para este trajeto.
  Observação: se você não usar o objeto DirectionsRenderer fornecido, será necessário processar e mostrar essas informações por conta própria.
• warnings[] contém uma matriz de avisos que serão mostrados quando essas rotas foram mostradas. Se você não usar o objeto DirectionsRenderer fornecido, deverá manipular e mostrar esses avisos manualmente.
• fare contém o total das tarifas (ou seja, o custo total dos bilhetes) nesse trajeto. Essa propriedade é retornada somente para solicitações de transporte público e apenas para trajetos em que as informações de tarifas estão disponíveis para todos os trechos do percurso. Essas informações incluem:
  • currency: um código ISO 4217 que indica a moeda em que o valor é expresso.
  • value: o total das tarifas na moeda especificada acima.

Trechos das rotas

Observação: o objeto DirectionsRoute legado foi renomeado como DirectionsLeg.

Um DirectionsLeg define um único trecho de uma jornada (da origem ao destino) no trajeto calculado. Trajetos que não contêm waypoints consistem em um único "trecho". Já trajetos que definem um ou mais waypoints consistem em um ou mais trechos, que correspondem aos trechos específicos da jornada.

O DirectionsLeg é um literal de objeto que contém os seguintes campos:

• steps[] contém uma matriz de objetos DirectionsStep com informações sobre cada etapa específica do trecho do caminho.

• distance indica a distância total coberta por este trecho, como um objeto Distance com o seguinte formato:

  • value indica a distância em metros
  • text contém uma string que representa a distância, que, por padrão, é mostrada com a mesma unidade de medida usada na origem. Por exemplo, milhas são usadas para origens nos Estados Unidos. Você pode substituir esse sistema de medidas definindo especificamente um UnitSystem na consulta original. Independentemente do sistema de medidas usado, o campo distance.value sempre conterá um valor expresso em metros.

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

• duration indica a duração total deste trecho, como um objeto Duration com o seguinte formato:

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

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

• duration_in_traffic indica a duração total desse trecho, considerando as condições de trânsito atuais. O duration_in_traffic será retornado somente se todas as condições a seguir forem verdadeiras:

  • A solicitação não inclui waypoints com parada. Ou seja, ele não inclui waypoints em que stopover é true.
  • A solicitação é específica para rotas de carro. O mode é definido como driving.
  • O departureTime está incluído como parte do campo drivingOptions na solicitação.
  • Há condições de trânsito disponíveis para o trajeto solicitado.

  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 o horário previsto de chegada para esse trecho. Essa propriedade é retornada apenas para rotas de transporte público. O resultado é retornado como um objeto Time com três propriedades:
  • value, o horário especificado como um objeto JavaScript Date.
  • text, o horário especificado como uma string. O tempo é mostrado no fuso horário da parada do transporte público.
  • time_zone contém o fuso horário desta estação. O valor é o nome do fuso horário conforme definido no banco de dados de fusos horários da IANA, por exemplo, "America/New_York".
• departure_time contém o horário estimado de partida para este trecho, especificado 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 desse trecho. Como o Serviço da web do Directions calcula rotas entre locais usando a opção de transporte mais próxima (geralmente uma estrada) do ponto inicial e final, o campo start_location pode ser diferente da origem fornecida para este trecho se, por exemplo, não houver uma estrada próxima da origem.
• end_location contém a LatLng do destino deste trecho. Como o DirectionsService calcula rotas entre locais usando a opção de transporte mais próxima (geralmente uma estrada) do ponto inicial e final, o campo end_location pode ser diferente do destino fornecido para este trecho se, por exemplo, não houver uma estrada próxima do destino.
• start_address contém o endereço legível (geralmente uma rua) do ponto inicial deste trecho.
  
  O conteúdo precisa ser lido no estado em que se encontra. Não analise o endereço formatado de maneira programática.
• end_address contém o endereço legível (geralmente uma rua) do ponto final deste trecho.
  
  O conteúdo precisa ser lido no estado em que se encontra. Não analise o endereço formatado de maneira programática.

Etapas das rotas

Um DirectionsStep é a menor unidade do trajeto de uma rota e contém uma única etapa que descreve uma instrução única e específica da jornada. Por exemplo, "Vire à esquerda na Avenida Brasil". 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 indicada como "Entre na I-80 West" pode conter uma distância de "37 milhas" e uma duração de "40 minutos", indicando que a próxima etapa está a 37 milhas/40 minutos da etapa atual.

Quando você usa o serviço Directions para pesquisar rotas de transporte público, a matriz de etapas inclui informações específicas de transporte público extras na forma de um objeto transit. Se as rotas incluem vários modos de transporte, são fornecidas rotas detalhadas para etapas a pé ou de carro em uma matriz steps[]. Por exemplo, uma etapa a pé inclui rotas dos locais inicial e final: "Caminhe até a Innes Ave e Fitch Street". Essa etapa incluirá rotas a pé detalhadas para esse trajeto na matriz steps[], como: "Siga para o Noroeste", "Vire à esquerda na Arelious Walker" e "Vire à esquerda na Innes Avenue".

O DirectionsStep é um literal de objeto que contém os seguintes campos:

• instructions contém instruções para esta etapa dentro de uma string de texto.
• distance contém a distância coberta por esta etapa até a próxima etapa, como um Distance. Consulte a descrição em DirectionsLeg, acima. Esse campo pode ser indefinido se a distância é desconhecida.
• duration contém uma estimativa do tempo necessário para realizar a etapa, até a etapa seguinte, como um objeto Duration. Consulte a descrição em DirectionsLeg, acima. Esse campo pode ser indefinido se a duração é desconhecida.
• start_location contém a LatLng geocodificada do ponto inicial desta etapa.
• end_location contém a LatLng do ponto final desta etapa.
• polyline contém um único objeto points que contém uma representação da polilinha codificada da etapa. Essa polilinha é um caminho aproximado (suavizado) da etapa.
• steps[]: um literal de objeto DirectionsStep que contém rotas detalhadas para etapas de caminhada ou condução nas 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 que descreve o curso dessa etapa.
• transit contém informações específicas de transporte público, como os horários de chegada e partida 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 extras são expostas por meio do objeto TransitDetails, retornadas como uma propriedade de DirectionsStep. No objeto TransitDetails, é possível acessar informações extras para os objetos TransitStop, TransitLine, TransitAgency e VehicleType, conforme descrito abaixo.

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 de chegada/parada com as seguintes propriedades:
  • name é o nome da parada/estação de transporte público. Por exemplo: "Union Square".
  • location é a localização da parada/estação de transporte público, representada como um LatLng.
• departure_stop contém um objeto TransitStop que representa a parada/estação de partida.
• arrival_time contém o horário de chegada, especificado como um objeto Time com três propriedades:
  • value, o horário especificado como um objeto JavaScript Date.
  • text, o horário especificado como uma string. O tempo é mostrado no fuso horário da parada do transporte público.
  • time_zone contém o fuso horário desta estação. O valor é o nome do fuso horário conforme definido no 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 de deslocamento nessa linha, conforme marcada no veículo ou no ponto de partida. Essa parada é, com frequência, a estação terminal.
• headway, quando disponível, especifica o número esperado de segundos entre as partidas no mesmo ponto, nesse horário. Por exemplo, se headway tiver o valor de 600, aguarde 10 minutos caso perca o ônibus.
• line contém um literal de objeto TransitLine com informações sobre a linha de transporte público usada nesta etapa. O TransitLine fornece o nome e a operadora da linha, junto 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 as rotas envolvem sair da parada A, passar pelas paradas B e C e chegar à parada D, num_stops vai retornar 3.

Linha de transporte público

O objeto TransitLine expõe as seguintes propriedades:

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

  Importante: se você estiver processando rotas de transporte público manualmente em vez de usar o objeto DirectionsRenderer, deverá mostrar os nomes e os URLs das agências de transporte público que oferecem os resultados de viagem.

• url contém um URL dessa linha de transporte público, conforme fornecido pela agência de transporte público.
• icon contém um URL do ícone associado a essa 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 York, têm ícones específicos para essa linha.
• color contém a cor normalmente usada na sinalização dessa linha de transporte público. A cor será especificada como uma string hexadecimal, como: #FF0033.
• text_color contém a cor do texto usada com frequência para sinalização dessa 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 nessa linha. Por exemplo: "Metrô".
  • type contém o tipo de veículo usado nessa linha. Consulte a documentação Tipo de Veículo para obter uma lista completa de valores aceitos.
  • icon contém um URL do ícone geralmente associado a esse tipo de veículo.
  • local_icon contém o URL do ícone associado a esse tipo de veículo, com base na sinalização de transporte local.

Tipo de veículo

O objeto VehicleType expõe as seguintes propriedades:

Valor	Definição
VehicleType.RAIL	Trem.
VehicleType.METRO_RAIL	Trilho para veículos leves.
VehicleType.SUBWAY	Veículo leve subterrâneo.
VehicleType.TRAM	Veículo leve acima do chão.
VehicleType.MONORAIL	Monotrilho.
VehicleType.HEAVY_RAIL	Vagões pesados.
VehicleType.COMMUTER_TRAIN	Trem metropolitano.
VehicleType.HIGH_SPEED_TRAIN	Trem de alta velocidade.
VehicleType.BUS	Ônibus.
VehicleType.INTERCITY_BUS	Ônibus intermunicipal.
VehicleType.TROLLEYBUS	Ônibus elétrico.
VehicleType.SHARE_TAXI	Dividir um táxi é uma forma de ônibus, com a possibilidade de deixar e pegar passageiros em qualquer ponto do trajeto.
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. Geralmente, um funicular consiste em dois carros, cada um atuando como contrapeso do outro.
VehicleType.OTHER	Todos os demais veículos vão retornar esse tipo.

Inspeção do objeto DirectionsResults

Os componentes de DirectionsResults (DirectionsRoute, DirectionsLeg, DirectionsStep e TransitDetails) podem ser inspecionados e usados ao analisar qualquer resposta de rotas.

Importante: se você estiver processando rotas de transporte público manualmente em vez de usar o objeto DirectionsRenderer, deverá mostrar os nomes e os URLs das agências de transporte público que oferecem os resultados de viagem.

O exemplo a seguir plota rotas de caminhada para algumas atrações turísticas na cidade de Nova York. Inspecionamos o DirectionsStep do trajeto para adicionar marcadores para cada etapa e anexar informações a um InfoWindow com texto instrucional para esta etapa.

Observação: como estamos calculando rotas a pé, também mostramos os avisos para o usuário em outro painel <div>.

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

function initMap() {
  // 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
  }
  directionsRenderer = 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: '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 == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsRenderer.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>

Exemplo

Usar waypoints nos trajetos

Cuidado: as solicitações que usam mais de 10 waypoints, ou a otimização de waypoints, têm uma taxa mais alta. Saiba mais sobre o faturamento dos produtos da Plataforma Google Maps.

Conforme observado em DirectionsRequest, você também pode especificar waypoints (do tipo DirectionsWaypoint) ao calcular trajetos usando o serviço Directions para obter rotas a pé, de bicicleta ou de carro. Os waypoints não estão disponíveis em rotas de transporte público. Os waypoints permitem que você calcule trajetos por meio de localizações adicionais. Nesse caso, o trajeto retornado passa pelos waypoints informados.

Um waypoint consiste nos seguintes campos:

• location (obrigatório) especifica o endereço do waypoint.
• stopover (opcional) indica se este waypoint é uma parada real no trajeto (true) ou apenas uma preferência para rotear pelo local indicado (false). As paradas são true por padrão.

Cuidado: definir stopover como false para evitar paradas resulta em rotas muito rígidas na interpretação delas sobre o waypoint. Isso poderá resultar em desvios graves no trajeto ou ZERO_RESULTS no código de status da resposta, se o serviço Directions não conseguir criar rotas usando esse ponto.

Por padrão, o serviço Directions calcula um trajeto pelos waypoints fornecidos, na ordem em que são apresentados. Como opção, você pode passar optimizeWaypoints: true dentro do parâmetro DirectionsRequest para permitir que o serviço Directions otimize o trajeto fornecido reorganizando os waypoints em uma ordem mais eficaz. Essa otimização é um aplicativo do problema do vendedor de viagens. O tempo do percurso é o principal fator a ser otimizado, mas demais fatores, como distância, quantidade de curvas e outros, podem ser considerados para determinar o trajeto mais eficaz. Todos os waypoints precisam ser paradas para que o serviço Directions otimize o trajeto.

Se você instruir o serviço Directions a otimizar a ordem dos seus waypoints, a ordem será retornada no campo waypoint_order dentro do objeto DirectionsResult.

O exemplo a seguir calcula trajetos que cruzam os EUA usando diversos pontos de partida, destinos e waypoints. Para selecionar vários waypoints, pressione Ctrl + clique ao selecionar os itens na lista. routes.start_address e routes.end_address são inspecionados para fornecer o texto para cada ponto inicial e final do trajeto.

TypeScript

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const 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>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

Observação: acesse o guia sobre como usar o TypeScript e o Google Maps.

JavaScript

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

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let 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,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const 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>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;
index.js

Limites e restrições para waypoints

Os limites e as restrições de uso a seguir são válidos:

• O número máximo de waypoints permitidos ao usar o serviço Directions na API Maps JavaScript é 25, mais a origem e o destino. Os limites são os mesmos do serviço da Web da API Directions.
• No serviço da Web da API Directions, os clientes podem ter 25 waypoints, além da origem e do destino.
• Os clientes do Plano Premium da Plataforma Google Maps têm 25 waypoints, além da origem e do destino.
• Não são permitidos waypoints nas rotas de transporte público.

Rotas arrastáveis

Os usuários podem modificar rotas de bicicleta, a pé ou de carro mostradas usando um DirectionsRenderer dinamicamente, caso as rotas sejam arrastáveis. Isso permite que o usuário selecione e altere trajetos, clicando e arrastando os caminhos resultantes no mapa. Indique se uma exibição do renderizador permite rotas arrastáveis definindo sua propriedade draggable para 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 waypoint) do caminho no resultado renderizado e mover o componente indicado para uma nova localização. O DirectionsRenderer será atualizado dinamicamente para mostrar o caminho modificado. Quando o ponto é liberado, um waypoint 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 do trajeto. A seleção e a movimentação de um marcador de waypoint (incluindo os pontos de partida e de chegada) alteram os trechos do trajeto que passam pelo waypoint.

Como as rotas arrastáveis são modificadas e renderizadas pelo cliente, convém monitorar e manipular o evento directions_changed no DirectionsRenderer para ser notificado quando o usuário modificou as rotas mostradas.

O código a seguir mostra uma viagem de Perth, na costa oeste da Austrália, a Sydney, na costa leste. O código monitora o evento directions_changed para atualizar a distância total de todos os trechos da viagem.

TypeScript

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

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

Observação: leia o guia sobre como usar o TypeScript e o Google Maps.

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer,
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;
index.js

Observação: o JavaScript é compilado no snippet do TypeScript.

Exemplo

Testar amostra

JSFiddle.net (link em inglês) Google Cloud Shell