Ver trajeto

Desenvolvedores do Espaço Econômico Europeu (EEE)

Se o endereço de faturamento estiver no Espaço Econômico Europeu, a partir de 8 de julho de 2025, os Termos de Serviço da Plataforma Google Maps para o EEE vão valer para o uso dos serviços. A funcionalidade varia de acordo com a região. Saiba mais.

Um trajeto é um caminho navegável entre um local de partida, ou origem, e um local de chegada, ou destino. Você pode escolher uma rota para diferentes meios de transporte, como a pé, de bicicleta ou diferentes tipos de veículos. Também é possível solicitar detalhes do trajeto, como distância, tempo estimado para percorrê-lo, pedágios esperados e instruções guiadas.

Confira o código-fonte de exemplo completo

O exemplo de código a seguir mostra como receber um trajeto de carro entre dois locais.

TypeScript

// Initialize and add the map.
let map: google.maps.Map;
let mapPolylines: google.maps.Polyline[] = [];
const center = { lat: 37.447646, lng: -122.113878 }; // Palo Alto, CA

// Initialize and add the map.
async function init(): Promise<void> {
    //  Request the needed libraries.
    const [{ Map }, { Place }, { Route }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
        google.maps.importLibrary('routes'),
    ]);

    map = new Map(document.getElementById('map')!, {
        zoom: 12,
        center,
        mapTypeControl: false,
        mapId: 'DEMO_MAP_ID',
    });

    // Use address strings in a directions request.
    const requestWithAddressStrings = {
        origin: '1600 Amphitheatre Parkway, Mountain View, CA',
        destination: '345 Spear Street, San Francisco, CA',
        fields: ['path'],
    };
    console.log({ requestWithAddressStrings });

    // Use Place IDs in a directions request.
    const originPlaceInstance = new Place({
        id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
    });

    const destinationPlaceInstance = new Place({
        id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
    });

    const requestWithPlaceIds: google.maps.routes.ComputeRoutesRequest = {
        origin: originPlaceInstance,
        destination: destinationPlaceInstance,
        fields: ['path'], // Request fields needed to draw polylines.
    };
    console.log({ requestWithPlaceIds });

    // Use lat/lng in a directions request.
    // Mountain View, CA
    const originLatLng = { lat: 37.422, lng: -122.084058 };
    // San Francisco, CA
    const destinationLatLng = { lat: 37.774929, lng: -122.419415 };

    // Define a computeRoutes request.
    const requestWithLatLngs: google.maps.routes.ComputeRoutesRequest = {
        origin: originLatLng,
        destination: destinationLatLng,
        fields: ['path'],
    };
    console.log({ requestWithLatLngs });

    // Use Plus Codes in a directions request.
    const requestWithPlusCodes: google.maps.routes.ComputeRoutesRequest = {
        origin: '849VCWC8+R9', // Mountain View, CA
        destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
        fields: ['path'],
    };
    console.log({ requestWithPlusCodes });

    // Define a routes request.
    const request: google.maps.routes.ComputeRoutesRequest = {
        origin: 'Mountain View, CA',
        destination: 'San Francisco, CA',
        travelMode: 'DRIVING',
        fields: ['path'], // Request fields needed to draw polylines.
    };

    // Call computeRoutes to get the directions.
    const { routes } = await Route.computeRoutes(request);

    // Use createPolylines to create polylines for the route.
    if (!routes) {
        console.warn('No routes found.');
        return;
    }
    mapPolylines = routes[0].createPolylines();
    // Add polylines to the map.
    mapPolylines.forEach((polyline) => {
        polyline.setMap(map);
    });

    // Create markers to start and end points.
    const markers = await routes[0].createWaypointAdvancedMarkers();
    // Add markers to the map
    markers.forEach((marker) => {
        marker.map = map;
    });

    // Display the raw JSON for the result in the console.
    console.log(`Response:\n ${JSON.stringify(routes, null, 2)}`);

    // Fit the map to the path.
    void fitMapToPath(routes[0].path!);
}

// Helper function to fit the map to the path.
async function fitMapToPath(path: google.maps.LatLngLiteral[]) {
    const { LatLngBounds } = await google.maps.importLibrary('core');
    const bounds = new LatLngBounds();
    path.forEach((point) => {
        bounds.extend(point);
    });
    map.fitBounds(bounds);
}

void init();
index.ts

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

JavaScript

// Initialize and add the map.
let map;
let mapPolylines = [];
const center = { lat: 37.447646, lng: -122.113878 }; // Palo Alto, CA

