Acessar matriz de rota

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.

Uma matriz de rotas é uma matriz bidimensional de informações de rota, em que as linhas correspondem às origens e as colunas correspondem aos destinos. Com uma lista de origens e destinos, a classe matriz de rotas calcula a distância e a duração de uma rota que começa em cada origem e termina em cada destino. Use a classe Matriz de rotas para calcular a distância e a duração de um trajeto para várias origens e destinos.

Confira o código-fonte de exemplo completo

Este exemplo mostra como usar a classe Matriz de rotas para calcular as distâncias e durações de viagens entre várias origens e destinos.

TypeScript

// Initialize and add the map.
let map: google.maps.Map;
const markers: google.maps.marker.AdvancedMarkerElement[] = [];
const center = { lat: 51.55, lng: -1.8 };

async function init(): Promise<void> {
    //  Request the needed libraries.
    const [
        { Map },
        { Place },
        { AdvancedMarkerElement, PinElement },
        { RouteMatrix },
        { LatLngBounds, UnitSystem },
    ] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('routes'),
        google.maps.importLibrary('core'),
    ]);

    const bounds = new LatLngBounds();

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

    // Build the request using Place instances.
    const origin1 = new Place({
        id: 'ChIJ83WZp86p2EcRbMrkYqGncBQ', // Greenwich, London, UK
    });
    const origin2 = new Place({
        id: 'ChIJCSkVvleJc0gR8HHaTGpajKc', // Southampton, UK
    });
    const destinationA = new Place({
        id: 'ChIJYdizgWaDcUgRH9eaSy6y5I4', // Bristol, UK
    });
    const destinationB = new Place({
        id: 'ChIJ9VPsNNQCbkgRDmeGZdsGNBQ', // Cardiff, UK
    });

    await Promise.all([
        origin1.fetchFields({ fields: ['location', 'displayName'] }),
        origin2.fetchFields({ fields: ['location', 'displayName'] }),
        destinationA.fetchFields({ fields: ['location', 'displayName'] }),
        destinationB.fetchFields({ fields: ['location', 'displayName'] }),
    ]);

    const destinations = [destinationA, destinationB];
    const origins = [origin1, origin2];
    const request: google.maps.routes.ComputeRouteMatrixRequest = {
        origins,
        destinations,
        travelMode: 'DRIVING',
        units: UnitSystem.METRIC,
        fields: ['distanceMeters', 'durationMillis', 'condition'],
    };

    // Show the request.
    document.getElementById('request')!.innerText = JSON.stringify(
        request,
        null,
        2
    );

    // Get the RouteMatrix response.
    const response = await RouteMatrix.computeRouteMatrix(request);

    // Show the response.
    document.getElementById('response')!.innerText = JSON.stringify(
        response,
        null,
        2
    );

    // Add markers for the origins.
    for (const origin of origins) {
        if (origin.location) {
            const pin = new PinElement({
                glyphText: 'O',
                glyphColor: 'white',
                background: '#137333',
                borderColor: 'white',
            });
            const marker = new AdvancedMarkerElement({
                map,
                position: origin.location,
                title: `Origin: ${origin.displayName}`,
            });
            marker.append(pin);
            markers.push(marker);
            bounds.extend(origin.location);
        }
    }

    // Add markers for the destinations.
    for (const destination of destinations) {
        if (destination.location) {
            const pin = new PinElement({
                glyphText: 'D',
                glyphColor: 'white',
                background: '#C5221F',
                borderColor: 'white',
            });

            const marker = new AdvancedMarkerElement({
                map,
                position: destination.location,
                content: pin,
                title: `Destination: ${destination.displayName ?? 'Unknown'}`,
            });

            markers.push(marker);
            bounds.extend(destination.location);
        }
    }

    // Fit the map to the bounds of all markers.
    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;
const markers = [];
const center = { lat: 51.55, lng: -1.8 };

