Riferimento rapido dell'API Geocoding

L'API Geocoding è un servizio web che converte gli indirizzi in coordinate e ID luogo e viceversa. Il metodo v4 SearchDestinations restituisce anche i dettagli della destinazione, come gli ingressi degli edifici, i punti di navigazione, i contorni degli edifici e dei terreni e i punti di riferimento nelle vicinanze.

API Geocoding: informazioni chiave

  • Prodotto: API Geocoding
  • Categoria: Luoghi
  • Piattaforma: servizio web (REST)
  • Esecuzione su: server (codice di backend)
  • Fase di lancio: GA
  • Ciclo di vita: Attivo
  • Panoramica: Panoramica dell'API Geocoding

API Geocoding: quando utilizzarla

Utilizza l'API Geocoding quando:

  • Devi convertire un indirizzo in coordinate di latitudine/longitudine e un ID luogo sul tuo server di backend.
  • Per le coordinate GPS o un ID luogo noto, è necessario un indirizzo di visualizzazione o un'area amministrativa (città, codice postale).
  • Per indirizzare i conducenti o i corrieri verso una destinazione, sono necessari gli ingressi degli edifici, i punti di navigazione instradabili o i contorni degli edifici/terreni.
  • Devi risolvere una destinazione all'interno di un grande complesso (aeroporto, centro commerciale, campus) in sottodestinazioni o punti di riferimento nelle vicinanze.

Non utilizzare l'API Geocoding quando:

  • Hai bisogno della geocodifica da JavaScript del browser lato client; la chiamata alla versione v4 con una chiave API esposta rappresenta un rischio per la sicurezza. Utilizza invece l'API Maps JavaScript.
  • Devi calcolare un percorso o l'orario di arrivo stimato per la destinazione geocodificata. Utilizza invece l'API Routes.
  • Hai bisogno di indicazioni stradali passo passo per un token di un punto di navigazione in un'app per Android. Utilizza invece l'SDK Navigation per Android.
  • Hai bisogno di indicazioni stradali passo passo per un token di un punto di navigazione in un'app per iOS. Utilizza invece l'SDK Navigation per iOS.

API Geocoding: configurazione

API Geocoding: errori comuni

  • Problema: le richieste SearchDestinations senza una maschera di campo non vanno a buon fine e generano un errore; a differenza di GeocodeAddress, GeocodeLocation e GeocodePlace, la maschera di campo è obbligatoria. Correzione: imposta l'intestazione X-Goog-FieldMask o il parametro $fields su ogni richiesta SearchDestinations. Consulta /maps/documentation/geocoding/choose-fields.
  • Problema: v4 GeocodeAddress non ha un filtro dei componenti rigido (v3 components=country:US). I parametri address.* strutturati vengono combinati in un unico indirizzo e non filtrano i risultati; regionCode non ha un valore predefinito nella v4 (nella v3 il valore predefinito era us). Correzione: filtra results lato client: abbina regionCode in maiuscolo a postalAddress.regionCode; abbina le aree amministrative di 2 lettere in maiuscolo a postalAddress.administrativeArea e administrative_area_level_n addressComponents (shortText); normalizza sia l'input che postalAddress.postalCode (rimuovi spazi/trattini e applica le regole della regione). Consulta la pagina /maps/documentation/geocoding/geocoding-v4-migrate.
  • Problema: la chiamata all'API Geocoding v4 direttamente da JavaScript del browser espone la chiave API; le limitazioni dei referrer HTTP possono essere aggirate falsificando l'intestazione Referer. Correzione: chiama la versione 4 dal tuo backend con una chiave protetta o utilizza il servizio di geocodifica dell'API Maps JavaScript (backend versione 3) per le esigenze lato client. Consulta la pagina /maps/documentation/geocoding/geocoding-v4-migrate.
  • Problema: SearchDestinations può restituire risultati che non hanno un indirizzo principale preciso, a differenza della versione 3 e degli altri metodi della versione 4. Correzione: imposta placeFilter.addressability su PRIMARY quando hai bisogno solo di risultati con indirizzi principali precisi. Consulta la pagina /maps/documentation/geocoding/geocoding-v4-migrate.
  • Problema: il codice scritto per l'API Geocoding v3 non funziona con le risposte REST v4: v4 utilizza nomi di campi in formato lowerCamelCase (addressComponents, non address_components), rimuove status e error_message e restituisce un singolo oggetto principale da GeocodePlace anziché un array results. Correzione: controlla i codici di stato HTTP e i corpi degli errori nelle chiamate REST v4, leggi i campi lowerCamelCase (addressComponents, postalAddress) e tieni presente che le risposte gRPC utilizzano ancora snake_case. Consulta /maps/documentation/geocoding/geocoding-v4-migrate.

API Geocoding: funzionalità legacy e deprecate

  • Dati iperlocali dell'API Geocoding v3 (extra_computations: BUILDING_AND_ENTRANCES, NAVIGATION_POINTS, GROUNDS; campi di risposta buildings.entrances, navigation_points, buildings.building_outlines, grounds): ritirati dal 13 agosto 2025. Sostituzione: metodo SearchDestinations dell'API Geocoding v4 (POST /v4/geocode/destinations). Consulta la guida alla migrazione.

Cosa puoi fare con l'API Geocoding

Consulta le guide collegate di seguito per ogni attività o confronta i prodotti in Capabilities Explorer.