Specifica le località per un percorso

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ù.

Per calcolare un percorso, devi specificare almeno le località di origine e destinazione del percorso. Definisci queste località come waypoint sul percorso.

Oltre all'origine e alla destinazione, puoi specificare diversi tipi di waypoint e come gestirli per un percorso. Per ulteriori informazioni ed esempi, consulta questi argomenti:

• Specificare l'orientamento del veicolo e il lato della strada
• Specificare i waypoint intermedi
• Impostare una tappa lungo un percorso
• Impostare un punto di passaggio per un percorso
• Ottimizzare l'ordine delle tappe del percorso

Specificare le località per un percorso

Rappresenti una località creando un oggetto Waypoint (REST) o Waypoint (gRPC). Nella definizione del waypoint, puoi specificare una località in uno dei seguenti modi:

• ID luogo (preferito)
• Coordinate di latitudine/longitudine
• Stringa di indirizzo ("Chicago, IL" o "Darwin, NT, Australia")
• Token del punto di navigazione
• Plus Code

Puoi specificare le località per tutti i waypoint in una richiesta nello stesso modo oppure puoi combinarle. Ad esempio, puoi utilizzare le coordinate di latitudine/longitudine per il waypoint di origine e un ID luogo per il waypoint di destinazione.

Per efficienza e accuratezza, utilizza gli ID luogo anziché le coordinate di latitudine/longitudine o le stringhe di indirizzo. Gli ID luogo sono univoci ed espliciti e forniscono vantaggi di geocodifica per il routing, come punti di accesso e variabili di traffico. Aiutano a evitare le seguenti situazioni che possono derivare da altri modi di specificare una località:

• L'utilizzo delle coordinate di latitudine/longitudine può comportare l'allineamento della località alla strada più vicina a queste coordinate, che potrebbe non essere un punto di accesso alla proprietà o persino una strada che conduce rapidamente o in sicurezza alla destinazione.
• Le stringhe di indirizzo devono prima essere geocodificate dall'API Routes per convertire le in coordinate di latitudine/longitudine prima che possa calcolare un percorso. Questa conversione può influire sulle prestazioni.

Specificare una località come ID luogo

Puoi utilizzare un ID luogo per specificare la località di un waypoint. Poiché le coordinate di latitudine e longitudine vengono allineate alle strade, in alcune circostanze potresti trovare un ID luogo che offre risultati migliori.

Recupera gli ID luogo dall'API Geocoding e dall'API Places (incluso Place Autocomplete). Per saperne di più sugli ID luogo, consulta la panoramica degli ID luogo.

L'esempio seguente utilizza la proprietà placeId per passare un ID luogo sia per origin sia per destination:

{
  "origin":{
    "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o"
  },
  "destination":{
    "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU"
  },
  ...
}

Specificare una località come coordinate di latitudine e longitudine

Per definire la località in un waypoint, specifica Location (REST) o Location(gRPC) utilizzando le coordinate di latitudine/longitudine.

Ad esempio, specifica un waypoint per l'origine e la destinazione del percorso origin e destination utilizzando latitude e longitude coordinate:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
...
}

Nota: i punti specificati dalle coordinate di latitudine/longitudine vengono allineati alle strade e potrebbero non fornire l'accuratezza di cui la tua app ha bisogno. Utilizza le coordinate di latitudine/longitudine quando sei certo che i valori specificano effettivamente i punti di cui la tua app ha bisogno per il routing, indipendentemente dai possibili punti di accesso o da ulteriori dettagli di geocodifica.

Specificare una località come stringa di 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, l'API Routes esegue internamente la geocodifica della stringa per convertirla in coordinate di latitudine e longitudine.

Nota: le coordinate di latitudine e longitudine potrebbero essere diverse da quelle restituite dall'API Geocoding. Ad esempio, l'API Routes potrebbe restituire le coordinate per l'ingresso di un edificio anziché per il suo centro.

Ad esempio, per calcolare un percorso, specifica un waypoint per il percorso origin e destination utilizzando le stringhe di indirizzo:

{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "450 Serra Mall, Stanford, CA 94305, USA"
  },
  ...
}

In questo esempio, l'API Routes esegue la geocodifica di entrambi gli indirizzi per convertirli in coordinate di latitudine e longitudine.

Se il valore dell'indirizzo è ambiguo, l'API Routes potrebbe richiamare una ricerca per disambiguare gli indirizzi simili. Ad esempio, "1st Street" potrebbe essere un valore completo o un valore parziale per "1st street NE" o "1st St SE". Questo risultato potrebbe essere diverso da quello restituito dall'API Geocoding. Puoi evitare possibili interpretazioni errate utilizzando gli ID luogo.

Impostare la regione per l'indirizzo

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

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE"
}

In questo esempio, "Toledo" viene interpretata come una città dello stato dell'Ohio negli Stati Uniti, non in Spagna. Di conseguenza, la richiesta restituisce un array vuoto, il che significa che non esistono percorsi:

{
  []
}

Puoi configurare l'API in modo che restituisca risultati orientati a una regione specifica includendo il parametro regionCode. Questo parametro specifica il codice regione come un ccTLD ("dominio di primo livello") valore di due caratteri. La maggior parte dei codici ccTLD sono identici ai codici ISO 3166-1, con alcune eccezioni notevoli. 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:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE",
  "regionCode": "es"
}

La risposta ora contiene il percorso calcolato da Toledo, Spagna a Madrid, Spagna:

{
  "routes": [
    {
      "distanceMeters": 75330,
      "duration": "4137s",
      ...
    }
  ]
}

Specificare una località come token del punto di navigazione

Questo prodotto o funzionalità è in anteprima (pre-GA). I prodotti e le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Le offerte pre-GA sono coperte da Google Termini specifici di servizio di Google Maps Platform. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Un token del punto di navigazione è una stringa che codifica una località e un contesto di percorso aggiuntivo. I token del punto di navigazione possono fornire un routing preciso a punti di accesso specifici vicino a ingressi, banchine di carico o aree di ritiro designate. È utile in casi come la consegna di cibo o il ridesharing, in cui il punto di ritiro o riconsegna potrebbe essere ambiguo.

Puoi ottenere un token del punto di navigazione chiamando il metodo Destinations dell'API Geocoding.

Per specificare un token del punto di navigazione:

1. Ottieni un navigationPointToken dal metodo SearchDestinations dell'API Geocoding. Per ulteriori informazioni, consulta la documentazione dell'API Geocoding.
2. Crea un waypoint passando il navigationPointToken.

L'esempio seguente utilizza la proprietà navigation_point_token per passare un token del punto di navigazione sia per origin sia per destination:

{
  "origin":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_ORIGIN"
  },
  "destination":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_DESTINATION"
  },
  ...
}

Specificare una località come 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 accettare le consegne in località più specifiche, come un ingresso posteriore o una banchina di carico.

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

Google ha sviluppato i Plus Code per offrire il vantaggio degli indirizzi a tutti e a tutto. Un Plus Code è un riferimento di località codificato, derivato da 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 più piccola. Puoi utilizzare i Plus Code in sostituzione degli indirizzi stradali in 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:

• Un 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". Quindi, utilizza l'intero Plus Code di 10 caratteri per specificare il valore della località come "849VCWC8+R9".

• Un codice composto è composto da un codice locale di almeno 6 caratteri combinato con una località 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 parte dell'indirizzo relativa a città, stato, codice postale e paese nel formato "CRHJ+C3 Stanford, CA 94305, USA".

  Ad esempio, calcola un percorso specificando un waypoint per l'origine origin e destination utilizzando i Plus Code:

  {
    "origin":{
      "address": "849VCWC8+R9"
    },
    "destination":{
      "address": "CRHJ+C3 Stanford, CA 94305, USA"
    },
    "travelMode": "DRIVE"
  }

I Plus Code sono supportati nelle API Google Maps Platform, tra cui Place Autocomplete, Place Details, API Directions (legacy), e API Geocoding. Ad esempio, puoi utilizzare l'API Geocoding per eseguire la geocodifica inversa di una località specificata dalle coordinate di latitudine/longitudine per determinare il Plus Code della località.