Specifica le località per un percorso

Per calcolare un percorso, devi specificare almeno le posizioni di partenza e di destinazione del percorso. Queste località vengono definite come waypoint sul percorso.

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

Specificare le località per un percorso

Rappresenta una posizione creando un oggetto Waypoint (REST) o Waypoint (gRPC). Nella definizione del punto di passaggio, puoi specificare una posizione in uno dei seguenti modi:

Puoi specificare le posizioni di tutti i waypoint in una richiesta nello stesso modo o combinarle. Ad esempio, puoi utilizzare le coordinate di latitudine/longitudine per il waypoint di partenza e 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. Ti aiutano a evitare le seguenti situazioni che possono verificarsi con altri modi di 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 porta rapidamente o in sicurezza alla destinazione.
  • Le stringhe di indirizzi devono prima essere geocodificate dall'API Routes per convertirle in coordinate di latitudine/longitudine prima che possa essere calcolato un percorso. Questa conversione può influire sul rendimento.

Specificare 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 allineate alle strade, potresti trovare un ID luogo che offre risultati migliori in alcune circostanze.

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 posizione in una tappa, specifica Posizione (REST) o Posizione(gRPC) utilizzando le coordinate di latitudine/longitudine.

Ad esempio, specifica un punto di passaggio 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 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 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 punto di passaggio 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 eseguire una ricerca per eliminare l'ambiguità rispetto ad indirizzi simili. Ad esempio, "1st Street" potrebbe essere un valore completo o 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.

Imposta la regione per l'indirizzo

Se passi una stringa di indirizzo incompleta come posizione di un waypoint, l'API potrebbe utilizzare le coordinate di latitudine/longitudine geocodificate errate. Ad esempio, effettui una richiesta specificando "Toledo" come località di partenza e "Madrid" come destinazione per un itinerario 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 orientati a una determinata regione includendo il parametro regionCode. Questo parametro specifica il codice regione come valore di due caratteri di un ccTLD ("top-level domain"). La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni notevoli. Ad esempio, il TLD di primo livello del Regno Unito è "uk " (.co.uk), mentre il codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Il 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 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, in Spagna, a Madrid, in Spagna:

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

Specificare una località come Plus Code

Molte persone non hanno un indirizzo preciso, il che può complicare la ricezione delle spedizioni. In alternativa, le persone con un indirizzo potrebbero preferire accettare le consegne in località più specifiche, come un ingresso secondario o una banchina di carico.

I plus code sono come gli indirizzi stradali per persone o luoghi che non hanno un indirizzo reale. Invece di indirizzi con nomi e numeri di strade, 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 i vantaggi degli indirizzi a tutti e a tutto. 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 più piccola. Puoi utilizzare i Plus Code come sostituti degli indirizzi in luoghi in cui non esistono, in cui gli edifici non sono numerati o in cui le strade non hanno un nome.

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

  • Un codice globale è composto da un codice area di 4 caratteri e da 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 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 punto di passaggio per il percorso origin e destination utilizzando i plus code:

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

I codici Plus sono supportati nelle API di Google Maps Platform, tra cui Completamento automatico dei luoghi, Dettagli dei luoghi, API Directions e API Geocoding. Ad esempio, puoi utilizzare l'API Geocoding per eseguire il reverse geocoding di una località specificata dalle coordinate di latitudine/longitudine per determinare il relativo Plus Code.