Compute routes

Lo strumento compute_routes restituisce un percorso tra un'origine e una destinazione per una determinata modalità di viaggio. La risposta include la distanza e la durata del percorso. Per impostazione predefinita, i percorsi vengono calcolati senza traffico in tempo reale. Pro aggiunge il calcolo del percorso che tiene conto del traffico in tempo reale e dei percorsi con più fermate intermedie.

Questa pagina descrive le opzioni di richiesta, incluse le opzioni Pro, i contenuti della risposta e la fatturazione delle richieste. Per lo schema completo dello strumento, consulta il riferimento compute_routes.

Opzioni di richiesta

Opzione Descrizione
origin, destination Obbligatorio. Ognuno è un waypoint: un address (un indirizzo leggibile o un Plus Code), un place_id o un lat_lng. Puoi combinare i formati, ad esempio un indirizzo per l'origine e un ID luogo per la destinazione.
travel_mode La modalità di trasporto: DRIVE (predefinita), WALK, BICYCLE o TRANSIT. I percorsi WALK sono in versione beta e a volte potrebbero non includere marciapiedi o percorsi pedonali ben definiti. Devi mostrare questo avviso all'utente per tutti i percorsi a piedi che mostri nella tua app.
routing_preference Come vengono utilizzati i dati sul traffico per calcolare il percorso: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (predefinito) o ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, che è un'opzione Pro. ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL non è supportato per WALK o BICYCLE. Consulta Routing basato sul traffico.
intermediate_waypoints Tappe ordinate tra l'origine e la destinazione. Il percorso li attraversa nell'ordine indicato. Una richiesta può includere fino a 10 tappe intermedie o da 11 a 25 come opzione Pro. Una richiesta con più di 25 waypoint restituisce un errore INVALID_ARGUMENT. I percorsi con il trasporto pubblico non supportano i waypoint intermedi.
departure_time o arrival_time Quando partire dall'origine o arrivare alla destinazione, come timestamp RFC 3339. Impostane al massimo uno. Per impostazione predefinita, la partenza è impostata sull'ora corrente. Per TRANSIT, il tempo può essere fino a 7 giorni nel passato o 100 giorni nel futuro. Per le altre modalità di viaggio, l'orario non può essere nel passato e può essere impostato fino a 365 giorni nel futuro.
compute_alternative_routes Quando true, la risposta include percorsi alternativi oltre a quello consigliato, se disponibili. Il valore predefinito è false.
include_polyline Quando true, ogni percorso nella risposta include encodedPolyline. Il valore predefinito è false.
location_bias Una latitudine e una longitudine che influenzano il modo in cui vengono risolti i waypoint di testo, ad esempio per eliminare l'ambiguità di un indirizzo.

Opzioni Pro

Due opzioni selezionano lo SKU Pro. Una richiesta che utilizza uno o entrambi i parametri viene fatturata con lo SKU Pro:

Opzione Pro Quando utilizzarla
routing_preference impostato su ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL L'utente chiede informazioni sul traffico, sulla congestione o su un tempo di percorrenza che tiene conto del traffico attuale. Consulta Routing basato sul traffico.
11-25 intermediate_waypoints Il percorso richiede più di 10 tappe tra l'origine e la destinazione.

Tutte le altre opzioni vengono fatturate in base allo SKU Essentials, tra cui la modalità di viaggio, i tempi, i percorsi alternativi, le polilinee e l'orientamento della località.

Routing basato sul traffico

Per impostazione predefinita, i percorsi vengono calcolati senza condizioni del traffico in tempo reale (ROUTING_PREFERENCE_TRAFFIC_UNAWARE). Questa impostazione ha la latenza più bassa. È adatto per le richieste in cui il traffico non è importante o non è applicabile, ad esempio per i percorsi a piedi o per una pianificazione approssimativa.

Imposta routing_preference su ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL per calcolare il percorso e la sua durata in base alle condizioni del traffico attuali, se i dati sul traffico sono disponibili. Utilizzala quando l'utente chiede quanto tempo ci vuole per un viaggio in auto in questo momento. Per i percorsi con TRANSIT, questa impostazione utilizza i dati sul trasporto pubblico in tempo reale, come ritardi e cancellazioni, se disponibili. Non è supportato per le route WALK o BICYCLE. Queste richieste restituiscono un errore INVALID_ARGUMENT. Questa è un'opzione Pro, quindi la richiesta viene fatturata con lo SKU Pro. Questa opzione aggiunge anche latenza.