// Initialize and add the map.
async function init() {
    //  Request the needed libraries.
    const [{ Map }, { Place }, { Route }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
        google.maps.importLibrary('routes'),
    ]);

    map = new Map(document.getElementById('map'), {
        zoom: 12,
        center,
        mapTypeControl: false,
        mapId: 'DEMO_MAP_ID',
    });

    // Use address strings in a directions request.
    const requestWithAddressStrings = {
        origin: '1600 Amphitheatre Parkway, Mountain View, CA',
        destination: '345 Spear Street, San Francisco, CA',
        fields: ['path'],
    };
    console.log({ requestWithAddressStrings });

    // Use Place IDs in a directions request.
    const originPlaceInstance = new Place({
        id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
    });

    const destinationPlaceInstance = new Place({
        id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
    });

    const requestWithPlaceIds = {
        origin: originPlaceInstance,
        destination: destinationPlaceInstance,
        fields: ['path'], // Request fields needed to draw polylines.
    };
    console.log({ requestWithPlaceIds });

    // Use lat/lng in a directions request.
    // Mountain View, CA
    const originLatLng = { lat: 37.422, lng: -122.084058 };
    // San Francisco, CA
    const destinationLatLng = { lat: 37.774929, lng: -122.419415 };

    // Define a computeRoutes request.
    const requestWithLatLngs = {
        origin: originLatLng,
        destination: destinationLatLng,
        fields: ['path'],
    };
    console.log({ requestWithLatLngs });

    // Use Plus Codes in a directions request.
    const requestWithPlusCodes = {
        origin: '849VCWC8+R9', // Mountain View, CA
        destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
        fields: ['path'],
    };
    console.log({ requestWithPlusCodes });

    // Define a routes request.
    const request = {
        origin: 'Mountain View, CA',
        destination: 'San Francisco, CA',
        travelMode: 'DRIVING',
        fields: ['path'], // Request fields needed to draw polylines.
    };

    // Call computeRoutes to get the directions.
    const { routes } = await Route.computeRoutes(request);

    // Use createPolylines to create polylines for the route.
    if (!routes) {
        console.warn('No routes found.');
        return;
    }
    mapPolylines = routes[0].createPolylines();
    // Add polylines to the map.
    mapPolylines.forEach((polyline) => {
        polyline.setMap(map);
    });

    // Create markers to start and end points.
    const markers = await routes[0].createWaypointAdvancedMarkers();
    // Add markers to the map
    markers.forEach((marker) => {
        marker.map = map;
    });

    // Display the raw JSON for the result in the console.
    console.log(`Response:\n ${JSON.stringify(routes, null, 2)}`);

    // Fit the map to the path.
    void fitMapToPath(routes[0].path);
}

// Helper function to fit the map to the path.
async function fitMapToPath(path) {
    const { LatLngBounds } = await google.maps.importLibrary('core');
    const bounds = new LatLngBounds();
    path.forEach((point) => {
        bounds.extend(point);
    });
    map.fitBounds(bounds);
}

void init();
index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
#map {
    height: 100%;
}

/*
   * Optional: Makes the sample page fill the window.
   */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}
style.css

HTML

<html>
    <head>
        <title>Get directions</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <div id="map"></div>
    </body>
</html>
index.html

Chame o método computeRoutes() para solicitar um trajeto entre dois locais. O exemplo a seguir mostra como definir uma solicitação e chamar computeRoutes() para receber um trajeto. computeRoutes() é um método estático da classe Route, então chame Route.computeRoutes(request) diretamente. A solicitação também precisa definir a propriedade fields como uma máscara de campo de resposta.

  // Import the Routes library.
  const { Route } = await google.maps.importLibrary('routes');

  // Define a computeRoutes request.
  const request = {
    origin: 'Mountain View, CA',
    destination: 'San Francisco, CA',
    fields: ['path'], // Required: response field mask.
  };

  // Call the computeRoutes() method to get routes.
  const {routes} = await Route.computeRoutes(request);
    

Para desenhar o trajeto em um mapa, chame createPolylines() em um trajeto que você solicitou com o campo path. Consulte Mostrar polilinhas em um mapa.

Escolher campos para retornar

Ao solicitar um trajeto, use uma máscara de campo para especificar quais informações a resposta precisa retornar. É possível especificar os nomes das propriedades da classe Route na máscara de campo.

O uso de uma máscara de campo também garante que você não solicite dados desnecessários, o que ajuda na latência de resposta e evita o retorno de informações que seu sistema não precisa.

Especifique a lista de campos necessários definindo a propriedade ComputeRoutesRequest.fields, conforme mostrado no snippet a seguir:

TypeScript

// Define a routes request.
const request: google.maps.routes.ComputeRoutesRequest = {
    origin: 'Mountain View, CA',
    destination: 'San Francisco, CA',
    travelMode: 'DRIVING',
    fields: ['path'], // Request fields needed to draw polylines.
};
index.ts

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

JavaScript

// Define a routes request.
const request = {
    origin: 'Mountain View, CA',
    destination: 'San Francisco, CA',
    travelMode: 'DRIVING',
    fields: ['path'], // Request fields needed to draw polylines.
};
index.js

Especificar locais para uma rota

Para calcular um trajeto, é preciso especificar pelo menos os locais de origem e destino, além de uma máscara de campo. Também é possível especificar waypoints intermediários ao longo de um trajeto e usá-los para fazer outras coisas, como adicionar paradas ou pontos de passagem.

No ComputeRoutesRequest, é possível especificar um local de uma das seguintes maneiras:

• Place (preferencial)
• Coordenadas de latitude/longitude
• String de endereço ("Chicago, IL" ou "Darwin, NT, Australia")
• Plus Code

É possível especificar locais para todos os waypoints em uma solicitação da mesma forma ou misturá-los. Por exemplo, você pode usar coordenadas de latitude/longitude para o ponto de passagem de origem e um objeto Place para o ponto de passagem de destino.

Para maior eficiência e precisão, use objetos Place em vez de coordenadas de latitude/longitude ou strings de endereço. Os IDs de lugar são explicitamente exclusivos e oferecem benefícios de geocodificação para rotas, como pontos de acesso e variáveis de trânsito. Eles ajudam a evitar as seguintes situações que podem resultar de outras maneiras de especificar um local:

• O uso de coordenadas de latitude/longitude pode fazer com que o local seja fixado na via mais próxima a essas coordenadas, que pode não ser um ponto de acesso à propriedade ou até mesmo uma via que leve ao destino de forma rápida ou segura.
• As strings de endereço precisam ser geocodificadas pela API Routes para serem convertidas em coordenadas de latitude/longitude antes de calcular um trajeto. Essa conversão pode afetar o desempenho.

Especificar um local como um objeto Place (preferencial)

Para especificar um local usando um lugar, crie uma nova instância de Place. O snippet a seguir mostra a criação de novas instâncias de Place para origin e destination e o uso delas em um ComputeRoutesRequest:

TypeScript

// Use Place IDs in a directions request.
const originPlaceInstance = new Place({
    id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
});

const destinationPlaceInstance = new Place({
    id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
});

const requestWithPlaceIds: google.maps.routes.ComputeRoutesRequest = {
    origin: originPlaceInstance,
    destination: destinationPlaceInstance,
    fields: ['path'], // Request fields needed to draw polylines.
};
index.ts

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

JavaScript

// Use Place IDs in a directions request.
const originPlaceInstance = new Place({
    id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
});

const destinationPlaceInstance = new Place({
    id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
});

const requestWithPlaceIds = {
    origin: originPlaceInstance,
    destination: destinationPlaceInstance,
    fields: ['path'], // Request fields needed to draw polylines.
};
index.js

Coordenadas de latitude/longitude

Para especificar um local como coordenadas de latitude/longitude, crie uma nova instância de google.maps.LatLngLiteral, google.maps.LatLngAltitude ou google.maps.LatLngAltitudeLiteral. O snippet a seguir mostra a criação de novas instâncias de google.maps.LatLngLiteral para origin e destination e o uso delas em um computeRoutesRequest:

TypeScript

// Use lat/lng in a directions request.
// Mountain View, CA
const originLatLng = { lat: 37.422, lng: -122.084058 };
// San Francisco, CA
const destinationLatLng = { lat: 37.774929, lng: -122.419415 };

// Define a computeRoutes request.
const requestWithLatLngs: google.maps.routes.ComputeRoutesRequest = {
    origin: originLatLng,
    destination: destinationLatLng,
    fields: ['path'],
};
index.ts

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

JavaScript

// Use lat/lng in a directions request.
// Mountain View, CA
const originLatLng = { lat: 37.422, lng: -122.084058 };
// San Francisco, CA
const destinationLatLng = { lat: 37.774929, lng: -122.419415 };

// Define a computeRoutes request.
const requestWithLatLngs = {
    origin: originLatLng,
    destination: destinationLatLng,
    fields: ['path'],
};
index.js

String de endereço

