Questa pagina è stata tradotta dall'API Cloud Translation.

Esamina la risposta del percorso

Quando l'API Routes calcola una route, utilizza i waypoint e i parametri di configurazione che hai fornito come input. L'API restituisce quindi una risposta contenente la route default e una o più route alternative.

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

Includerlo nella risposta	Visualizza questa documentazione
Il percorso a più basso consumo di carburante o energia in base al tipo di motore del veicolo.	Configurare route ecosostenibili
Fino a tre percorsi alternativi	Richiedere percorsi alternativi
La polilinea per un intero percorso, per ogni tratto del percorso e per ogni passo di un tratto.	Richiedi polilinee della route
Pedaggi stimati, tenendo conto di eventuali sconti o pass disponibili per il conducente o il veicolo.	Calcolare le tariffe pedaggi
Risposte localizzate in base ai codici lingua e all'unità di misura (imperiale o metrica).	Richiedere valori localizzati
Per formattare le istruzioni di navigazione come stringa di testo HTML, aggiungi `HTML_FORMATTED_NAVIGATION_INSTRUCTIONS` a `extraComputations`.	Computazioni extra

Per l'elenco completo delle opzioni di input, vedi Opzioni di route disponibili e il Corpo della richiesta.

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

Informazioni sulle maschere dei campi

Quando chiami un metodo per calcolare una route, devi specificare una maschera di campo che definisca i campi che vuoi che vengano restituiti nella risposta. Non esiste un elenco predefinito di campi restituiti. Se ometti questo elenco, i metodi restituiscono un errore.

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

Per ulteriori informazioni, vedi Scegliere quali informazioni restituire.

Informazioni sulla visualizzazione di contenuti protetti da copyright

Devi includere la seguente dichiarazione sul copyright quando mostri i risultati agli utenti:

Powered by Google, ©YEAR Google

Ad esempio:

Informazioni su percorsi, tappe e passi

Prima di esaminare la risposta restituita dall'API Routes, dovresti aver compreso i componenti che costituiscono una route:

Percorso, tratta e passo.

La tua risposta potrebbe contenere informazioni su ciascuno dei seguenti componenti del percorso:

Route: l'intero percorso dal waypoint di origine, attraverso qualsiasi waypoint intermedio, al waypoint di destinazione. Un percorso è costituito da una o più tratto.
Gamba: il percorso da un waypoint in un percorso al waypoint successivo nel percorso. Ogni tratto è costituito da uno o più passaggi discreti.

Un percorso contiene una tratta separata per il percorso da ogni tappa a quella successiva. Ad esempio, se contiene un solo waypoint di origine e un singolo point di destinazione, la route contiene un solo tratto. Per ogni waypoint aggiuntivo che aggiungi alla route dopo l'origine e la destinazione, chiamato waypoint intermedio, l'API aggiunge una tratta separata.

L'API non aggiunge una tratta per un waypoint intermedio pass-through. Ad esempio, una route che contiene un waypoint di origine, un waypoint intermedio pass-through e un waypoint di destinazione contiene solo un tratto dall'origine alla destinazione, mentre lo attraversa. Per ulteriori informazioni sui waypoint del passthrough, consulta Definire un waypoint del passthrough.
Passaggio: una singola istruzione lungo il tratto di un percorso. Il passaggio è l'unità più atomica di una route. Ad esempio, un passaggio può indicare "Svolta a sinistra sulla strada principale''.

Cosa c'è nella 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 route restituita dall'API. L'array può contenere un massimo di cinque elementi: la route predefinita, quella ecosostenibile e fino a tre route alternative.
geocodingResults, un array di elementi di tipo GeocodingResults. Per ogni posizione nella richiesta (origine, destinazione o waypoint intermedio) che hai specificato come stringa indirizzo o Plus code, l'API esegue una ricerca dell'ID luogo. Ogni elemento di questo array contiene l'ID place corrispondente a una località. Le località nella richiesta specificata come ID luogo o 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 una route da tutte le proprietà di input, potrebbe utilizzare un metodo di calcolo diverso. Quando viene utilizzata la modalità di riserva, questo campo contiene informazioni dettagliate sulla risposta di riserva. In caso contrario, il campo non viene configurato.

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)
  }
}

Decifra l'array di route

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

Puoi richiedere route aggiuntive. Se richiedi una percorso ecosostenibile, l'array può contenere due elementi: la route predefinita e quella ecosostenibile. In alternativa, imposta computeAlternativeRoutes su true nella richiesta per aggiungere fino a tre percorsi alternativi alla risposta.

Ogni route nell'array viene identificata con la proprietà dell'array routeLabels:

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

L'array legs contiene la definizione di ogni tratto del percorso. Le restanti proprietà, come distanceMeters, duration e polyline,, contengono informazioni sulla route nel suo insieme:

{
  "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 quello ecosostenibile possono coincidere. In questo caso, l'array routeLabels contiene entrambe le etichette: DEFAULT_ROUTE e FUEL_EFFICIENT.

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

Informazioni sull'array Gambe

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

La proprietà legs contiene la definizione di ogni passaggio lungo il tratto nell'array steps. Le restanti proprietà, come distanceMeters, duration e polyline, contengono informazioni sul tratto.

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

Informazioni sull'array di passaggi

Ogni gamba della risposta contiene un array steps, in cui ogni elemento dell'array steps è di tipo RouteLegStep. Un passo corrisponde a una singola istruzione eseguita lungo la gamba. Una gamba contiene sempre almeno un passaggio.

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

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

Il file 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 restanti proprietà nel passaggio descrivono informazioni sul passaggio, come 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 dei passaggi

L'API restituisce le informazioni sulle route nella lingua locale, traslitte in uno script leggibile dall'utente, se necessario, osservando la lingua preferita. I componenti dell'indirizzo vengono tutti restituiti nella stessa lingua.

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

Informazioni sull'array geocodingResults

Per ogni località nella richiesta (origine, destinazione o waypoint intermedio) specificata come stringa indirizzo o 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 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 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 qualsiasi waypoint intermedio specificato come stringa indirizzo o come Plus Code. Se specifichi un waypoint 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 delle risposte localizzate

I valori di risposta localizzati sono un campo di risposta aggiuntivo che fornisce testo localizzato per i valori dei parametri restituiti. Viene fornito un testo localizzato per la durata del viaggio, la distanza e il sistema di unità (sistema metrico o imperiale). Puoi richiedere valori localizzati utilizzando una maschera per i campi e puoi specificare la lingua e il sistema di unità o utilizzare i valori dedotti dall'API. Per i dettagli, consulta LocalizedValues.

Ad esempio, se specifichi un codice lingua per il tedesco (de) e le unità imperiali, il valore di distanceMeters sarà 49889.7, ma anche il testo localizzato che prevede la misurazione della distanza in unità di misura tedesca e imperiale, ad esempio "31 Meile".

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

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

Nota: ottieni due valori per la durata prevista: duration utilizza il modello di traffico specificato e static_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 deduce la lingua e le unità come segue:

Il metodo ComputeRoutes deduce le unità di posizione e distanza dal waypoint di origine. Pertanto, per una richiesta di routing negli Stati Uniti, l'API deduce la lingua en-US e le unità IMPERIAL.
Il metodo ComputeRouteMatrix utilizza per impostazione predefinita la lingua "en-US" e le unità METRIC.