Questa pagina è stata tradotta dall'API Cloud Translation.

Esamina la risposta del percorso

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

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

Per includerlo nella risposta	Consulta questa documentazione
Il percorso più efficiente dal punto di vista energetico o del carburante in base al tipo di motore del veicolo.	Configurare percorsi ecosostenibili
Fino a tre percorsi alternativi	Richiedere percorsi alternativi
La polilinea per un intero percorso, per ogni tratto di un percorso e per ogni passaggio di una tratta.	Richiedere le polilinee di route
I pedaggi stimati, tenendo conto di eventuali sconti sui prezzi o pass a disposizione del conducente o del veicolo.	Calcolare le tariffe dei pedaggi
Risposte localizzate in base a codici di lingua e unità di misura (imperale o metrica).	Richiedi valori localizzati
Per formattare le istruzioni di navigazione come stringa di testo HTML, aggiungi `HTML_FORMATTED_NAVIGATION_INSTRUCTIONS` a `extraComputations`.	Calcolo extra

Per l'elenco completo delle opzioni di input, consulta Opzioni di route 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 una route, devi specificare una maschera di campo che definisce i campi che devono essere 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 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, tappe e passi

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

Il percorso, la tappa e il passo.

La tua risposta può contenere informazioni su ciascuno di questi componenti di route:

Percorso: l'intero viaggio dalla tappa di partenza, attraverso qualsiasi tappa intermedia, fino alla tappa di destinazione. Un percorso è costituito da una o più tratte.
Parte posteriore: il percorso da una tappa di una rotta a quella successiva. Ogni gamba è costituita da uno o più passi discreti.

Un percorso contiene un tratto separato per il percorso da ogni tappa a quella successiva. Ad esempio, se il percorso contiene una singola tappa di partenza e una singola tappa di destinazione, il percorso contiene un solo tratto. Per ogni tappa aggiuntiva aggiunta al percorso dopo l'origine e la destinazione, chiamata waypoint intermedio, l'API aggiunge un tratto separato.

L'API non aggiunge un tratto per una tappa intermedia pass-through. Ad esempio, un percorso che contiene una tappa di partenza, una tappa intermedia di passaggio e una tappa di destinazione contiene solo un tratto dal luogo di partenza alla destinazione, mentre passa attraverso la tappa. Per ulteriori informazioni sulle tappe passthrough, consulta Definire una tappa passthrough.
Passaggio: una singola istruzione lungo la tratta di un percorso. Un passo è l'unità più atomica di una route. Ad esempio, un passaggio può indicare "Svolta a sinistra su Via principale".

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 route restituita dall'API. L'array può contenere un massimo di cinque elementi: la route predefinita, la route 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) 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 una route da tutte le proprietà di input, potrebbe utilizzare un metodo di calcolo diverso. Quando si utilizza la modalità di riserva, questo campo contiene informazioni dettagliate sulla risposta di riserva. In caso contrario, questo campo non viene 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)
  }
}

Decriptare l'array di route

La risposta contiene l'array routes, dove ogni elemento dell'array è di tipo Route. Ogni elemento dell'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 route ecosostenibile, l'array può contenere due elementi: la route predefinita e la route ecosostenibile. In alternativa, imposta computeAlternativeRoutes su true nella richiesta per aggiungere fino a tre route alternative 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`	Indica un percorso alternativo.

L'array legs contiene la definizione di ogni tratto del percorso. Le altre proprietà, come distanceMeters, duration e polyline,, contengono informazioni sulla route 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 attuali condizioni di guida e di altri fattori, il percorso predefinito e quello ecosostenibile possono essere uguali. In questo caso, l'array routeLabels contiene entrambe le etichette: DEFAULT_ROUTE e FUEL_EFFICIENT.

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

Informazioni sull'array delle gambe

Ogni route nella risposta contiene un array legs, dove ogni elemento dell'array legs è di tipo RouteLeg. Ogni tratto dell'array definisce il percorso da una tappa a quella successiva lungo il percorso. Un percorso contiene sempre almeno un tratto.

La proprietà legs contiene la definizione di ogni passaggio lungo la gamba nell'array steps. Le proprietà rimanenti, 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)
  }
}

Comprendere l'array dei passaggi

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

Ogni elemento nell'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 altre proprietà nel passaggio descrivono le 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, osservando la lingua preferita. I componenti dell'indirizzo vengono tutti restituiti nella stessa lingua.

Utilizza il parametro languageCode di una richiesta per impostare esplicitamente la lingua della route dall'elenco di 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ò 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 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.

Comprendere l'array geocodingResults

Per ogni posizione nella richiesta (origine, destinazione o tappa intermedia) specificata come una 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 posizione 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 eventuali tappe intermedie specificate come stringa di indirizzo o come Plus Code. Se specifichi una tappa intermedia utilizzando un ID luogo o le coordinate di latitudine e longitudine, questa viene omessa dalla risposta. Utilizza la proprietà intermediateWaypointRequestIndex nella risposta per determinare quale tappa intermedia 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
        }
    ]
}

Comprendere i valori delle risposte localizzate

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

Ad esempio, se specifichi un codice lingua per le unità tedesche (de) e imperiali, viene restituito un valore distanceMeters pari a 49889,7, ma viene utilizzato anche testo localizzato che fornisce la misura della distanza in tedesco 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, mentre static_duration non prende in considerazione il traffico. Pertanto, se il modello di traffico richiesto è TRAFFIC_UNAWARE, gli orari 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 dalla tappa di origine. Pertanto, per una richiesta di routing negli Stati Uniti, l'API deduce la lingua en-US e le unità IMPERIAL.
Per impostazione predefinita, il metodo ComputeRouteMatrix è impostato sulla lingua "en-US" e sulle unità METRIC.