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 se aplicar ao 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 rotas, em que as linhas correspondem às origens e as colunas aos destinos. Com uma lista de origens e destinos, a classe Route Matrix calcula a distância e a duração de um trajeto que começa em cada origem e termina em cada destino. Use a classe Route Matrix 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 Route Matrix para calcular as distâncias e durações de viagens entre várias origens e destinos.

TypeScript

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

async function initMap(): Promise<void> {
  //  Request the needed libraries.
  //@ts-ignore
  const [{Map}, {Place}, {AdvancedMarkerElement, PinElement}, {RouteMatrix}] = await Promise.all([
    google.maps.importLibrary('maps') as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary('places') as Promise<google.maps.PlacesLibrary>,
    google.maps.importLibrary('marker') as Promise<google.maps.MarkerLibrary>,
    google.maps.importLibrary('routes') as Promise<google.maps.RoutesLibrary>
  ]);

  const bounds = new google.maps.LatLngBounds();

  map = new Map(document.getElementById('map') as HTMLElement, {
    zoom: 8,
    center: 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 request = {
    origins: [origin1, origin2], 
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    units: google.maps.UnitSystem.METRIC,
    fields: ['distanceMeters', 'durationMillis', 'condition'],
  };

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

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

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

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

  // Add markers for the destinations.
  for (let i = 0; i < request.destinations.length; i++) {
    const destination = request.destinations[i];
    if (destination.location) {
      const pin = new PinElement({
        //@ts-ignore
        glyphText: "D",
        glyphColor: "white",
        background: "#C5221F",
        borderColor: "white",
      });

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

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

  // Fit the map to the bounds of all markers.
  map.fitBounds(bounds);
}

initMap();
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 markers = [];
let center = { lat: 51.55, lng: -1.8 };
async function initMap() {
    //  Request the needed libraries.
    //@ts-ignore
    const [{ Map }, { Place }, { AdvancedMarkerElement, PinElement }, { RouteMatrix }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('routes')
    ]);
    const bounds = new google.maps.LatLngBounds();
    map = new Map(document.getElementById('map'), {
        zoom: 8,
        center: 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 request = {
        origins: [origin1, origin2],
        destinations: [destinationA, destinationB],
        travelMode: 'DRIVING',
        units: google.maps.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 request.origins) {
        if (origin.location) {
            const pin = new PinElement({
                //@ts-ignore
                glyphText: "O",
                glyphColor: "white",
                background: "#137333",
                borderColor: "white",
            });
            const marker = new AdvancedMarkerElement({
                map,
                position: origin.location,
                content: pin.element,
                title: `Origin: ${origin.displayName}`,
            });
            markers.push(marker);
            bounds.extend(origin.location);
        }
    }
    // Add markers for the destinations.
    for (let i = 0; i < request.destinations.length; i++) {
        const destination = request.destinations[i];
        if (destination.location) {
            const pin = new PinElement({
                //@ts-ignore
                glyphText: "D",
                glyphColor: "white",
                background: "#C5221F",
                borderColor: "white",
            });
            const marker = new AdvancedMarkerElement({
                map,
                position: destination.location,
                content: pin.element,
                title: `Destination: ${destination.displayName}`,
            });
            markers.push(marker);
            bounds.extend(destination.location);
        }
    }
    // Fit the map to the bounds of all markers.
    map.fitBounds(bounds);
}
initMap();
index.js

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

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>
  </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>
    <!-- prettier-ignore -->
    <script>(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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "beta"});</script>
  </body>
</html>
index.html

Testar amostra

JSFiddle.net

Limites de solicitações

O método computeRouteMatrix impõe os seguintes limites de solicitação para pontos de referência usando instâncias de endereço ou lugar e para itens. Os itens são os trajetos 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 TRANSIT rota, 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 lugar, poderá especificar até 50 no total dessa forma.

Para mais detalhes, consulte Receber 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 como especificar uma matriz de dois pontos de referência de origem e dois de destino. O método calcula um trajeto de cada origem para cada destino. Portanto, 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 a serem retornados. Neste exemplo, a solicitação está configurada para retornar durationMillis, distanceMeters e condition para cada rota.

TypeScript

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

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

JavaScript

const request = {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    units: google.maps.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 partida e de 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 bidimensional. Por exemplo, o RouteMatrixItem que descreve o trajeto calculado da origem no índice 1 e o 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 a rota 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 os campos que serão retornados

Ao solicitar uma matriz de rotas, você precisa usar 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 construir 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 quais campos são 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 mais 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. Confira a hierarquia dos campos na classe RouteMatrixItem dos campos que você quer.

3. Crie suas máscaras de campo usando a hierarquia dos campos mostrados na etapa anterior, neste 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 o RouteMatrixItem, sua máscara de campo será a seguinte:

fields: ['travelAdvisory.tollInfo']

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

fields: ['travelAdvisory.fuelConsumptionMicroliters']

Se você quiser solicitar os dois, a máscara de campo será a seguinte:

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

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

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 trajetos de transporte público

Receba uma matriz de rotas de transporte público que usa as opções 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 trajetos de transporte público.