Eseguire la migrazione da Geocoding v3 a v4

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ù.

L'API Geocoding v4 introduce diversi nuovi endpoint che sostituiscono le funzionalità della versione 3 dell'API. Questa guida mostra come eseguire la migrazione dell'app per utilizzare i nuovi endpoint v4.

Puoi utilizzare le chiavi API esistenti con i nuovi endpoint v4. Tuttavia, se hai richiesto un aumento della quota nella versione 3 dell'API, devi richiedere un aumento nelle nuove API v4. Non esiste un percorso di migrazione per gli utenti JavaScript.

Nota:durante l'anteprima, i metodi dell'API Geocoding v4 sono limitati a 25 query al secondo (QPS). Per informazioni su come richiedere una quota più elevata, vedi Visualizza e gestisci le quote e seleziona API Geocoding come servizio.

Eseguire la migrazione dalla geocodifica diretta v3

Se utilizzi la geocodifica per geocodificare gli indirizzi, devi eseguire la migrazione all'endpoint v4 Geocode an address, che accetta una richiesta GET.

L'API v4 modifica i nomi, la struttura e il supporto di diversi parametri. Ti consigliamo vivamente di utilizzare una maschera del campo per specificare i campi che vuoi che vengano restituiti nella risposta.

Avviso: in tutti gli endpoint v4, i nomi dei campi sono formattati utilizzando la notazione camel case minuscola (ad es. addressComponents), a differenza degli endpoint v3, che utilizzavano la notazione snake case (ad es. address_components). Le risposte RPC continuano a utilizzare la notazione snake case nella versione 4, come nella versione 3.

Modifiche ai parametri di richiesta

Parametro v3	Parametro v4	Note
address, components	address	L'indirizzo non strutturato (v3 address) viene ora passato nel percorso dell'URL. I filtri dei componenti (v3 components) ora vengono passati come parametri di query address.*.
bounds	locationBias.rectangle	Rinominato; la struttura è stata modificata in oggetto.
language	languageCode	Rinominato.
region	regionCode	Rinominato.
extra_computations	Rimosso

Modifiche ai campi di risposta

v3 Field	Campo v4	Note
status, error_message	Rimosso	La versione 4 utilizza codici di stato HTTP e corpi degli errori.
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	Rinominato.
results.geometry.location_type	results.granularity	Rinominato.
results.geometry.location	results.location	Nomi dei campi: lat/lng -> latitude/longitude.
results.geometry.viewport	results.viewport	Nomi dei campi: northeast/southwest -> high/low.
results.postcode_localities	results.postalCodeLocalities	Rinominato. Ora restituito per una o più località (v3 richiesto > 1).
results.partial_match	Rimosso
Novità	results.addressComponents.languageCode	Lingua del componente specifico dell'indirizzo.
Novità	results.bounds	Limiti espliciti che utilizzano high/low.
Novità	results.place	Il nome della risorsa per il luogo.
Novità	results.postalAddress	Oggetto PostalAddress strutturato.

Migrazione dalla geocodifica inversa v3

Se utilizzi la geocodifica inversa per trasformare le coordinate in indirizzi, devi eseguire la migrazione all'endpoint v4 Geocodifica inversa di una posizione, che accetta una richiesta GET.

L'API v4 modifica i nomi, la struttura e il supporto di diversi parametri. Ti consigliamo vivamente di utilizzare una maschera del campo per specificare i campi che vuoi che vengano restituiti nella risposta.

Avviso: in tutti gli endpoint v4, i nomi dei campi sono formattati utilizzando la notazione camel case minuscola (ad es. addressComponents), a differenza degli endpoint v3, che utilizzavano la notazione snake case (ad es. address_components). Le risposte RPC continuano a utilizzare la notazione snake case nella versione 4, come nella versione 3.

Modifiche ai parametri di richiesta

Parametro v3	Parametro v4	Note
language	languageCode	Rinominato.
region	regionCode	Rinominato.
result_type	types	Rinomato; utilizza parametri di query ripetuti.
location_type	granularity	Rinomato; utilizza parametri di query ripetuti.
extra_computations	Rimosso

Modifiche ai campi di risposta

