Questa pagina è stata tradotta dall'API Cloud Translation.

Esamina la risposta del percorso

Quando l'API Routes calcola un percorso, prende come input i parametri di configurazione e i waypoint che fornisci. L'API restituisce quindi una risposta che contiene il percorso predefinito e uno o più percorsi alternativi.

La risposta può includere diversi tipi di percorsi e altri dati, in base ai campi richiesti:

Per includere questa informazione nella risposta	Consulta questa documentazione
Il percorso più efficiente dal punto di vista del consumo di carburante o di energia elettrica in base al tipo di motore del veicolo.	Configurare i percorsi ecosostenibili
Fino a tre percorsi alternativi	Richiedi percorsi alternativi
Il polilinea per un'intera tratta, per ogni tratto di un percorso e per ogni passaggio di un tratto.	Richiedi polilinee del percorso
I pedaggi stimati, tenendo conto di eventuali sconti sul prezzo del pedaggio o tessere disponibili per il conducente o il veicolo.	Calcolare le tariffe dei pedaggi
Risposte localizzate per codici lingua e unità di misura (sistema imperiale o metrico).	Richiedi valori localizzati
Per formattare le istruzioni di navigazione come stringa di testo HTML, aggiungi `HTML_FORMATTED_NAVIGATION_INSTRUCTIONS` a `extraComputations`.	Calcoli extra

Per l'elenco completo delle opzioni di input, consulta Opzioni di percorso disponibili e il corpo della richiesta.

Utilizzando la risposta, puoi fornire ai tuoi clienti le informazioni necessarie per selezionare il percorso appropriato per le loro esigenze.

Informazioni sulle maschere dei campi

Quando chiami un metodo per calcolare un percorso, devi specificare una maschera di campi che definisce i campi da restituire nella risposta. Non esiste un elenco predefinito dei campi restituiti. Se ometti questo elenco, i metodi restituiscono un errore.

Gli esempi in questo documento mostrano l'intero oggetto di risposta senza prendere in considerazione le maschere di campo. In un ambiente di produzione, la risposta includerebbe solo i campi specificati esplicitamente nella maschera di campo.

Per ulteriori informazioni, consulta Scegliere le informazioni da restituire.

Informazioni sulla visualizzazione dei copyright

Quando mostri i risultati agli utenti, devi includere la seguente dichiarazione sul copyright:

Powered by Google, ©YEAR Google

Ad esempio:

Informazioni su percorsi, tratti e passaggi

Prima di esaminare la risposta restituita dall'API Routes, devi conoscere i componenti che compongono un itinerario:

Il percorso, la tappa e il passaggio.

La risposta può contenere informazioni su ciascuno di questi componenti del percorso:

Percorso: l'intero viaggio dal waypoint di partenza, attraverso eventuali waypoint intermedi, al waypoint di destinazione. Un itinerario è costituito da uno o più tratte.
Tappa: il percorso da un waypoint in un percorso al waypoint successivo nel percorso. Ogni tratto è costituito da uno o più passaggi distinti.

Un itinerario contiene un tratto separato per il percorso da ogni waypoint al successivo. Ad esempio, se il percorso contiene un singolo waypoint di partenza e un singolo waypoint di destinazione, il percorso contiene un singolo tratto. Per ogni waypoint aggiuntivo che aggiungi al percorso dopo l'origine e la destinazione, chiamato waypoint intermedio, l'API aggiunge un tratto separato.

L'API non aggiunge un tratto per un punto di passaggio intermedio pass-through. Ad esempio, un percorso che contiene un punto di passaggio intermedio, un punto di passaggio intermedio e un punto di passaggio intermedio contiene un solo tratto dall'origine alla destinazione, passando per il punto di passaggio intermedio. Per ulteriori informazioni sui waypoint passthrough, consulta Definire un waypoint passthrough.
Passaggio: una singola istruzione lungo il tratto di un itinerario. Un passaggio è l'unità più atomica di un percorso. Ad esempio, un passaggio può indicare "Svolta a sinistra su Corso Garibaldi".

Contenuto della risposta

L'oggetto JSON che rappresenta la risposta dell'API contiene le seguenti proprietà di primo livello:

