L'API Routes è attualmente in anteprima (pre-GA). I prodotti e le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Le Offerte pre-GA sono coperte dai Termini di servizio specifici per Google Maps Platform. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Guida alla migrazione dell'API Routes

Attualmente, la piattaforma di Google Maps supporta l'API Directions e l'API Distance Matrix. Questa versione della nuova API Routes contiene la versione di nuova generazione ottimizzata per le prestazioni dell'API Directions e dell'API Distance Matrix esistenti:

  • Route di calcolo: calcola le indicazioni stradali tra località con dati di routing globali completi e il traffico in tempo reale.
  • Matrice del percorso di calcolo: calcola la distanza e il tempo di percorrenza per un elenco di coppie di origine/destinazione.

L'API Routes include molte nuove funzionalità, tra cui:

  • Routing TWO_WHEELER
  • Calcolo del pedaggio
  • Polilinea sensibile al traffico
  • Controlli per la qualità di Polyline
  • Controlli di latenza della qualità
  • Flusso di risultati (matrice di route Compute solo con gRPC)
  • Supporto gRPC

Per scoprire di più sull'API Routes, consulta API Routes.

Questa guida descrive come eseguire la migrazione delle app esistenti che utilizzano l'API Directions e l'API Distance Matrix per utilizzare la nuova API Routes.

Modifiche alla funzionalità nella nuova API Routes

A livello generale, l'API Routes apporta le seguenti modifiche all'API Directions e all'API Distance Matrix:

  • Consolidamento di Compute Routes e Compute Route Matrix in un unico servizio chiamato Routes API

    Per poter utilizzare le route di Compute e la matrice di route di Compute, devi abilitare l'API Routes nella console API. Al momento attivi l'API Directions e l'API Distance Matrix come servizi separati nella console API.

    Per saperne di più, consulta Configurare la console delle API di Google.

  • La nuova API Routes utilizza le richieste POST HTTP

    Nella nuova API Routes, trasmetti i parametri nel corpo della richiesta o nelle intestazioni come parte di una richiesta POST HTTP. Al contrario, con l'API Directions e l'API Distance Matrix, trasmetti i parametri URL utilizzando una richiesta HTTP GET.

    Per vedere alcuni esempi, vedi:

  • Il mascheramento dei campi è obbligatorio

    Quando chiami la nuova API Routes per calcolare una route o una matrice di route, devi specificare i campi da restituire nella risposta. Non esiste un elenco predefinito di campi restituiti. Se ometti questo elenco, i metodi restituiscono un errore.

    Specifica l'elenco dei campi creando una maschera del campo di risposta. Passi la maschera del campo di risposta a ciascun metodo utilizzando il parametro URL $fields o fields oppure l'intestazione HTTP/gRPC X-Goog-FieldMask.

    Il mascheramento dei campi è una buona pratica di progettazione per assicurarsi di non richiedere dati non necessari, il che consente di evitare tempi di elaborazione e addebiti non necessari.

    Per maggiori informazioni, consulta Scegliere i campi da restituire.

  • Nuovi limiti di richieste per Compute Route Matrix

    L'API Distance Matrix ha applicato i seguenti limiti alle richieste:

    • Massimo 25 origini o 25 destinazioni per richiesta.
    • Massimo 100 elementi (numero di origini × numero di destinazioni) per richiesta lato server.

    La matrice di route Compute applica i seguenti limiti di richiesta:

    • Il numero di elementi non può superare 625.

    • Se specifichi TRAFFIC_AWARE_OPTIMAL, il numero di elementi non può superare 100. Per scoprire di più su TRAFFIC_AWARE_OPTIMAL, consulta Confronto tra qualità e latenza.

    • Il numero massimo di tappe (origini + destinazioni) che puoi specificare utilizzando un ID luogo è 50.

  • Nuove opzioni per configurare la qualità e la latenza

    La nuova API Routes supporta tre preferenze di routing che puoi utilizzare per configurare in modo esplicito la qualità delle route e la latenza di risposta:

    • TRAFFIC_UNAWARE (valore predefinito): utilizza i dati medi sul traffico indipendente dal tempo, non i dati sul traffico in tempo reale, per calcolare il percorso, con conseguente latenza più bassa della risposta. Questa impostazione equivale a quando il traffico non viene utilizzato nell'API Directions e nell'API Distance Matrix.

    • TRAFFIC_AWARE: qualità del traffico in tempo reale ottimizzata per le prestazioni, per una latenza ridotta. Questa impostazione è nuova per l'API Routes e non ha equivalenti nell'API Directions e nell'API Distance Matrix.

      A differenza di TRAFFIC_AWARE_OPTIMAL, alcune ottimizzazioni vengono applicate per ridurre significativamente la latenza.

    • TRAFFIC_AWARE_OPTIMAL: dati sul traffico completi e di alta qualità, senza applicare la maggior parte delle ottimizzazioni del rendimento. Questa impostazione produce la latenza massima e equivale all'impostazione departure_time nell'API Directions e nell'API Distance Matrix.

      La preferenza di routing per TRAFFIC_AWARE_OPTIMAL equivale alla modalità utilizzata da maps.google.com e dall'app per dispositivi mobili Google Maps.

    Nell'API Directions e nell'API Distance Matrix forniamo solo le opzioni TRAFFIC_AWARE_OPTIMAL e TRAFFIC_UNAWARE. Queste opzioni sono state impostate implicitamente a seconda che tu abbia impostato departure_time o meno.

    La tabella seguente mette a confronto le opzioni attuali per l'API Directions e l'API Distance Matrix e le nuove opzioni dell'API Routes:

    Modalità Attuale API Routes Note
    Nessun traffico in tempo reale departure_time proprietà non impostata TRAFFIC_UNAWARE Massima latenza delle tre modalità.
    Condizioni per il traffico in tempo reale applicate Nessun equivalente TRAFFIC_AWARE

    Nuova modalità aggiunta dall'API Routes. Offre una latenza leggermente superiore rispetto a TRAFFIC_UNAWARE con un piccolo costo della qualità ATE.

    Ha una latenza molto più bassa rispetto a TRAFFIC_AWARE_OPTIMAL.

    Dati per il traffico in tempo reale di alta qualità applicati departure_time proprietà impostata TRAFFIC_AWARE_OPTIMAL

    Equivalente alla modalità utilizzata da maps.google.com e dall'app per dispositivi mobili Google Maps.

    Per Compute Route Matrix, il numero di elementi in una richiesta (numero di origini × numero di destinazioni) non può superare 100.

    L'API Routes modifica anche il modo in cui è impostata la proprietà di risposta duration e modifica le proprietà restituite nella risposta current, come mostrato nella seguente tabella:

    Tipo di viaggio ATE Attuale API Routes
    Traffico incerto e indipendente dal tempo.

    Corrisponde a departure_time non impostato nella richiesta.

    • Arrivo di ATE nella proprietà della risposta duration.
    • La proprietà della risposta duration_in_traffic non viene restituita.

    Corrisponde a TRAFFIC_UNAWARE.

    • Arrivo di ATE nella proprietà della risposta duration.
    • Le proprietà della risposta duration e staticDuration contengono lo stesso valore.
    Orario di arrivo stimato che prende in considerazione il traffico in tempo reale.

    Corrisponde all'impostazione di departure_time nella richiesta.

    • L'orario di arrivo stimato che prende in considerazione il traffico in tempo reale è incluso nella proprietà delle risposte duration_in_traffic.

    Corrisponde a TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL.

    • L'orario di arrivo stimato che prende in considerazione il traffico in tempo reale è incluso nella proprietà delle risposte duration.
    • La proprietà staticDuration di risposta contiene la durata del viaggio attraverso la route senza prendere in considerazione le condizioni del traffico.
    • La proprietà duration_in_traffic non viene più restituita.

    Per ulteriori informazioni, consulta Confronto tra qualità e latenza.

