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ù tappe intermedie.

Puoi chiamare compute_routes tramite il server MCP o come metodo REST computeRoutes. Questa pagina descrive le opzioni di richiesta, incluse le opzioni Pro, i contenuti della risposta e la fatturazione delle richieste. Per gli schemi completi, consulta il riferimento MCP compute_routes e il riferimento REST computeRoutes.

Opzioni di richiesta

La tabella seguente descrive le opzioni di richiesta per compute_routes:

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 avere marciapiedi o percorsi pedonali chiari. 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 la sezione 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, l'ora può essere impostata 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 Coordinate di latitudine/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 Maps Grounding Pro. Una richiesta che utilizza uno o entrambi gli elementi 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 la sezione 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 con lo SKU Essentials, tra cui la modalità di viaggio, i tempi, i percorsi alternativi, le polilinee e la preferenza per la 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. Utilizzalo 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 i percorsi 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.

Esempio

La seguente richiesta MCP richiede un percorso di guida che tenga 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
}

L'esempio seguente invia la stessa richiesta al metodo REST computeRoutes:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "origin": {"address": "Ferry Building, San Francisco, CA"},
  "destination": {"address": "Golden Gate Park, San Francisco, CA"},
  "intermediateWaypoints": [
    {"address": "Palace of Fine Arts, San Francisco, CA"}
  ],
  "travelMode": "DRIVE",
  "routingPreference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
  "includePolyline": true
}' \
"https://mapstools.googleapis.com/v1:computeRoutes"

Sostituisci API_KEY con la tua chiave API.

Risposta

La risposta contiene routes[], in ordine decrescente di raccomandazione. 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.
  • retrievalToken: un token opaco restituito per i percorsi DRIVE (valido per 10 minuti) che puoi passare a search_along_route per trovare luoghi lungo quel percorso senza inviare nuovamente i waypoint.
  • attribution: l'attribuzione che devi mostrare con il percorso. Consulta i requisiti di attribuzione.

Fatturazione e quote

Ogni richiesta compute_routes è un evento fatturabile:

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 ogni 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 waypoint intermedi restituisce un errore INVALID_ARGUMENT.
  • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL non è supportato 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.