routes, un array di elementi di tipo Route. L'array routes contiene un elemento per ogni percorso restituito dall'API. L'array può contenere un massimo di cinque elementi: il percorso predefinito, il percorso ecosostenibile e fino a tre percorsi alternativi.
geocodingResults, un array di elementi di tipo GeocodingResults. Per ogni località nella richiesta (origine, destinazione o punto di passaggio intermedio) specificata come stringa di indirizzo o come Plus Code, l'API esegue una ricerca dell'ID luogo. Ogni elemento di questo array contiene l'ID luogo corrispondente a una località. Le località nella richiesta specificate come ID luogo o come coordinate di latitudine/longitudine non sono incluse. Se hai specificato tutte le località utilizzando gli ID luogo o le coordinate di latitudine e longitudine, questo array non viene fornito.
fallbackInfo, di tipo FallbackInfo. Se l'API non è in grado di calcolare un percorso da tutte le proprietà di input, potrebbe ricorrere a un metodo di calcolo diverso. Quando viene utilizzata la modalità di riserva, questo campo contiene informazioni dettagliate sulla risposta di riserva. In caso contrario, questo campo non è impostato.

La risposta ha il seguente formato:

{
  // The routes array.
  "routes": [
    {
      object (Route)
    }
  ],
  // The place ID lookup results.
  "geocodingResults": [
    {
      object (GeocodedWaypoint)
    }
  ],
  // The fallback property.
  "fallbackInfo": {
    object (FallbackInfo)
  }
}

Decifrare l'array di route

La risposta contiene l'array routes, in cui ogni elemento dell'array è di tipo Route. Ogni elemento dell'array rappresenta un intero percorso dall'origine alla destinazione. L'API restituisce sempre almeno un percorso, chiamato percorso predefinito.

Puoi richiedere percorsi aggiuntivi. Se richiedi un percorso ecosostenibile, l'array può contenere due elementi: il percorso predefinito e il percorso ecosostenibile. In alternativa, imposta computeAlternativeRoutes su true nella richiesta per aggiungere fino a tre percorsi alternativi alla risposta.

Ogni percorso nell'array è identificato con la proprietà array routeLabels:

Valore	Descrizione
`DEFAULT_ROUTE`	Identifica la route predefinita.
`FUEL_EFFICIENT`	Identifica il percorso ecosostenibile.
`DEFAULT_ROUTE_ALTERNATE`	Indica un percorso alternativo.

L'array legs contiene la definizione di ogni tratto del percorso. Le proprietà rimanenti, come distanceMeters, duration e polyline,, contengono informazioni sul percorso nel suo complesso:

{
  "routeLabels": [
    enum (RouteLabel)
  ],
  "legs": [
    {
      object (RouteLeg)
    }
  ],
  "distanceMeters": integer,
  "duration": string,
  "routeLabels": [string],
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "description": string,
  "warnings": [
    string
  ],
  "viewport": {
    object (Viewport)
  },
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  }
  "routeToken": string
}

A causa delle condizioni di guida attuali e di altri fattori, il percorso predefinito e il percorso ecosostenibile possono essere gli stessi. In questo caso, l'array routeLabels contiene entrambe le etichette: DEFAULT_ROUTE e FUEL_EFFICIENT.

{
  "routes": [
    {
      "routeLabels": [
        "DEFAULT_ROUTE",
        "FUEL_EFFICIENT"
      ],
     …
    }
  ]
}

Informazioni sull'array legs

Ogni route nella risposta contiene un array legs, in cui ogni elemento dell'array legs è di tipo RouteLeg. Ogni tratto nell'array definisce il percorso da un waypoint al successivo lungo il percorso. Un itinerario contiene sempre almeno una tappa.

La proprietà legs contiene la definizione di ogni passaggio del tratto nell'array steps. Le proprietà rimanenti, come distanceMeters, duration e polyline, contengono informazioni sulla tratta.

{
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "steps": [
    {
      object (RouteLegStep)
    }
  ],
  "travelAdvisory": {
    object (RouteLegTravelAdvisory)
  }
}

Informazioni sull'array steps

Ogni tratto nella risposta contiene un array steps, in cui ogni elemento dell'array steps è di tipo RouteLegStep. Un passaggio corrisponde a una singola istruzione lungo il tratto. Un tratto contiene sempre almeno un passaggio.

Ogni elemento dell'array steps include la proprietà navigationInstruction, di tipo NavigationInstruction, che contiene l'istruzione del passaggio. Ad esempio:

"navigationInstruction": {
  "maneuver": "TURN_LEFT",
  "instructions": "Turn left toward Frontage Rd"
}

instructions potrebbe contenere informazioni aggiuntive sul passaggio. Ad esempio:

