Recupero di una matrice di route

Sviluppatori dello Spazio economico europeo (SEE)

Se il tuo indirizzo di fatturazione si trova nello Spazio economico europeo, a partire dall'8 luglio 2025, i Termini di servizio di Google Maps Platform per il SEE si applicheranno al tuo utilizzo dei servizi. La funzionalità varia in base alla regione. Scopri di più.

Una matrice di route è un array bidimensionale di informazioni sulle route, in cui le righe corrispondono a le origini e le colonne corrispondono alle destinazioni. Dato un elenco di origini e destinazioni, la classe Route Matrix calcola la distanza e la durata di una route che inizia da ogni origine e termina in ogni destinazione. Utilizza la classe Route Matrix per calcolare la distanza e la durata di una route per più origini e destinazioni.

Visualizza il codice sorgente dell'esempio completo

Questo esempio mostra come utilizzare la classe Route Matrix per calcolare le distanze e le durate per gli spostamenti tra più origini e destinazioni.

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

Nota: leggi la guida sull'utilizzo di TypeScript e 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

Limiti per le richieste

Il metodo computeRouteMatrix applica i seguenti limiti per le richieste per i waypoint che utilizzano istanze di indirizzi o luoghi e per gli elementi. Gli elementi sono le route tra ogni origine e destinazione in una matrice di route, quindi il numero di elementi è il numero di origini moltiplicato per il numero di destinazioni. Ad esempio, se hai 10 origini e 10 destinazioni, hai 100 elementi:

• Il numero di elementi non può superare 625 per le route che non sono TRANSIT route.
• Se specifichi una route TRANSIT, il numero di elementi non può superare 100.
• Se specifichi TRAFFIC_AWARE_OPTIMAL, il numero di elementi non può superare 100.
• Se specifichi origini o destinazioni utilizzando indirizzi o istanze di luoghi, puoi specificare un totale massimo di 50 in questo modo.

Per ulteriori dettagli, consulta Ottenere una route di trasporto pubblico.

Esempio di richiesta di matrice di route

L'esempio seguente mostra una ComputeRouteMatrixRequest. Questo esempio esegue le seguenti operazioni:

• Mostra come specificare un array di due waypoint di origine e due di destinazione. Il metodo calcola una route da ogni origine a ogni destinazione, quindi la risposta contiene quattro route.
  Nell'array, il primo elemento ha indice 0, il secondo indice 1 e così via.
• Specifica i campi da restituire. In questo esempio, la richiesta è configurata per restituire durationMillis, distanceMeters, e condition per ogni route.

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

Nota: leggi la guida sull'utilizzo di TypeScript e 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

La risposta contiene le quattro route possibili per la combinazione di tutti i waypoint di origine e destinazione, come mostrato nell'esempio seguente:

"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
        }
      ]
    }
  ]
}
    

Identifica ogni route nel risultato utilizzando l'indice di origine e destinazione per trovare il corrispondente RouteMatrixItem nell'array bidimensionale. Ad esempio, il RouteMatrixItem che descrive la route calcolata dall'origine all'indice 1 e dalla destinazione 0 nella richiesta si troverebbe nel secondo elemento dell'array RouteMatrix.rows e nel primo elemento dell'array RouteMatrixRow.items.

Il seguente snippet di codice mostra come identificare il RouteMatrixItem per trovare la route per un'origine e una destinazione specifiche:

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

Scegli i campi da restituire

Quando richiedi una matrice di route, devi utilizzare una maschera di campo per specificare le informazioni che la risposta deve restituire.

L'utilizzo di una maschera di campo garantisce anche di non richiedere dati non necessari, il che a sua volta contribuisce alla latenza della risposta ed evita di restituire informazioni di cui il sistema non ha bisogno.

Specifica l'elenco dei campi di cui hai bisogno impostando la ComputeRoutesMatrixRequest.fields proprietà, come mostrato nel seguente snippet:

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

Determinare le maschere di campo da utilizzare

Ecco come puoi determinare i campi che vuoi utilizzare e creare le maschere di campo per questi campi:

1. Richiedi tutti i campi utilizzando una maschera di campo ['*'].
   Attenzione: anche se puoi utilizzare questa maschera di campo con carattere jolly durante lo sviluppo per determinare i campi di cui hai bisogno, non utilizzarla in produzione. La richiesta di tutti i campi in produzione comporta costi più elevati e tempi di risposta più lunghi. Il costo potrebbe anche aumentare in modo imprevisto man mano che vengono aggiunte funzionalità avanzate, poiché questa maschera di campo le includerà automaticamente. Richiedi invece solo i campi di cui hai bisogno per ridurre al minimo i costi e il tempo di risposta della richiesta.
2. Esamina la gerarchia dei campi nella RouteMatrixItem classe per i campi che ti interessano.

3. Crea le maschere di campo utilizzando la gerarchia dei campi mostrata nel passaggio precedente, utilizzando questo formato:

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

Ad esempio, per questo RouteMatrixItem:

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

Se vuoi restituire solo il campo tollInfo per RouteMatrixItem, la maschera di campo è la seguente:

fields: ['travelAdvisory.tollInfo']

Se invece vuoi richiedere il consumo di carburante stimato, la maschera di campo è la seguente:

fields: ['travelAdvisory.fuelConsumptionMicroliters']

Se vuoi richiedere entrambi, la maschera di campo è la seguente:

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

Se vuoi richiedere l'insieme completo di avvisi di viaggio, la maschera di campo è la seguente:

fields: ['travelAdvisory']

La gerarchia delle proprietà è disponibile solo per RouteMatrix.computeRouteMatrix, e non è supportata per Route.computeRoutes.

Richiedere una matrice di route di trasporto pubblico

Ottieni una matrice di route di trasporto pubblico che utilizza le opzioni di trasporto pubblico disponibili nella regione. Le opzioni di trasporto pubblico possono includere autobus, metropolitane e treni, tra gli altri. Per richiedere una matrice di route di trasporto pubblico:

• Imposta travelMode su TRANSIT
• Richiedi il campo travelAdvisory.

Scopri di più sulle route di trasporto pubblico.