async function init() {
    //  Request the needed libraries.
    const [
        { Map },
        { Place },
        { AdvancedMarkerElement, PinElement },
        { RouteMatrix },
        { LatLngBounds, UnitSystem },
    ] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('routes'),
        google.maps.importLibrary('core'),
    ]);

    const bounds = new LatLngBounds();

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

    // Build the request using Place instances.
    const origin1 = new Place({
        id: 'ChIJ83WZp86p2EcRbMrkYqGncBQ', // Greenwich, London, UK
    });
    const origin2 = new Place({
        id: 'ChIJCSkVvleJc0gR8HHaTGpajKc', // Southampton, UK
    });
    const destinationA = new Place({
        id: 'ChIJYdizgWaDcUgRH9eaSy6y5I4', // Bristol, UK
    });
    const destinationB = new Place({
        id: 'ChIJ9VPsNNQCbkgRDmeGZdsGNBQ', // Cardiff, UK
    });

    await Promise.all([
        origin1.fetchFields({ fields: ['location', 'displayName'] }),
        origin2.fetchFields({ fields: ['location', 'displayName'] }),
        destinationA.fetchFields({ fields: ['location', 'displayName'] }),
        destinationB.fetchFields({ fields: ['location', 'displayName'] }),
    ]);

    const destinations = [destinationA, destinationB];
    const origins = [origin1, origin2];
    const request = {
        origins,
        destinations,
        travelMode: 'DRIVING',
        units: UnitSystem.METRIC,
        fields: ['distanceMeters', 'durationMillis', 'condition'],
    };

    // Show the request.
    document.getElementById('request').innerText = JSON.stringify(
        request,
        null,
        2
    );

    // Get the RouteMatrix response.
    const response = await RouteMatrix.computeRouteMatrix(request);

    // Show the response.
    document.getElementById('response').innerText = JSON.stringify(
        response,
        null,
        2
    );

    // Add markers for the origins.
    for (const origin of origins) {
        if (origin.location) {
            const pin = new PinElement({
                glyphText: 'O',
                glyphColor: 'white',
                background: '#137333',
                borderColor: 'white',
            });
            const marker = new AdvancedMarkerElement({
                map,
                position: origin.location,
                title: `Origin: ${origin.displayName}`,
            });
            marker.append(pin);
            markers.push(marker);
            bounds.extend(origin.location);
        }
    }

    // Add markers for the destinations.
    for (const destination of destinations) {
        if (destination.location) {
            const pin = new PinElement({
                glyphText: 'D',
                glyphColor: 'white',
                background: '#C5221F',
                borderColor: 'white',
            });

            const marker = new AdvancedMarkerElement({
                map,
                position: destination.location,
                content: pin,
                title: `Destination: ${destination.displayName ?? 'Unknown'}`,
            });

            markers.push(marker);
            bounds.extend(destination.location);
        }
    }

    // Fit the map to the bounds of all markers.
    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.
 */
/* Optional: Makes the sample page fill the window. */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

#container {
    height: 100%;
    display: flex;
}

#sidebar {
    flex-basis: 15rem;
    flex-grow: 1;
    padding: 1rem;
    max-width: 30rem;
    height: 100%;
    box-sizing: border-box;
    overflow: auto;
}

#map {
    flex-basis: 0;
    flex-grow: 4;
    height: 100%;
}

#sidebar {
    flex-direction: column;
}
style.css

HTML

<html>
    <head>
        <title>Route matrix</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="container">
            <div id="map"></div>
            <div id="sidebar">
                <h3 style="flex-grow: 0">Request</h3>
                <pre style="flex-grow: 1" id="request"></pre>
                <h3 style="flex-grow: 0">Response</h3>
                <pre style="flex-grow: 1" id="response"></pre>
            </div>
        </div>
    </body>
</html>
index.html

Testar amostra

JSFiddle.net

Limites de solicitações

O método computeRouteMatrix aplica os seguintes limites de solicitação para waypoints que usam instâncias de endereço ou de lugar e para itens. Os itens são as rotas entre cada origem e destino em uma matriz de rotas. Portanto, o número de itens é o número de origens multiplicado pelo número de destinos. Por exemplo, se você tiver 10 origens e 10 destinos, terá 100 itens:

• O número de itens não pode exceder 625 para rotas que não são TRANSIT.
• Se você especificar uma rota TRANSIT, o número de itens não poderá exceder 100.
• Se você especificar TRAFFIC_AWARE_OPTIMAL, o número de itens não poderá exceder 100.
• Se você especificar origens ou destinos usando endereços ou instâncias de Place, poderá especificar até 50 no total dessa maneira.

Para mais detalhes, consulte Acessar uma rota de transporte público.

Exemplo de solicitação de matriz de rotas

O exemplo a seguir mostra um ComputeRouteMatrixRequest. Este exemplo faz o seguinte:

• Mostra a especificação de uma matriz de dois waypoints de origem e dois de destino. O método calcula um trajeto de cada origem para cada destino, então a resposta contém quatro trajetos.
  Na matriz, o primeiro elemento está no índice 0, o segundo no índice 1 e assim por diante.
• Especifica os campos que serão retornados. Neste exemplo, a solicitação está configurada para retornar durationMillis, distanceMeters e condition para cada trajeto.

