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 predefinita e una o più route alternative.

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

Per includerlo nella risposta	Visualizza questa documentazione
Il percorso a più basso consumo di carburante o energia in base al tipo di motore del veicolo.	Configura route ecosostenibili
Fino a tre percorsi alternativi	Richiedere percorsi alternativi
La polilinea di un intero percorso, per ogni tratto di un percorso e per ogni passo di una tratta.	Richiedi polilinee dei percorsi
I pedaggi stimati, tenendo conto di eventuali sconti o pass disponibili per il conducente o il veicolo.	Calcolare i 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.	Calcolo extra

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

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

Nota: per avere un'idea più chiara di come l'API gestisce i diversi tipi di richieste di route, prova la demo. La demo ti consente di inserire gli indirizzi e di visualizzare la risposta sotto forma di contenuto visualizzato.

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 includerebbe solo i campi specificati esplicitamente nella maschera dei campi.

Per ulteriori informazioni, vedi Scegliere le informazioni da restituire.

Informazioni sulla visualizzazione di copyright

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

Powered by Google, ©YEAR Google

Ad esempio:

Powered by Google, ©2023 Google

Informazioni su percorsi, tappe e passi

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

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

• Route: l'intero viaggio dal tappa di origine, attraverso eventuali tappe intermedie, al punto di destinazione. Un percorso è costituito da una o più tratte.

• Tasta: il percorso da un tappa in un percorso al tappe successivo. Ogni tratto è costituito da uno o più passaggi distinti.

  Un percorso contiene una tratta separata per il percorso da ogni tappa a quella successiva. Ad esempio, se contiene un solo tappa di origine e un solo punto di destinazione, contiene un'unica tratta. Per ogni tappa aggiuntiva aggiunta alla route dopo l'origine e la destinazione, chiamata routepoint 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 tappa di origine, un punto di passaggio intermedio e un punto di arrivo di destinazione, contiene solo una tratta dall'origine alla destinazione e viceversa. Per ulteriori informazioni sui punti di percorso che prevedono il passaggio, consulta Definire un percorso di passaggio.

• Passaggio: una singola istruzione lungo il tratto di un percorso. Un passaggio è l'unità più atomica di una route. Ad esempio, un passaggio può indicare "Svolta a sinistra sulla via 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 owaypoint intermedio) che hai specificato come stringa indirizzo o Plus Code, l'API esegue una ricerca ID luogo. Ogni elemento di questo array contiene l'ID luogo corrispondente a una località. Le località nella richiesta specificate come ID luogo o coordinate di latitudine/longitudine non vengono 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 per utilizzare un metodo di riserva. 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 dell'array è di tipo Route. Ogni elemento array rappresenta un'intera route dall'origine alla destinazione. L'API restituisce sempre almeno una route, denominata route predefinita.

Puoi richiedere percorsi aggiuntivi. Se richiedi una route 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 è 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 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 il percorso ecosostenibile possono coincidere. In questo caso, l'array routeLabels contiene entrambe le etichette: DEFAULT_ROUTE e FUEL_EFFICIENT.

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

Comprendere l'array di gambe

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

La proprietà legs contiene la definizione di ogni passaggio lungo il tratto 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)
  }
}

Informazioni sull'array di passaggi

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 gamba. Una gamba contiene sempre almeno un passaggio.

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

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

Il 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 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 dei passaggi

L'API restituisce le informazioni sulle route 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.

• Usa il parametro languageCode di una richiesta per impostare esplicitamente la lingua della route dall'elenco delle lingue supportate. Spesso Google aggiorna le lingue supportate, pertanto l'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 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.

Informazioni sull'array geocodingResults

Per ogni località nella richiesta (origine, destinazione o waypoint intermedio) specificata come stringa di indirizzo o Plus Code, l'API cerca 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.

Nota: l'API non include le località nella richiesta specificata come ID luogo o coordinate di latitudine e longitudine. Se sono tutti in questi formati, l'array non viene fornito.

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 di indirizzo o come Plus Code. Se specifichi un tappa intermedia 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 tappa intermedia della richiesta corrisponde all'ID luogo nella risposta.

Nota: se una località richiesta non esiste o non è possibile trovarla, l'API compila comunque l'array geocodingResults nella risposta. Tuttavia, l'array routes è vuoto perché non è possibile calcolare alcuna route per una località che non può essere trovata.

"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 localizzati della risposta sono un campo di risposta aggiuntivo che fornisce testo localizzato per i valori dei parametri restituiti. Viene fornito un testo localizzato per durata del viaggio, distanza e sistema di unità (sistema metrico o imperiale). Puoi richiedere 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 i dettagli, consulta LocalizedValues.

Ad esempio, se specifichi un codice lingua per il tedesco (de) e le unità imperiali, il valore distanceMeters è 49889,7, ma anche il testo localizzato che prevede la misurazione della distanza in tedesco e nelle unità imperiali, 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 prende in considerazione il traffico. Pertanto, se il modello di traffico richiesto è TRAFFIC_UNAWARE, questi 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 dal tappa di origine. Di conseguenza, 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 utilizza la lingua "en-US" e le unità METRIC.