v3 Field	Campo v4	Note
status, error_message	Rimosso	La versione 4 utilizza codici di stato HTTP e corpi degli errori.
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	Rinominato.
results.geometry.location_type	results.granularity	Rinominato.
results.geometry.location	results.location	Nomi dei campi: lat/lng -> latitude/longitude.
results.geometry.viewport	results.viewport	Nomi dei campi: northeast/southwest -> high/low.
Novità	results.addressComponents.languageCode	Lingua del componente specifico dell'indirizzo.
Novità	results.bounds	Limiti espliciti che utilizzano high/low.
Novità	results.place	Il nome della risorsa per il luogo.
Novità	results.postalAddress	Oggetto PostalAddress strutturato.

Eseguire la migrazione da v3 Place Geocoding

Se utilizzi place_id per ottenere l'indirizzo di un ID luogo specifico con Geocoding v3, devi eseguire la migrazione all'endpoint v4 Place Geocoding, che accetta una richiesta GET.

L'API v4 modifica i nomi, la struttura e il supporto di diversi parametri. Ti consigliamo vivamente di utilizzare una maschera del campo per specificare i campi che vuoi che vengano restituiti nella risposta.

Avviso: in tutti gli endpoint v4, i nomi dei campi sono formattati utilizzando la notazione camel case minuscola (ad es. addressComponents), a differenza degli endpoint v3, che utilizzavano la notazione snake case (ad es. address_components). Le risposte RPC continuano a utilizzare la notazione snake case nella versione 4, come nella versione 3.

Modifiche ai parametri di richiesta

Parametro v3	Parametro v4	Note
place_id	place campo nel proto della richiesta	L'ID luogo viene ora fornito come parametro di percorso places/{place}, ad esempio: https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. Questo campo corrisponde al campo luogo della richiesta sottostante.
language	languageCode	Rinominato.
region	regionCode	Rinominato.

Modifiche ai campi di risposta

v3 Field	Campo v4	Note
status, error_message	Rimosso	La versione 4 utilizza codici di stato HTTP e corpi degli errori.
results	(root)	La versione 4 restituisce un singolo oggetto risultato, non un array results.
results.address_components.long_name/results.address_components.short_name	addressComponents.longText/addressComponents.shortText	Rinominato.
results.geometry.location_type	granularity	Rinominato.
results.geometry.location	location	Nomi dei campi: lat/lng -> latitude/longitude.
results.geometry.viewport	viewport	Nomi dei campi: northeast/southwest -> high/low.
results.postcode_localities	postalCodeLocalities	Rinominato. Ora restituito per una o più località (v3 richiesto > 1).
Novità	addressComponents.languageCode	Lingua del componente specifico dell'indirizzo.
Novità	bounds	Limiti espliciti che utilizzano high/low.
Novità	place	Il nome della risorsa per il luogo.
Novità	postalAddress	Oggetto PostalAddress strutturato.

Eseguire la migrazione da Geocoding Hyperlocal Data a Destinations

Le seguenti funzionalità dell'API Geocoding v3 vengono sostituite dall'endpoint SearchDestinations dell'API Geocoding v4:

• Entrate
• Punti di navigazione
• Contorni degli edifici
• Terreni

Se utilizzavi l'API Geocoding v3 per le funzionalità sopra indicate, utilizza questo documento per utilizzare invece l'endpoint SearchDestinations e ottenere queste funzionalità. Questo documento spiega in quale punto della risposta dell'API SearchDestinations trovare queste funzionalità e le differenze nel modo in cui queste funzionalità sono rappresentate nelle risposte dell'API tra l'API Geocoding v3 e l'endpoint SearchDestinations dell'API Geocoding v4.

Entrate

Per ottenere gli ingressi associati a un destination, utilizza il campo destination.entrances.

Tieni presente che il formato di un entrance è leggermente diverso dal formato di ingresso nell'API Geocoding v3. Ogni ingresso in destination.entrances ha i seguenti campi:

• displayName: questo è un nuovo campo facoltativo che conterrà un nome leggibile per l'ingresso, ad esempio "Cancello B".
• location: si tratta di una località di tipo LatLng, che è diverso dal formato utilizzato nell'API Geocoding v3.
• tags: è uguale al campo tags degli ingressi dell'API Geocoding v3.
• place: analogo al campo buildingPlaceId degli ingressi dell'API Geocoding v3. Tuttavia, l'ID luogo in questo campo potrebbe essere per un luogo di qualsiasi tipo, non necessariamente solo un edificio.

Punti di navigazione

Per ottenere i punti di navigazione associati a un destination, utilizza il campo destination.navigationPoints.