"navigationInstruction": {
  "maneuver": "TURN_SLIGHT_LEFT",
  "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days"
}

Le proprietà rimanenti nel passaggio descrivono informazioni sul passaggio, ad esempio distanceMeters, duration e polyline:

{
  "distanceMeters": integer,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "navigationInstruction": {
    object (NavigationInstruction)
  }
}

Specifica la lingua delle istruzioni del passaggio

L'API restituisce le informazioni sul percorso nella lingua locale, traslitterate in uno script leggibile dall'utente, se necessario, rispettando la lingua preferita. I componenti dell'indirizzo vengono restituiti tutti nella stessa lingua.

Utilizza il parametro languageCode di una richiesta per impostare esplicitamente la lingua del percorso dall'elenco delle lingue supportate. Google aggiorna spesso le lingue supportate, pertanto questo elenco potrebbe non essere esaustivo.
Se un nome non è disponibile nella lingua specificata, l'API utilizza la corrispondenza più simile.
La lingua specificata può influire sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che possono essere validi in una lingua, ma non in un'altra. Ad esempio, utca e tér sono sinonimi di strada in ungherese.

Informazioni sull'array geocodingResults

Per ogni località nella richiesta (di partenza, di destinazione o intermedia) specificata come stringa di indirizzo o come plus code, l'API tenta di trovare la località più pertinente con un ID luogo corrispondente. Ogni elemento dell'array geocodingResults contiene il campo placeID contenente la località come ID luogo e un campo type che specifica il tipo di località, ad esempio street_address, premise o airport.

L'array geocodingResults contiene tre campi:

origin: se è stato specificato come stringa di indirizzo o come Plus Code, l'ID luogo dell'origine. In caso contrario, questo campo viene omesso dalla risposta.
destination: se è stato specificato come stringa di indirizzo o come plus code, l'ID luogo della destinazione. In caso contrario, questo campo viene omesso dalla risposta.
intermediates: un array contenente l'ID luogo di eventuali waypoint intermedi specificati come stringa di indirizzo o come Plus Code. Se specifichi un punto intermedio utilizzando un ID luogo o le coordinate di latitudine e longitudine, questo viene omesso dalla risposta. Utilizza la proprietà intermediateWaypointRequestIndex nella risposta per determinare quale waypoint intermedio nella richiesta corrisponde all'ID luogo nella risposta.

"geocodingResults": {
    "origin": {
        "geocoderStatus": {},
        "type": [
             enum (Type)
        ],
        "placeId": string
    },
    "destination": {
        "geocoderStatus": {},
        "type": [
            enum (Type)
        ],
        "placeId": string
    },
    "intermediates": [
        {
            "geocoderStatus": {},
            "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        },
        {
           "geocoderStatus": {},
           "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        }
    ]
}

Informazioni sui valori di risposta localizzati

I valori di risposta localizzati sono un campo di risposta aggiuntivo che fornisce testo localizzato per i valori dei parametri restituiti. Il testo localizzato è fornito per la durata della corsa, la distanza e il sistema di unità di misura (metrico o imperiale). Richiedi valori localizzati utilizzando una maschera di campo e puoi specificare la lingua e il sistema di unità o utilizzare i valori dedotti dall'API. Per maggiori dettagli, consulta LocalizedValues.

Ad esempio, se specifichi un codice lingua per il tedesco (de) e le unità imperiali, ottieni un valore per distanceMeters pari a 49889,7, ma anche un testo localizzato che fornisce la misurazione della distanza in tedesco e unità imperiali, quindi "31 Meile".

Ecco un esempio di ciò che vedrai per i valori localizzati:

{ "localized_values":
  {
    "distance": { "text": "31,0 Meile/n" },
    "duration": { "text": 38 Minuten}.
    "static_duration": { "text": 36 Minuten}.
  }
}

Nota: vengono visualizzati due valori per la durata prevista:duration utilizza il modello di traffico specificato estatic_duration non tiene conto del traffico. Pertanto, se il modello di traffico richiesto è TRAFFIC_UNAWARE, questi tempi sono identici.

Se non specifichi la lingua o il sistema di unità, l'API deducono la lingua e le unità come segue:

Il metodo ComputeRoutes deducono le unità di misura della posizione e della distanza dal waypoint di partenza. Pertanto, per una richiesta di routing negli Stati Uniti, l'API deduce la lingua en-US e le unità IMPERIAL.
Il metodo ComputeRouteMatrix ha come valore predefinito la lingua "en-US" e le unità di misura METRIC.