Funzionalità esistenti non supportate nell'API Routes

Le seguenti funzionalità non saranno supportate nell'API Routes:

  • XML come formato di risposta. Sono supportati solo JSON e gRPC.

  • Geocodifica inversa (rilevamento dell'indirizzo a partire dalle coordinate geografiche)

    Per questa funzionalità, ora utilizzi l'API Reverse Geocoding, creata per questo caso d'uso e che fornisce risultati di qualità superiore.

Esegui la migrazione all'API Routes

Abbiamo apportato diverse modifiche all'API Routes. La maggior parte delle modifiche è compatibile con le API attuali, ma di seguito sono elencate alcune modifiche che richiedono attenzione quando esegui la migrazione delle app all'API Routes.

Aggiorna gli endpoint API REST

Se utilizzi l'API Directions, aggiorna il codice in modo da utilizzare il nuovo endpoint dell'API Routes:

API Directions https://maps.googleapis.com/maps/api/directions/outputFormat?parameters
API Routes https://routes.googleapis.com/directions/v2:computeRoutes

Se utilizzi l'API Distance Matrix, aggiorna il codice per utilizzare il nuovo endpoint dell'API Routes:

API Distance Matrix https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters
API Routes https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

Converti i parametri URL per utilizzare un corpo della richiesta HTTP

Con l'API Directions e l'API Distance Matrix, passi le proprietà di configurazione come parametri URL a una richiesta HTTP GET. Ad esempio, per l'API Directions:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

Con l'API Routes, puoi trasmettere i parametri in un corpo di richiesta o nelle intestazioni come parte di una richiesta POST HTTP. Per vedere alcuni esempi, vedi:

Convertire i parametri correnti in parametri dell'API Routes

La seguente tabella elenca i parametri nell'API Directions e nell'API Distance Matrix che sono stati rinominati o modificati oppure parametri che non sono supportati nella release di anteprima. Aggiorna il codice se utilizzi uno di questi parametri.

Parametro attuale Parametro API Routes Note
destination destination Indirizzi e Plus Code non sono disponibili nella release di anteprima.
origin origin Indirizzi e Plus Code non sono disponibili nella release di anteprima.
alternatives computeAlternativeRoutes
arrival_time Non disponibile perché la modalità TRANSIT non è disponibile in anteprima.
avoid routeModifiers
copyrights Non disponibile nella release di anteprima.
departure_time departureTime
distance distanceMeters La distanza è disponibile solo in metri.
duration_in_traffic Rimosso nell'API Routes, usa duration. Per saperne di più, consulta la sezione Modifiche alle funzionalità per la nuova API Routes sopra.
language languageCode
mode travelMode

Aggiunto il supporto per TWO_WHEELER.

Modalità TRANSIT non disponibile in anteprima.

region Non disponibile nella versione di anteprima perché gli indirizzi non sono supportati.
status Non disponibile nella release di anteprima. Utilizza i codici di risposta HTTP per gli errori segnalati dall'API. Per ulteriori informazioni, consulta la sezione Gestire gli errori di richiesta.
traffic_model Non disponibile nella release di anteprima.
transit_mode Non disponibile perché la modalità TRANSIT non è disponibile in anteprima.
transit_routing_preference Non disponibile perché la modalità TRANSIT non è disponibile in anteprima.
units Non disponibile per Distance Matrix nella release Anteprima.
waypoints intermediates Indirizzi e polilinee non sono disponibili nella versione di anteprima.
optimize=true per i tappe Non disponibile nella release di anteprima.