Traçando rotas com a versão 3 da API do Google Maps - Parte II

Traçar rotas usando a API do Google Maps é uma tarefa relativamente simples. Para o processo básico, basta criar instâncias de dois serviços existentes na API - um que calcula as rotas (DirectionsService) e outro que as exibe (DirectionsRenderer). Além, é claro, de fornecermos o endereço de origem e o de destino (ou pares latitude/longitude que correspondam aos locais desejados). Esse processo básico foi assunto de um outro post aqui no blog, onde foi apresentado um passo a passo para esse uso da API.

Rotas onde apenas dois pontos são especificados atendem uma gama grande de situações, mas nem sempre isso é suficiente. É o que ocorre quando há uma logística mais complexa envolvida no traçado da rota, como por exemplo, quando temos um ponto de origem e outro de destino mas queremos também estabelecer locais intermediários que devem constar da rota calculada.

Na realidade, o trabalho feito no post básico sobre rotas nos deixa bem próximos de atender também a necessidade de passar por outros pontos preestabelecidos. O que vai abaixo é parte do código explicado naquele outro post, justamente o trecho que traça a rota entre dois locais dados:

var directionsService, directionsRenderer;
var enderDe, enderAte;

directionsService = new google.maps.DirectionsService();
directionsRenderer = new google.maps.DirectionsRenderer();
directionsRenderer.setMap(map);

enderDe = 'ALAMEDA SANTOS, 1000, SÃO PAULO - SP, 01418-9028';
enderAte =
'AVENIDA NAÇÕES UNIDAS, 17-17, BAURU - SP, 17013-035';

var request = {
origin:endDe,
destination:endPara,
travelMode: google.maps.DirectionsTravelMode.DRIVING
};

directionsService.route(request, function(response, status) {
if (status == google.maps.DirectionsStatus.OK) {
directionsRenderer.setDirections(response);
}
});)

A variável request nesse código é do tipo DirectionsRequest. De acordo com a documentação dessa classe, além das propriedades utilizadas no exemplo básico acima, ela possui uma outra chamada waypoints. A propriedade waypoints é um array de objetos do tipo DirectionsWaypoint, cada um contendo informações sobre um endereço intermediário que deve constar do trajeto final. Cada endereço pode ser informado como um texto - exatamente como fazemos para definir os pontos de origem e destino - ou ainda o par latidude/longitude que representa o local por onde a rota deve passar.

Com isso, podemos montar um novo exemplo para traçar a rota entre dois locais, passando obrigatoriamente por uma lista de outros locais, cujos endereços são fornecidos. É preciso apenas passar uma lista desses endereços usando a propriedade waypoints do objeto request:

var directionsService, directionsRenderer;
var enderDe, enderAte;

directionsService = new google.maps.DirectionsService();
directionsRenderer = new google.maps.DirectionsRenderer();
directionsRenderer.setMap(map);

/* Endereço de origem e o de destino. */
enderDe = 'ALAMEDA SANTOS, 1000, SÃO PAULO - SP, 01418-9028';
enderAte =
'AVENIDA NAÇÕES UNIDAS, 17-17, BAURU - SP, 17013-035';

/* Locais intermediários por onde a rota deve passar. */
var local1, local, local3;
local1 = {location:'AV. 11 DE JUNHO, 52, SÃO PAULO - SP'};
local2 = {location:'RUA CEL. MURSA, 10, SÃO PAULO - SP'};
local3 = {location:'RUA CAMPOS SALLES, 214, BOTUCATU - SP'};

var request = {
origin:endDe,
destination:endPara,
travelMode: google.maps.DirectionsTravelMode.DRIVING,
waypoints: new Array (local1, local2, local3)
};

Acrescentando esse valor do waypoints ao exemplo básico publicado no outro post, temos o mapa e a rota abaixo:

O HTML com este exemplo completo pode ser acessado neste link.

Veja que os endereços da lista não precisam estar na mesma cidade. Outro aspecto importante a se destacar é que a rota é traçada a partir do local de origem, passando pelos pontos extras na ordem exata em que eles foram incluídos na lista. Isto é, o serviço da API que traça as rotas não faz qualquer inferência a respeito da melhor ordem a seguir para obter a rota mais curta. Portanto, quando essa questão for um problema, é preciso prestar atenção ao construir o array waypoints para evitar que a rota resultante seja irracional.

Por fim, como a propriedade waypoints é do tipo Array, todos os métodos e propriedades dessa classe são aplicáveis, inclusive push, que permite acrescentar novos itens ao array depois que ele foi instanciado:

request.waypoints.push (
{location: 'AV. RODRIGUES ALVES, 14-10, BAURU - SP' }
);

A documentação para a classe Array está disponível neste link.

Mais Informações
Básico sobre rotas com a versão 3 da API do Google Maps, Documentação da classe DirectionsRequest, Documentação da classe DirectionsWaypoint