Durante la fase di disponibilità generale limitata, se il tuo progetto non è incluso nella lista consentita di Pro, questa opzione viene trattata come ROUTING_PREFERENCE_TRAFFIC_UNAWARE. Per maggiori dettagli, consulta Opzioni Pro durante la disponibilità generale limitata.

Esempio

La seguente richiesta richiede un percorso di guida che tiene conto del traffico con una fermata intermedia e una polilinea codificata. Viene fatturato con lo SKU Pro:

{
  "method": "tools/call",
  "params": {
    "name": "compute_routes",
    "arguments": {
      "origin": {"address": "Ferry Building, San Francisco, CA"},
      "destination": {"address": "Golden Gate Park, San Francisco, CA"},
      "intermediate_waypoints": [
        {"address": "Palace of Fine Arts, San Francisco, CA"}
      ],
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_polyline": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

Risposta

La risposta contiene routes[], in ordine decrescente di priorità. Viene restituito un solo percorso, a meno che compute_alternative_routes non sia true. Ogni percorso include:

  • distanceMeters: la distanza di percorrenza del percorso, in metri.
  • duration: il tempo necessario per percorrere il percorso. Con ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, la durata tiene conto delle condizioni del traffico.
  • encodedPolyline: il percorso della route come polyline codificata, quando include_polyline è true. Puoi utilizzarla per disegnare il percorso su una mappa con altre API di Google Maps Platform.
  • attribution: l'attribuzione che devi mostrare con il percorso. Consulta i requisiti di attribuzione.

Opzioni Pro durante la disponibilità generale limitata

Durante la fase di disponibilità generale limitata, le opzioni Pro sono disponibili solo per i progetti inclusi nella lista consentita Pro. Se il tuo progetto non è ancora nella lista consentita:

  • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL viene trattato come ROUTING_PREFERENCE_TRAFFIC_UNAWARE e la richiesta viene fatturata in base allo SKU Essentials.
  • Una richiesta con più di 10 waypoint intermedi restituisce un errore INVALID_ARGUMENT ("Sono supportati al massimo 10 waypoint intermedi").

Per richiedere l'accesso, consulta Opzioni Pro durante la disponibilità generale limitata.

Fatturazione e quote

Ogni richiesta compute_routes è un evento fatturabile:

  • Una richiesta che non utilizza opzioni Pro viene fatturata in base allo SKU Essentials.
  • Una richiesta che utilizza un'opzione Pro viene fatturata in base allo SKU Pro. L'utilizzo di entrambe le opzioni Pro in un'unica richiesta non modifica l'addebito. Per i prezzi di Pro, consulta Confronta Essentials, Pro e Grounding con Google Maps.

La richiesta di percorsi alternativi, di una polilinea, di un'ora di partenza o di arrivo o di una modalità di viaggio diversa non modifica lo SKU.

La quota di compute_routes è di 300 query al minuto per progetto, condivisa da entrambi gli SKU. Per i prezzi, consulta la tabella dei prezzi principale e la tabella dei prezzi per l'India.

Limiti

  • Una richiesta può includere al massimo 25 waypoint intermedi; da 11 a 25 è un'opzione Pro. Una richiesta con un numero maggiore di elementi restituisce un errore INVALID_ARGUMENT.
  • I percorsi con il trasporto pubblico non supportano i waypoint intermedi. Una richiesta di trasporto pubblico con tappe intermedie restituisce un errore INVALID_ARGUMENT.
  • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL non è supportata per i percorsi a piedi o in bicicletta.
  • Per i percorsi con il trasporto pubblico, gli orari di partenza e di arrivo possono essere fino a 7 giorni nel passato o 100 giorni nel futuro. Per le altre modalità di viaggio, non possono essere nel passato e possono essere fino a 365 giorni nel futuro.
  • Le coordinate dei waypoint devono rientrare in limiti geografici validi (latitudine da -90 a 90, longitudine da -180 a 180).
  • Lo strumento non restituisce passaggi passo passo, tappe o dettagli delle linee di trasporto pubblico.