Trova un percorso

Sviluppatori dello Spazio economico europeo (SEE)

Un percorso è un tragitto navigabile tra una località di partenza, o origine, e una località di arrivo, o destinazione. Puoi scegliere di ottenere un percorso per diverse modalità di trasporto, ad esempio a piedi, in bicicletta o con diversi tipi di veicoli. Puoi anche richiedere dettagli sul percorso, come la distanza, il tempo stimato per percorrerlo, i pedaggi previsti e le istruzioni passo passo per percorrerlo.

Visualizza il codice sorgente dell'esempio completo

Il seguente esempio di codice mostra come ottenere un percorso per le indicazioni stradali tra due località.

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();

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();

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;
}

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>

Prova l'esempio

Chiama il metodo computeRoutes() per richiedere un percorso tra due località. L'esempio seguente mostra la definizione di una richiesta e la successiva chiamata a computeRoutes() per ottenere un percorso. computeRoutes() è un metodo statico della classe Route, quindi chiama direttamente Route.computeRoutes(request). La richiesta deve inoltre impostare la proprietà fields su una maschera di campo della risposta. 

  // 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);

Per tracciare il percorso su una mappa, chiama createPolylines() su un percorso richiesto con il campo path. Consulta Visualizza le polilinee su una mappa.

Scegli i campi da restituire

Quando richiedi un percorso, devi utilizzare una maschera di campo per specificare quali informazioni deve restituire la risposta. Puoi specificare i nomi delle proprietà della classe Route nella maschera di campo.

L'utilizzo di una maschera di campo garantisce inoltre che non vengano richiesti 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 necessari impostando la proprietà ComputeRoutesRequest.fields, come mostrato nello snippet seguente:

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.
};

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.
};

Specifica le località per un percorso

Per calcolare un percorso, devi specificare almeno le località di origine e destinazione del percorso e una maschera di campo. Puoi anche specificare waypoint intermedi lungo un percorso e utilizzarli per eseguire altre operazioni, ad esempio aggiungere fermate o punti di passaggio lungo un percorso.

In ComputeRoutesRequest, puoi specificare una località in uno dei seguenti modi:

Puoi specificare le località per tutte le tappe di una richiesta nello stesso modo o combinarle. Ad esempio, puoi utilizzare le coordinate di latitudine/longitudine per il waypoint di partenza e un oggetto Place per il waypoint di destinazione.

Per efficienza e precisione, utilizza gli oggetti Place anziché le coordinate di latitudine/longitudine o le stringhe di indirizzo. Gli ID luogo sono univoci ed espliciti e offrono vantaggi di geocodifica per il routing, come punti di accesso e variabili di traffico. Consentono di evitare le seguenti situazioni che possono verificarsi con altri modi di specificare una località:

  • L'utilizzo delle coordinate di latitudine/longitudine può comportare l'aggancio della posizione alla strada più vicina a queste coordinate, che potrebbe non essere un punto di accesso alla proprietà o nemmeno una strada che conduce rapidamente o in sicurezza alla destinazione.
  • Le stringhe di indirizzo devono prima essere geocodificate dall'API Routes per convertirle in coordinate di latitudine/longitudine prima di poter calcolare un percorso. Questa conversione può influire sul rendimento.

Specifica una località come oggetto Place (opzione preferita)

Per specificare una località utilizzando un luogo, crea una nuova istanza Place. Lo snippet seguente mostra la creazione di nuove istanze Place per origin e destination, quindi il loro utilizzo in un 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.
};

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.
};

Coordinate di latitudine/longitudine

Per specificare una località come coordinate di latitudine/longitudine, crea una nuova istanza google.maps.LatLngLiteral, google.maps.LatLngAltitude o google.maps.LatLngAltitudeLiteral. Lo snippet seguente mostra la creazione di nuove istanze google.maps.LatLngLiteral per origin e destination, quindi il loro utilizzo in un 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'],
};

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'],
};

Stringa dell'indirizzo

Le stringhe di indirizzo sono indirizzi letterali rappresentati da una stringa (ad esempio "1600 Amphitheatre Parkway, Mountain View, CA"). La geocodifica è il processo di conversione di una stringa di indirizzo in coordinate di latitudine e longitudine (ad esempio, latitudine 37.423021 e longitudine -122.083739).

Quando passi una stringa di indirizzo come località di un waypoint, la libreria Routes geocodifica internamente la stringa per convertirla in coordinate di latitudine e longitudine.

Lo snippet seguente mostra la creazione di un ComputeRoutesRequest con una stringa di indirizzo per 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'],
};

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'],
};

Imposta la regione per l'indirizzo

Se passi una stringa di indirizzo incompleta come posizione di un waypoint, l'API potrebbe utilizzare coordinate di latitudine/longitudine geocodificate errate. Ad esempio, effettui una richiesta specificando "Toledo" come origine e "Madrid" come destinazione per un percorso in auto: 

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

In questo esempio, "Toledo" viene interpretato come una città nello stato dell'Ohio negli Stati Uniti, non in Spagna. Pertanto, la richiesta restituisce un array vuoto, il che significa che non esistono route.

Puoi configurare l'API in modo che restituisca risultati orientati verso una determinata regione includendo il parametro regionCode. Questo parametro specifica il codice regione come valore di due caratteri di un ccTLD ("dominio di primo livello"). La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk " (.co.uk), mentre il suo codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").

Una richiesta di indicazioni stradali da "Toledo" a "Madrid" che include il parametro regionCode restituisce risultati appropriati perché "Toledo" viene interpretata come una città in Spagna:

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

Plus Code

Molte persone non hanno un indirizzo preciso, il che può rendere difficile la ricezione delle consegne. In alternativa, le persone con un indirizzo potrebbero preferire ricevere le consegne in luoghi più specifici, come un ingresso sul retro o una banchina di carico.

I Plus Code sono come indirizzi via per persone o luoghi che non hanno un indirizzo effettivo. Anziché indirizzi con nomi e numeri di vie, i Plus Code si basano sulle coordinate di latitudine/longitudine e vengono visualizzati come numeri e lettere.

Google ha sviluppato i Plus Code per offrire a tutti e per tutto i vantaggi degli indirizzi. Un Plus Code è un riferimento di posizione codificato, derivato dalle coordinate di latitudine/longitudine, che rappresenta un'area: 1/8000 di grado per 1/8000 di grado (circa 14 m x 14 m all'equatore) o inferiore. Puoi utilizzare i Plus Code in sostituzione delle vie nei luoghi in cui non esistono o in cui gli edifici non sono numerati o le strade non hanno un nome.

I Plus Code devono essere formattati come codice globale o codice composto:

  • Il codice globale è composto da un prefisso di 4 caratteri e un codice locale di almeno 6 caratteri. Ad esempio, per l'indirizzo "1600 Amphitheatre Parkway, Mountain View, CA", il codice globale è "849V" e il codice locale è "CWC8+R9". Poi, utilizza l'intero Plus Code di 10 caratteri per specificare il valore della località come "849VCWC8+R9".
  • Un codice composto è costituito da un codice locale di almeno sei caratteri combinato con una posizione esplicita. Ad esempio, l'indirizzo "450 Serra Mall, Stanford, CA 94305, USA" ha un codice locale "CRHJ+C3". Per un indirizzo composto, combina il codice locale con la città, lo stato, il codice postale e il paese dell'indirizzo nel formato "CRHJ+C3 Stanford, CA 94305, USA".

Il seguente snippet mostra il calcolo di un percorso specificando un waypoint per l'origine e la destinazione del percorso utilizzando i Plus Code:

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'],
};

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'],
};