TypeScript

const destinations = [destinationA, destinationB];
const origins = [origin1, origin2];
const request: google.maps.routes.ComputeRouteMatrixRequest = {
    origins,
    destinations,
    travelMode: 'DRIVING',
    units: UnitSystem.METRIC,
    fields: ['distanceMeters', 'durationMillis', 'condition'],
};
index.ts

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

JavaScript

const destinations = [destinationA, destinationB];
const origins = [origin1, origin2];
const request = {
    origins,
    destinations,
    travelMode: 'DRIVING',
    units: UnitSystem.METRIC,
    fields: ['distanceMeters', 'durationMillis', 'condition'],
};
index.js

A resposta contém as quatro rotas possíveis para a combinação de todos os pontos de passagem de origem e destino, conforme mostrado no exemplo a seguir:

"matrix": {
  "rows": [
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 202587,
          "durationMillis": 10040000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 252734,
          "durationMillis": 12240000
        }
      ]
    },
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 166135,
          "durationMillis": 6596000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 216282,
          "durationMillis": 8797000
        }
      ]
    }
  ]
}
    

Identifique cada trajeto no resultado usando o índice de origem e destino para encontrar o RouteMatrixItem correspondente na matriz 2D. Por exemplo, o RouteMatrixItem que descreve o trajeto calculado da origem no índice 1 e do destino 0 na solicitação estaria no segundo elemento da matriz RouteMatrix.rows e no primeiro elemento da matriz RouteMatrixRow.items.

O snippet de código a seguir mostra como identificar o RouteMatrixItem para encontrar o trajeto de uma origem e um destino específicos:

// Find the route for origin 'x' and destination 'y'.
const {matrix} = await RouteMatrix.computeRouteMatrix(request);
const myRouteMatrixItem = matrix.rows[x].items[y];
    

Escolher campos para retornar

Ao solicitar uma matriz de rotas, use uma máscara de campo para especificar quais informações a resposta deve retornar.

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 ComputeRoutesMatrixRequest.fields, conforme mostrado no snippet a seguir:

fields: ['durationMillis', 'distanceMeters', 'condition'],
    

Determinar quais máscaras de campo usar

Veja como determinar quais campos você quer usar e criar as máscaras de campo para eles:

1. Solicite todos os campos usando uma máscara de campo de ['*'].
   Atenção: embora seja possível usar essa máscara de campo curinga durante o desenvolvimento para determinar os campos necessários, não a use na produção. Solicitar todos os campos na produção resulta em custos mais altos e tempos de resposta mais longos. Seu custo também pode aumentar inesperadamente à medida que recursos avançados são adicionados, já que essa máscara de campo os inclui automaticamente. Em vez disso, solicite apenas os campos necessários para minimizar os custos e o tempo de resposta da solicitação.
2. Observe a hierarquia dos campos na classe RouteMatrixItem para encontrar os campos que você quer.

3. Crie suas máscaras de campo usando a hierarquia dos campos mostrados na etapa anterior, usando este formato:

   topLevelField[.secondLevelField][.thirdLevelField][...]

Por exemplo, para este RouteMatrixItem:

  "travelAdvisory": {
    "fuelConsumptionMicroliters": 0,
    "tollInfo": {
      "estimatedPrices": [
        {
          "currencyCode": "USD",
          "units": 4,
          "nanos": 400000000
        }
      ]
    }
  },
    

Se você quiser retornar apenas o campo tollInfo para RouteMatrixItem, sua máscara de campo será assim:

fields: ['travelAdvisory.tollInfo']

Se você quiser solicitar o consumo de combustível estimado, sua máscara de campo será:

fields: ['travelAdvisory.fuelConsumptionMicroliters']

Se você quiser solicitar ambos, sua máscara de campo será a seguinte:

fields: ['travelAdvisory.fuelConsumptionMicroliters', 'travelAdvisory.tollInfo']

Se você quiser solicitar o conjunto completo de alertas de viagem, sua máscara de campo será:

fields: ['travelAdvisory']

A hierarquia de propriedades está disponível apenas para RouteMatrix.computeRouteMatrix, e não é compatível com Route.computeRoutes.

Solicitar uma matriz de rotas de transporte público

Receba uma matriz de rotas de transporte público que usa as opções de transporte público disponíveis na região. As opções de transporte público podem incluir ônibus, metrôs e trens, entre outros. Para solicitar uma matriz de rotas de transporte público:

• Defina o travelMode como TRANSIT
• Solicite o campo travelAdvisory.

Saiba mais sobre as rotas de transporte público.