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
- Servizio da attivare:
geocoding-backend.googleapis.com - Autenticazione: chiave API, OAuth 2.0, service account
- Inizia: configura l'API Geocoding
- Riferimento: Riferimento API Geocoding
- Prezzi: utilizzo e fatturazione dell'API Geocoding
- Norme: norme relative all'API Geocoding
- Note di rilascio: note di rilascio dell'API Geocoding
API Geocoding: prodotti correlati
- Spesso utilizzato con: API Routes, SDK Navigation per Android, SDK Navigation per iOS
API Geocoding: errori comuni
- Problema: le richieste
SearchDestinationssenza una maschera di campo non vanno a buon fine e generano un errore; a differenza diGeocodeAddress,GeocodeLocationeGeocodePlace, la maschera di campo è obbligatoria. Correzione: imposta l'intestazioneX-Goog-FieldMasko il parametro$fieldssu ogni richiestaSearchDestinations. Consulta /maps/documentation/geocoding/choose-fields. - Problema: v4
GeocodeAddressnon ha un filtro dei componenti rigido (v3components=country:US). I parametriaddress.*strutturati vengono combinati in un unico indirizzo e non filtrano i risultati;regionCodenon ha un valore predefinito nella v4 (nella v3 il valore predefinito eraus). Correzione: filtraresultslato client: abbinaregionCodein maiuscolo apostalAddress.regionCode; abbina le aree amministrative di 2 lettere in maiuscolo apostalAddress.administrativeAreaeadministrative_area_level_naddressComponents(shortText); normalizza sia l'input chepostalAddress.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:
SearchDestinationspuò restituire risultati che non hanno un indirizzo principale preciso, a differenza della versione 3 e degli altri metodi della versione 4. Correzione: impostaplaceFilter.addressabilitysuPRIMARYquando 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, nonaddress_components), rimuovestatuseerror_messagee restituisce un singolo oggetto principale daGeocodePlaceanziché un arrayresults. 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 rispostabuildings.entrances,navigation_points,buildings.building_outlines,grounds): ritirati dal 13 agosto 2025. Sostituzione: metodoSearchDestinationsdell'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.
- Restituisce le coordinate di latitudine/longitudine di un indirizzo (geocodifica).
- Restituisce l'indirizzo per un insieme di coordinate di latitudine/longitudine (geocodifica inversa).
- Limita una richiesta di geocodifica per restituire i risultati all'interno di un'area visibile specifica. Nota: nell'API Geocoding v4, locationBias orienta i risultati verso l'area visibile specificata anziché limitarli rigorosamente.
- Limita una richiesta di geocodifica o geocodifica inversa in modo che restituisca solo i risultati all'interno di una regione, un paese o un codice postale specifici. Nota: nell'API Geocoding v4, regionCode indirizza i risultati verso una regione CLDR specificata anziché limitarli rigorosamente. Per il filtro dei componenti v3 legacy in base al paese o al codice postale, consulta https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering.
- Limita una richiesta di geocodifica inversa in modo che restituisca solo i risultati per i tipi di indirizzo specificati. Nota: nell'API Geocoding v4, il parametro types filtra i risultati della geocodifica inversa restituiti in base al tipo di indirizzo dopo la ricerca, anziché limitare la ricerca sottostante.
- Restituisce informazioni sulla vicinanza a punti di riferimento o aree per un indirizzo.
- Restituisce informazioni sulla vicinanza a punti di riferimento o aree per un insieme di coordinate di latitudine/longitudine.
- Restituisce informazioni sulla vicinanza a punti di riferimento o aree per un identificatore di luogo Google.
- Restituisce l'indirizzo di un identificatore di luogo Google.
- Restituisce le coordinate di latitudine/longitudine del perimetro di un edificio per un indirizzo.
- Restituisce le coordinate di latitudine/longitudine del perimetro di un edificio per un insieme di coordinate di latitudine/longitudine.
- Restituisce le coordinate di latitudine/longitudine del perimetro di un edificio per un identificatore di Google Places.
- Restituisce le coordinate di latitudine/longitudine dell'ingresso di un edificio per un indirizzo.
- Restituisce le coordinate di latitudine/longitudine dell'ingresso di un edificio per un insieme di coordinate di latitudine/longitudine.
- Restituisce le coordinate di latitudine/longitudine dell'ingresso di un edificio per un identificatore di Google Place.