Geocodifica con maggiore precisione

Questo prodotto o questa funzionalità sono sperimentali (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 di Google Maps Platform. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Sviluppatori dello Spazio economico europeo (SEE)

Se il tuo indirizzo di fatturazione si trova nello Spazio economico europeo, a partire dall'8 luglio 2025, i Termini di servizio di Google Maps Platform per il SEE si applicheranno al tuo utilizzo dei servizi. La funzionalità varia in base alla regione. Scopri di più.

I metodi GeocodeAddress e SearchDestinations supportano un parametro effort facoltativo che consente di controllare il compromesso tra la latenza della risposta e l'accuratezza della risoluzione degli indirizzi.

Mentre il geocoding standard gestisce gli indirizzi postali ben formattati con una latenza inferiore al secondo, gli input reali sono spesso incompleti, informali o complessi (ad esempio "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai" o "where the warriors play, sf"). Configurando un livello effort più elevato, puoi indicare all'API Geocoding di applicare un ragionamento e una disambiguazione estesi per risolvere gli indirizzi difficili.

Importante: questa funzionalità è disponibile nel canale v4alpha. Scopri di più sui canali delle fasi di lancio.

Livelli di impegno

Specifica uno dei seguenti valori per il parametro effort:

Livello di impegno	Descrizione	Latenza tipica	Casi d'uso consigliati
EFFORT_UNSPECIFIED	Valore predefinito. Si comporta come l'effort LOW.	Sub-second	Geocodifica standard predefinita.
LOW	Ottimizza per i tempi di risposta più rapidi. Non esegue ricerche estese o disambiguazione per indirizzi difficili.	Sub-second	Ricerca interattiva in tempo reale, Address Validation standard ad alto volume.
MEDIUM	Bilancia velocità e accuratezza. La maggior parte delle richieste viene restituita con una bassa latenza standard. Per indirizzi ambigui o difficili, il servizio applica un'elaborazione aggiuntiva per migliorare l'accuratezza, che potrebbe richiedere fino a qualche secondo.	Meno di un secondo per gli indirizzi standard; fino a pochi secondi (≤ 4 secondi) per gli indirizzi ambigui	Flussi di lavoro interattivi degli utenti (come la conferma dell'indirizzo al momento del pagamento) in cui gli utenti possono tollerare una breve pausa.
HIGH	Massimizza l'accuratezza della risoluzione degli indirizzi per indirizzi incompleti, informali o complessi. I tempi di risposta potrebbero essere notevolmente più lunghi.	Fino a 20 secondi per indirizzi complessi	Elaborazione in background, geocodifica in batch, spedizione logistica o perfezionamento asincrono dell'indirizzo dopo il pagamento.

Nota: i livelli di impegno MEDIUM e HIGH utilizzano i modelli Gemini per elaborare e disambiguare indirizzi complessi. Le risposte vengono risolte utilizzando l'AI e potrebbero contenere errori.

Esempi di richieste

Cerca destinazioni (SearchDestinations)

Includi il campo effort nel corpo della richiesta JSON della richiesta POST a https://geocode.googleapis.com/v4alpha/geocode/destinations. Il parametro effort influisce principalmente sulla risoluzione di addressQuery:

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
  },
  "effort": "HIGH"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

Geocodifica un indirizzo (GeocodeAddress)

Passa il parametro effort come parametro di query URL nella richiesta GET all'endpoint /v4alpha/:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4alpha/geocode/address/where+the+warriors+play,+sf?effort=MEDIUM"

Mitigazione dell'impatto della latenza

Quando utilizzi l'effort MEDIUM o HIGH nella tua applicazione, l'invio di una richiesta single-pass è l'integrazione più semplice, ma le richieste in queste modalità possono comportare una latenza più elevata, che può ritardare i workflow sincroni, rivolti agli utenti e sensibili alla latenza.

Per mitigare questo impatto della latenza sui flussi utente interattivi (come il pagamento o la prenotazione), puoi utilizzare un flusso di lavoro in più passaggi:

1. Passaggio 1 (interattivo): invia una richiesta sincrona con effort=LOW (o predefinito) per convalidare immediatamente l'indirizzo con una latenza inferiore al secondo.
2. Passaggio 2 (background): invia una richiesta di follow-up asincrona con effort=MEDIUM o effort=HIGH (ad esempio, dopo il pagamento o prima della spedizione) per risolvere indirizzi complessi in coordinate, ingressi e punti di navigazione ad alta precisione senza bloccare l'utente.

Limiti di utilizzo

Durante la fase di lancio sperimentale (v4alpha), le richieste con effort impostato su MEDIUM o HIGH sono soggette a limiti di frequenza più severi rispetto alle richieste standard (LOW). Se la tua applicazione supera questi limiti di frequenza, l'API restituisce un errore RESOURCE_EXHAUSTED (HTTP 429). Se riscontri errori HTTP 429 o hai bisogno di una quota più elevata per il tuo caso d'uso, contattaci tramite il canale di feedback.

Feedback

Questa è una funzionalità sperimentale dell'API Geocoding. Apprezziamo i feedback all'indirizzo [e-mail].