Esamina la risposta del percorso

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

La risposta può includere diversi tipi di itinerari e altri dati, in base ai campi che richiedi:

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 l'itinerario appropriato per le loro esigenze.

Informazioni sulle maschere di campo

Quando chiami un metodo per calcolare un itinerario, devi specificare una maschera di campo che definisca i campi che vuoi 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 includerebbe solo i campi specificati esplicitamente nella maschera del campo.

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

Powered by Google, ©2023 Google

Informazioni su itinerari, tappe e passi

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

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

• Percorso: l'intero viaggio dal punto di partenza, passando per eventuali punti intermedi, fino al punto di arrivo. Un itinerario è composto da una o più tappe.

• Tratta: il percorso da un waypoint di un itinerario al successivo. Ogni tratta è costituita da uno o più passaggi discreti.

  Un itinerario contiene un tratto separato per il percorso da ogni waypoint al successivo. Ad esempio, se l'itinerario contiene un singolo waypoint di partenza e un singolo waypoint di destinazione, allora l'itinerario contiene un singolo segmento. 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 segmento 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 transito e un waypoint di destinazione contiene un solo segmento dal punto di partenza alla destinazione, passando per il waypoint. Per ulteriori informazioni sui waypoint di transito, vedi Definire un waypoint di transito.

• Passaggio: una singola istruzione lungo la tratta 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: l'itinerario predefinito, l'itinerario ecologico e fino a tre itinerari 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 ricorrere a 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 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 una route, chiamata route predefinita.

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 itinerari alternativi alla risposta.

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

L'array legs contiene la definizione di ogni tratto del percorso. Le proprietà rimanenti, come distanceMeters, duration e polyline,, contengono informazioni sull'itinerario 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 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 di segmenti

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

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

{
  "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 tratta nella risposta contiene un array steps, in cui ogni elemento dell'array steps è di tipo RouteLegStep. Un passaggio corrisponde a una singola istruzione lungo la gamba. Una tratta contiene sempre almeno un passaggio.

Ogni elemento dell'array steps include la proprietà navigationInstruction, di tipo NavigationInstruction, che contiene le istruzioni 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 un alfabeto leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti i componenti dell'indirizzo vengono restituiti 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, 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ò influire sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocoder 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 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 con 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 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 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 viene fornito per durata, distanza e sistema di unità di misura (metrico o imperiale) del viaggio. Richiedi valori localizzati utilizzando una maschera di campo e puoi specificare la lingua e il sistema di unità di misura oppure utilizzare i valori dedotti dall'API. Per maggiori dettagli, vedi 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 in 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 deduce la lingua e le unità nel seguente modo:

• 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à METRICHE.