Riferimento rapido per l'API Distance Matrix

L'API Distance Matrix (Legacy) è un servizio web che restituisce la distanza e il tempo di percorrenza per una matrice di origini e destinazioni, in base al percorso consigliato tra ogni coppia. Puoi impostare la modalità di viaggio (auto, a piedi, bicicletta, mezzi pubblici), le modalità Mezzi pubblici, le unità e l'ora di partenza per le durate basate sul traffico. Restituisce JSON o XML.

API Distance Matrix: informazioni chiave

  • Prodotto: API Distance Matrix
  • Nota anche come: API Distance Matrix (legacy), Distance Matrix (legacy)
  • Categoria: Percorsi
  • Piattaforma: servizio web (REST)
  • Esecuzione su: server (codice di backend)
  • Fase di lancio: GA
  • Ciclo di vita: legacy
  • Sostituita da: API Routes
  • Panoramica: Panoramica dell'API Distance Matrix

API Distance Matrix: quando utilizzarla

Utilizza l'API Distance Matrix quando:

  • Gestisci un progetto esistente in cui l'API Distance Matrix (Legacy) è già abilitata e chiama /maps/api/distancematrix.
  • Devi calcolare la distanza e il tempo di percorrenza tra più origini e più destinazioni da un server.
  • Hai bisogno delle durate nel traffico per la guida, utilizzando departure_time e un traffic_model facoltativo.

Non utilizzare l'API Distance Matrix quando:

  • Stai avviando un nuovo progetto Google Cloud. A partire da ottobre 2026, l'API Distance Matrix (legacy) non potrà essere abilitata per i nuovi progetti. Utilizza invece l'API Routes.
  • Hai bisogno di nuove funzionalità o di una matrice dei percorsi di massimo 625 elementi con risposte in streaming (computeRouteMatrix). Utilizza invece l'API Routes.
  • Hai bisogno di un percorso completo con passaggi e polilinee tra i punti, non solo di valori di distanza e durata. Utilizza invece l'API Routes.

API Distance Matrix: configurazione

API Distance Matrix: errori comuni

  • Problema: ogni richiesta lato server è limitata a 100 elementi (origini x destinazioni) e a 25 origini o 25 destinazioni. Le richieste più grandi restituiscono MAX_ELEMENTS_EXCEEDED o MAX_DIMENSIONS_EXCEEDED. Correzione: suddividi la matrice in richieste di non più di 100 elementi e 25 origini o destinazioni. Consulta /maps/documentation/distance-matrix/usage-and-billing#usage-limits.
  • Problema: se non specifichi departure_time, il percorso e la durata si basano sul traffico medio indipendente dal tempo e non viene restituito duration_in_traffic. I risultati possono variare nel tempo. Correzione: imposta departure_time su now o su un orario futuro con mode=driving per ottenere durate che tengono conto del traffico. Tieni presente che le richieste di traffico vengono fatturate a una tariffa più elevata. Consulta /maps/documentation/distance-matrix/distance-matrix.
  • Problema: il parametro units modifica solo il testo nei campi della distanza. Il valore della distanza è sempre espresso in metri. Correzione: leggi distance.value come metri o utilizza distance.text per la visualizzazione. Consulta /maps/documentation/distance-matrix/distance-matrix.
  • Problema: la chiamata all'API Distance Matrix (Legacy) da un progetto in cui non è abilitata restituisce REQUEST_DENIED in status e un error_message che rimanda a LegacyApiNotActivatedMapError. Gli assistenti AI spesso generano codice API legacy per impostazione predefinita. Correzione: esegui la migrazione all'API Routes computeRouteMatrix (con l'intestazione X-Goog-FieldMask). Attiva l'API precedente tramite modulo solo come misura a breve termine. Consulta /maps/legacy#LegacyApiNotActivatedMapError.