Esamina la risposta del percorso

Sviluppatori dello Spazio economico europeo (SEE)

Quando l'API Routes calcola un percorso, prende come input i waypoint e i parametri di configurazione 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 questo elemento nella risposta Consulta questa documentazione
Il percorso più efficiente dal punto di vista del consumo di carburante o a risparmio energetico in base al tipo di motore del veicolo. Configura i percorsi ecosostenibili
Fino a tre percorsi alternativi Richiedi itinerari alternativi
La polilinea per un intero percorso, 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 sui prezzi dei pedaggi o pass disponibili per il conducente o il veicolo. Calcola i pedaggi
Risposte localizzate in base ai codici lingua e all'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 aggiuntivi

Per l'elenco completo delle opzioni di input, consulta Opzioni di percorso disponibili e 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 di campo

Quando chiami un metodo per calcolare un percorso, devi specificare una maschera di campo che definisce 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 della risposta senza tenere conto delle maschere di campo. In un ambiente di produzione, la risposta includerebbe solo i campi specificati esplicitamente nella maschera di campo.

Per saperne di più, consulta Scegli 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:

Powered by Google, ©2023 Google

Informazioni su percorsi, tappe e passaggi

Prima di esaminare la risposta restituita dall'API Routes, devi comprendere i componenti che costituiscono un percorso:

Il percorso, la tratta e il passaggio.

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

  • Percorso: l'intero viaggio dal waypoint di partenza, attraverso eventuali waypoint intermedi, fino al waypoint di destinazione. Un percorso è composto da una o più tappe.

  • Tratto: il percorso da un waypoint di un itinerario al waypoint successivo. Ogni tratto è composto da uno o più passaggi discreti.

    Un percorso contiene una tappa separata per il tragitto da ogni waypoint al successivo. Ad esempio, se il percorso contiene un singolo waypoint di origine e un singolo waypoint di destinazione, il percorso contiene una singola tappa. Per ogni punto di passaggio aggiuntivo che aggiungi al percorso dopo l'origine e la destinazione, chiamato punto di passaggio intermedio, l'API aggiunge un tratto separato.

    L'API non aggiunge una tappa per un waypoint intermedio pass-through. Ad esempio, un percorso che contiene un waypoint di partenza, un waypoint intermedio di passaggio e un waypoint di destinazione contiene una sola tappa dalla partenza alla destinazione, passando per il waypoint. Per saperne di più sui waypoint di transito, consulta Definisci un waypoint di transito.

  • Passaggio: una singola istruzione lungo la tappa di un percorso. Un passaggio è l'unità più atomica di un percorso. Ad esempio, un passaggio può indicare "Svolta a sinistra in via Roma".

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 waypoint intermedio) che hai specificato 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 utilizzare un metodo di calcolo diverso. Quando viene utilizzata la modalità di fallback, questo campo contiene informazioni dettagliate sulla risposta di fallback. 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 routes

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 una route, chiamata route predefinita.

Puoi richiedere route aggiuntive. 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à 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 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 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 legs

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

La proprietà legs contiene la definizione di ogni passaggio lungo la tappa 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 della risposta contiene un array steps, in cui ogni elemento dell'array steps è di tipo RouteLegStep. Un passaggio corrisponde a una singola istruzione lungo la tappa. Una tappa 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 le 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 del passaggio

L'API restituisce le informazioni sul percorso nella lingua locale, traslitterata 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ù vicina.

  • 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 potrebbero 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 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 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 di risposta localizzati

I valori di risposta localizzati sono un campo di risposta aggiuntivo che fornisce il testo localizzato per i valori parametro restituiti. Viene fornito un testo localizzato per la durata, la distanza e il sistema di unità di misura (metrico o imperiale) della corsa. Puoi richiedere valori localizzati utilizzando una maschera di campo e puoi specificare la lingua e il sistema di unità di misura 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, ovvero "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}.
  }
}

Se non specifichi la lingua o il sistema di unità, l'API li deduce come segue:

  • Il metodo ComputeRoutes deduce la località e le unità di distanza dal waypoint di origine. Quindi, 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à METRICHE.