As strings de endereço são endereços literais representados por uma string (como "1600 Amphitheatre Parkway, Mountain View, CA"). Geocodificação é o processo de converter uma string de endereço em coordenadas de latitude e longitude (como latitude 37.423021 e longitude -122.083739).

Quando você transmite uma string de endereço como o local de um waypoint, a biblioteca Routes geocodifica internamente a string para convertê-la em coordenadas de latitude e longitude.

O snippet a seguir mostra a criação de um ComputeRoutesRequest com uma string de endereço para origin e destination:

TypeScript

// Use address strings in a directions request.
const requestWithAddressStrings = {
    origin: '1600 Amphitheatre Parkway, Mountain View, CA',
    destination: '345 Spear Street, San Francisco, CA',
    fields: ['path'],
};
index.ts

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

JavaScript

// Use address strings in a directions request.
const requestWithAddressStrings = {
    origin: '1600 Amphitheatre Parkway, Mountain View, CA',
    destination: '345 Spear Street, San Francisco, CA',
    fields: ['path'],
};
index.js

Defina a região do endereço

Se você transmitir uma string de endereço incompleta como o local de um waypoint, a API poderá usar as coordenadas de latitude/longitude geocodificadas erradas. Por exemplo, você faz uma solicitação especificando "Toledo" como origem e "Madrid" como destino para um trajeto de carro:

// Define a request with an incomplete address string.
const request = {
  origin: 'Toledo',
  destination: 'Madrid',
};
    

Neste exemplo, "Toledo" é interpretado como uma cidade no estado de Ohio, nos Estados Unidos, e não na Espanha. Portanto, a solicitação retorna uma matriz vazia, o que significa que não há rotas.

É possível configurar a API para retornar resultados direcionados a uma região específica incluindo o parâmetro regionCode. Esse parâmetro especifica o código regional como um valor de dois caracteres de ccTLD ("domínio de nível superior"). A maioria dos códigos ccTLD é idêntica aos códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente para a entidade "Reino Unido da Grã-Bretanha e Irlanda do Norte").

Uma solicitação de rotas de "Toledo" para "Madrid" que inclui o parâmetro regionCode retorna resultados adequados porque "Toledo" é interpretada como uma cidade na Espanha:

const request = {
  origin: 'Toledo',
  destination: 'Madrid',
  region: 'es', // Specify the region code for Spain.
};
    

Plus Code

Muitas pessoas não têm um endereço preciso, o que pode dificultar o recebimento de entregas. Ou as pessoas com um endereço podem preferir receber entregas em locais mais específicos, como uma entrada traseira ou uma doca de carga.

Os Plus Codes são como endereços para pessoas ou lugares que não têm um endereço real. Em vez de endereços com nomes de ruas e números, os Plus Codes são baseados em coordenadas de latitude/longitude e são exibidos como números e letras.

O Google desenvolveu os Plus Codes para que todos os lugares e pessoas tenham um endereço. Um Plus Code é uma referência de local codificada, derivada de coordenadas de latitude/longitude, que representa uma área: 1/8000 de um grau por 1/8000 de um grau (aproximadamente 14m x 14m na Linha do Equador) ou menor. Você pode usar Plus Codes em vez de endereços nos lugares em que não existem, ou seja, quando os imóveis não estão numerados ou as ruas não têm nome.

Os Plus Codes precisam ser formatados como um código global ou composto:

• O código global é composto por um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres. Por exemplo, para o endereço "1600 Amphitheatre Parkway, Mountain View, CA", o código global é "849V" e o código local é "CWC8+R9". Em seguida, use o Plus Code completo de 10 caracteres para especificar o valor do local como "849VCWC8+R9".
• O código composto é formado por um código local com, pelo menos, seis caracteres combinado com um local explícito. Por exemplo, o endereço "450 Serra Mall, Stanford, CA 94305, USA" tem o código local "CRHJ+C3". Para um endereço composto, combine o código local com a cidade, o estado, o CEP e o país do endereço no formato "CRHJ+C3 Stanford, CA 94305, EUA".

O snippet a seguir mostra como calcular um trajeto especificando um waypoint para a origem e o destino usando Plus Codes:

TypeScript

// Use Plus Codes in a directions request.
const requestWithPlusCodes: google.maps.routes.ComputeRoutesRequest = {
    origin: '849VCWC8+R9', // Mountain View, CA
    destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
    fields: ['path'],
};
index.ts

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

JavaScript

// Use Plus Codes in a directions request.
const requestWithPlusCodes = {
    origin: '849VCWC8+R9', // Mountain View, CA
    destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
    fields: ['path'],
};
index.js