Specifica le località per un percorso

Per calcolare un percorso, è necessario specificare almeno le posizioni dell'origine e della destinazione dell'itinerario. Puoi definire queste località come waypoint lungo il percorso.

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

Specifica le località di una route

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

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

Per efficienza e precisione, utilizza gli ID luogo anziché le coordinate di latitudine/longitudine o le stringhe di indirizzi. Gli ID luogo sono espliciti in modo univoco e offrono vantaggi di geocodifica per il routing, ad esempio punti di accesso e variabili di traffico. Consentono di evitare le seguenti situazioni che possono derivare da altri modi per specificare una località:

  • L'utilizzo delle coordinate di latitudine/longitudine può comportare l'allineamento della posizione alla strada più vicina a queste coordinate, che potrebbe non essere un punto di accesso alla proprietà o persino una strada che conduce alla destinazione in modo rapido o sicuro.
  • Le stringhe di indirizzi devono essere prima geocodificate e convertite in coordinate di latitudine/longitudine prima che l'API Routes possa calcolare un percorso. Questa conversione può influire sul rendimento.

Specifica una località come ID luogo

Puoi utilizzare un ID luogo per specificare la posizione di un waypoint. Poiché le coordinate di latitudine e longitudine sono agganciate alle strade, potresti scoprire che un ID luogo offre risultati migliori in alcune circostanze.

Recupera gli ID luogo dall'API Geocoding e dall'API Places (incluso Place Autocomplete). Per ulteriori informazioni 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"
  },
  ...
}

Specifica una località come coordinate di latitudine e longitudine

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

Ad esempio, specifica un waypoint per il percorso origin e destination utilizzando le coordinate latitude e longitude:

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

Specifica una località come stringa indirizzo

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

Quando passi una stringa indirizzo come posizione di un waypoint, l'API Routes geocodifica internamente la stringa per convertirla in coordinate di latitudine e longitudine.

Ad esempio, per calcolare un percorso, specifichi un waypoint per il percorso origin e destination utilizzando stringhe di indirizzi:

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

In questo esempio, l'API Routes geocodifica 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 distinguere gli indirizzi simili. Ad esempio, "Via 1" potrebbe essere un valore completo o parziale per "Via 1° a SE" o "Via Roma 12". Questo risultato potrebbe essere diverso da quello restituito dall'API Geocoding. Puoi evitare possibili interpretazioni errate utilizzando gli ID luogo.

Imposta la regione per l'indirizzo

Se trasmetti una stringa indirizzo incompleta per la posizione di un waypoint, l'API potrebbe utilizzare le coordinate di latitudine e longitudine geocodificate errate. Ad esempio, fai 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 interpretato 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 route:

{
  []
}

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

Una richiesta di indicazioni stradali da "Toledo" a "Madrid" che include il parametro regionCode restituisce i risultati appropriati perché "Toledo" viene interpretato 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",
      ...
    }
  ]
}

Specifica una località come Plus Code

Molte persone non hanno un indirizzo preciso, il che può complicare la ricezione delle consegne. Oppure, le persone con un indirizzo potrebbero preferire accettare le consegne in luoghi più specifici, come un ingresso sul retro o un carico di lavoro.

I plus code sono come gli indirizzi stradali di persone o luoghi che non hanno un indirizzo effettivo. Invece degli indirizzi con i nomi delle vie e i numeri, i Plus Code sono basati su coordinate di latitudine e longitudine e vengono visualizzati come numeri e lettere.

Google ha sviluppato i Plus Code per offrire il vantaggio degli indirizzi a tutti. Un Plus Code è un riferimento di località codificato, ricavato dalle coordinate di latitudine/longitudine, che rappresenta un'area: 1/8000° di grado per 1/8000° di grado (circa 14 x 14 m all'equatore) o inferiore. 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 nomi.

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

  • Un codice globale è costituito da un prefisso di quattro caratteri e un codice locale di almeno sei caratteri.

    Ad esempio, per l'indirizzo "1600 Amphitheatre Parkway, Mountain View, CA", il codice globale è "849V" e il codice locale è "CWC8+R9". Successivamente, utilizzerai l'intero Plus Code di 10 caratteri per specificare il valore della posizione come "849VCWC8+R9".

  • Un codice locale è costituito da un codice locale di almeno 6 caratteri combinato con una posizione esplicita.

    Ad esempio, l'indirizzo "450 Serra Mall, Stanford, CA 94305, USA" ha il codice locale "CRHJ+C3". Per un indirizzo composto, combina il codice locale con la parte della città, dello stato, del codice postale e del paese dell'indirizzo nel formato "CRHJ+C3 Stanford, CA 94305, USA".

    Ad esempio, calcola un percorso specificando un waypoint per la rotta 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 di Google Maps Platform, tra cui Place Autocomplete, Place Details, API Directions e API Geocoding. Ad esempio, puoi utilizzare l'API Geocoding per eseguire la geocodifica inversa di una località specificata con le coordinate di latitudine/longitudine per determinare il Plus Code della località.