Esamina la risposta del percorso

Sviluppatori dello Spazio economico europeo (SEE)

Quando l'API Routes calcola una route, prende come input i waypoint e i parametri di configurazione che fornisci. L'API restituisce quindi una risposta che contiene 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 includere questo nella risposta Consulta questa documentazione
La route più efficiente dal punto di vista del consumo di carburante o a risparmio energetico in base al tipo di motore del veicolo. Configura le route ecosostenibili
Fino a tre route alternative Richiedi route alternative
La polilinea per un'intera route, per ogni tratta di una route e per ogni passaggio di una tratta. Richiedi le polilinee delle route
I pedaggi stimati, tenendo conto di eventuali sconti o pass sui prezzi dei pedaggi disponibili per il conducente o il veicolo. Calcola le tariffe dei 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 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 clienti le informazioni necessarie per selezionare la route appropriata in base alle loro esigenze.

Informazioni sulle maschere di campo

Quando chiami un metodo per calcolare una route, 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 che hai specificato esplicitamente nella maschera di campo.

Per ulteriori informazioni, consulta Scegli quali informazioni restituire.

Informazioni sulla visualizzazione dei copyright

Quando mostri i risultati agli utenti, devi includere la seguente dichiarazione di copyright:

Powered by Google, ©YEAR Google

Ad esempio:

Powered by Google, ©2023 Google

Informazioni su route, tratte e passaggi

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

Il percorso, la tappa e il passo.

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

  • Route: l'intero viaggio dal waypoint di origine, passando per eventuali waypoint intermedi, fino al waypoint di destinazione. Una route è costituita da una o più tratte.

  • Tratta: il percorso da un waypoint a quello successivo nella route. Ogni tratta è costituita da uno o più passaggi discreti.

    Una route contiene una tratta separata per il percorso da ogni waypoint a quello successivo. Ad esempio, se la route contiene un singolo waypoint di origine e un singolo waypoint di destinazione, la route contiene una singola tratta. 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 di passaggio. Ad esempio, una route che contiene un waypoint di origine, un waypoint intermedio di passaggio e un waypoint di destinazione contiene una sola tratta dall'origine alla destinazione, passando per il waypoint. Per ulteriori informazioni sui waypoint di passaggio, consulta Definire un waypoint di passaggio.

  • Passaggio: una singola istruzione lungo la tratta di una route. Un passaggio è l'unità più atomica di una route. 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 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 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 una route da tutte le proprietà di input, potrebbe ricorrere a un modo 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 delle route

La risposta contiene l'array routes, in cui ogni elemento dell'array è di tipo Route. Ogni elemento dell'array rappresenta un'intera route dall'origine alla destinazione. L'API restituisce sempre almeno una route, chiamata 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 è identificata con la proprietà dell'array routeLabels:

Valore Descrizione
DEFAULT_ROUTE Identifica la route predefinita.
FUEL_EFFICIENT Identifica la route ecosostenibile.
DEFAULT_ROUTE_ALTERNATE Indica una route alternativa.

L'array legs contiene la definizione di ogni tratta della route. Le proprietà rimanenti, 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 condizioni di guida attuali e di altri fattori, la route predefinita e la route ecosostenibile possono essere le stesse. 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 tratte

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

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 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 dei 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 tratta. Una tratta 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"
}

Le instructions potrebbero 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, come distanceMeters, duration e polyline:

{
  "distanceMeters": integer,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "navigationInstruction": {
    object (NavigationInstruction)
  }
}

Specificare la lingua delle istruzioni dei passaggi

L'API restituisce le informazioni sulla route nella lingua locale, traslitterate 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 della route 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ò 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 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 strada 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' geocodingResults array contiene il campo placeID che contiene 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 a quale waypoint intermedio nella richiesta corrisponde l'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 la durata del viaggio, la distanza e il 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, ottieni un valore per distanceMeters di 49889,7, ma anche un testo localizzato che fornisce la misurazione della distanza in tedesco e in unità imperiali, quindi "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à come segue:

  • Il metodo ComputeRoutes deduce le unità di località 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.