Tieni presente che il formato di un navigationPoint è leggermente diverso dal formato del punto di navigazione nell'API Geocoding v3. Ogni punto di navigazione in destination.navigationPoints ha i seguenti campi:

• displayName: questo è un nuovo campo facoltativo che avrà un nome leggibile per il punto di navigazione, ad esempio "5th Ave".
• location: si tratta di una località di tipo LatLng, che è diverso dal formato utilizzato nell'API Geocoding v3.
• travelModes: questo campo è simile a restrictedTravelModes dei punti di navigazione dell'API Geocoding v3. I valori enum possibili sono gli stessi, l'unica differenza è che questo campo ora rappresenta le modalità di trasporto accettabili per il punto di navigazione, anziché quelle con limitazioni.
• usage: questo è un nuovo campo che contiene i casi d'uso supportati dal punto di navigazione. Tieni presente che la maggior parte dei punti di navigazione avrà un utilizzo di UNKNOWN, ma ciò non significa necessariamente che l'utilizzo del punto di navigazione sia limitato in alcun modo.

Contorni degli edifici

Per ottenere i contorni degli edifici associati a un destination, devi utilizzare il campo displayPolygon degli oggetti placeView nel destination che rappresentano gli edifici. Per ogni placeView, puoi controllare se si tratta di un edificio con il campo placeView.structureType. Se il tipo di struttura è BUILDING, puoi ottenere la struttura dal campo placeView.displayPolygon. placeView avrà anche campi aggiuntivi per l'edificio che non erano presenti nell'API Geocoding v3.

Nota: stai cercando solo il poligono dell'edificio in una determinata posizione? Puoi utilizzare il parametro placeFilter nella richiesta per restringere i risultati. Per restituire solo i risultati degli edifici, imposta structureType su "BUILDING" all'interno di placeFilter. Se la tua priorità è ottenere un poligono (anche per le località senza indirizzi precisi), imposta addressability su "ANY" in placeFilter per restituire il poligono più preciso disponibile.

Esempio

{
  "locationQuery": {
    "location": {
      "latitude": 37.4224,
      "longitude": -122.0841
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "ANY"
    }
  }
}
  

Un destination può avere un oggetto placeView che rappresenta un edificio nei seguenti campi:

• destination.primary: questo è il luogo principale per la destinazione.
• destination.containingPlaces: si tratta di un campo ripetuto che può contenere luoghi più grandi che "contengono" il luogo principale. Ad esempio, se il luogo principale è un subpremise, containingPlaces di solito contiene placeView che rappresenta l'edificio.
• destination.subDestinations: si tratta di un campo ripetuto che può contenere le destinazioni secondarie del luogo principale. Ad esempio, singole unità di un edificio. In genere questo campo non contiene un placeView che rappresenta un edificio.

Tieni presente che il formato di placeView.displayPolygon corrisponde al formato contorno dell'edificio nell'API Geocoding v3, ovvero il formato GeoJSON, che utilizza il formato RFC 7946.

Terreni

Analogamente alla creazione di schemi, per ottenere i motivi associati a un destination, devi utilizzare il campo displayPolygon degli oggetti placeView nel destination che rappresentano i motivi. Per ogni placeView, puoi verificare se si tratta di un motivo con il campo placeView.structureType. Se il tipo di struttura è GROUNDS, puoi ottenere la struttura dal campo placeView.displayPolygon. placeView avrà anche campi aggiuntivi per i motivi che non erano presenti nell'API Geocoding v3.

Un destination può avere un oggetto placeView che rappresenta un motivo nei seguenti campi:

• destination.primary
• destination.containingPlaces
• destination.subDestinations

Tieni presente che il formato di placeView.displayPolygon corrisponde al formato contorno del terreno nell'API Geocoding v3, ovvero il formato GeoJSON, che utilizza il formato RFC 7946.

Utilizza una maschera di campo per richiedere queste funzionalità

L'endpoint SearchDestinations richiede una maschera di campo, come spiegato in Scegliere i campi da restituire. La maschera del campo può essere impostata su * per restituire tutti i campi oppure puoi impostarla sui campi specifici che vuoi ricevere. Ad esempio, la seguente richiesta API imposta la maschera del campo per ricevere tutti i campi necessari per ottenere gli ingressi, i punti di navigazione, i contorni degli edifici e i terreni di una destinazione:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations