Specifica le località per un percorso

Per calcolare una route, devi specificare almeno le località dell'origine della route e della destinazione della route. Queste località vengono definite come waypoint lungo il percorso.

Oltre a origine e destinazione, puoi specificare diversi tipi di tappe e come gestire le tappe per un percorso. Per ulteriori informazioni ed esempi, consulta questi argomenti:

Specificare le posizioni di un percorso

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

Puoi specificare le posizioni di tutte le tappe nello stesso modo oppure puoi combinarle in una richiesta. Ad esempio, puoi utilizzare le coordinate di latitudine/longitudine per la tappa di partenza e un ID luogo per la tappa di destinazione.

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

  • L'uso 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 consente di raggiungere la destinazione in modo rapido o sicuro.
  • Le stringhe degli indirizzi 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 ID luogo

Puoi utilizzare un ID luogo per specificare la posizione di una tappa. Poiché le coordinate di latitudine e longitudine sono agganciate alle strade, in alcuni casi un ID luogo potrebbe offrire risultati migliori.

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

Ad esempio, specifica una tappa 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 degli 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 di indirizzi in coordinate di latitudine e longitudine (ad esempio latitudine 37.423021 e longitudine -122.083739).

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

Ad esempio, per calcolare un percorso, devi specificare un waypoint per le route origin e destination utilizzando le 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 codifica 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 distinguerla da indirizzi simili. Ad esempio, "1st Street" potrebbe essere un valore completo o un valore parziale per "1st Street NE" o "1st Street 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 trasmetti una stringa di indirizzi incompleta come posizione di una tappa, l'API potrebbe utilizzare coordinate di latitudine/longitudine geocodificate errate. Ad esempio, puoi effettuare una richiesta specificando "Toledo" come origine e "Madrid" come destinazione di un percorso in auto:

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

In questo esempio, "Toledo" viene interpretata come una città nello 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 includendo il parametro regionCode. Questo parametro specifica il codice regione come un valore di due caratteri 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 codice ISO 3166-1 è"gb " (tecnicamente per l'entità "The United Kingdom of Gran Bretagna e Irlanda del Nord").

Una richiesta di indicazioni stradali per "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 la rotta calcolata da Toledo, Spagna a Madrid, Spagna:

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

Specifica una posizione come Plus Code

Molte persone non hanno un indirizzo preciso e questo può rendere difficile ricevere le consegne. Oppure, chi dispone di un indirizzo potrebbe preferire le consegne in luoghi più specifici, come un ingresso sul retro o un dock di carico.

I Plus Code sono come gli indirizzi di persone o luoghi che non hanno un indirizzo effettivo. Al posto degli indirizzi con i nomi delle vie e i numeri, i Plus Code si basano sulle coordinate di latitudine e longitudine e vengono visualizzati come numeri e lettere.

Google ha sviluppato i Plus Code per mostrare il vantaggio degli indirizzi a chiunque. 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 degli indirizzi stradali di luoghi in cui non sono presenti o in cui gli edifici non sono numerati o non sono stati denominati le strade.

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

  • Un codice globale è composto da un prefisso 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". Puoi quindi utilizzare l'intero Plus Code di 10 caratteri per specificare il valore della posizione come "849VCWC8+R9".

  • Un codice composto è composto 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 città, lo stato, il codice postale e la parte del paese dell'indirizzo nel formato "CRHJ+C3 Stanford, CA 94305, USA".

    Ad esempio, calcola un percorso specificando una tappa 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 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 geocodificare una località specificata da coordinate di latitudine/longitudine per determinare il Plus Code della sede.