Eseguire la migrazione da Geocoding v3 a v4

Sviluppatori dello Spazio economico europeo (SEE)

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

Puoi utilizzare le chiavi API esistenti con i nuovi metodi v4. Tuttavia, se hai richiesto un aumento della quota nella v3 dell'API, devi richiedere un aumento nelle nuove API v4.

Esegui la migrazione dalla geocodifica diretta v3

Se utilizzi v3 Geocoding per geocodificare gli indirizzi, devi eseguire la migrazione al metodo 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 di campo per specificare i campi che vuoi che vengano restituiti nella risposta.

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 componenti dell'indirizzo strutturato (v3 components) possono essere passati come parametri di query address.*. Consulta la sezione Riproduci i filtri dei componenti v3.
bounds locationBias.rectangle Rinominato; struttura modificata in oggetto.
language languageCode Rinominato. Se omesso, v3 utilizza l'intestazione Accept-Language o il valore predefinito en, mentre v4 utilizza per impostazione predefinita la lingua e lo script locali della località.
region regionCode Rinominato. Se omesso, v3 assume il valore predefinito us, mentre v4 non ha un valore predefinito.
extra_computations Rimosso Sostituito dal metodo SearchDestinations.

Modifiche ai campi di risposta

Campo v3 Campo v4 Note
status, error_message Rimosso La versione 4 utilizza i codici di stato HTTP e i 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 richiede >1).
results.partial_match Rimosso
Novità results.addressComponents.languageCode Lingua del componente dell'indirizzo specifico.
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.

Riproduci i filtri dei componenti v3

Il geocoding diretto nella versione 3 includeva un parametro components che consentiva il filtraggio rigido dei risultati per componenti specifici (ad es. components=country:US). Il geocoding diretto nella versione 4 non supporta questo tipo di filtraggio rigido nei parametri della richiesta. Nella versione 4, puoi fornire informazioni sull'indirizzo come una singola stringa non strutturata nel percorso o come parametri di query strutturati come address.addressLines, address.locality, address.administrativeArea, address.postalCode e address.regionCode. I parametri strutturati non fungono da filtri rigidi. Invece, tutti i componenti forniti vengono combinati per formare l'indirizzo completo che l'API tenterà di geocodificare. L'API cerca la corrispondenza migliore per l'intero indirizzo specificato in tutti i componenti. Fornire i componenti in modo strutturato può aiutare l'API a comprendere meglio l'intent, soprattutto quando le informazioni sull'indirizzo vengono raccolte da campi del modulo separati. In questo modo, l'API può gestire piccoli errori di battitura o ambiguità all'interno di ogni componente, poiché il tipo di informazioni in ogni campo è chiaro.

Per ottenere un comportamento simile ai filtri dei componenti rigidi della versione 3, devi implementare il filtro lato client nell'array results restituito dall'API v4 in base agli oggetti postalAddress e addressComponents nella risposta.

La tabella seguente mostra la corrispondenza migliore tra i filtri components v3 e i campi postalAddress v4:

Filtro dei componenti v3 Campo di risposta v4
country postalAddress.regionCode
postal_code postalAddress.postalCode
administrative_area postalAddress.administrativeArea o addressComponents

Esempi di filtri lato client

Gli esempi seguenti mostrano come filtrare i risultati per ottenere un comportamento simile al filtro dei componenti v3 per i campi supportati: paese, area amministrativa e codice postale. Ti sconsigliamo di filtrare in base ad altri campi, in quanto non esistono criteri di filtro affidabili.

Filtra per paese

Abbina il address.regionCode della tua richiesta al postalAddress.regionCode in ogni risultato. Tieni presente che, sebbene l'API accetti codici regione in minuscolo nella richiesta, li restituisce sempre in maiuscolo nella risposta, quindi devi normalizzare l'input in maiuscolo prima del confronto.

Esempio di codice Python 
def filter_by_country(results, region_code):
    return [
        res for res in results
        if res.get('postalAddress', {}).get('regionCode') == region_code.upper()
    ]

# Example usage:
# v4_response = ... # API call response
# filtered = filter_by_country(v4_response.get('results', []), 'US')
Esempio di codice Node.js 
function filterByCountry(results, regionCode) {
    return results.filter(res => res.postalAddress?.regionCode === regionCode.toUpperCase());
}

// Example usage:
// const v4Response = ... # API call response
// const filtered = filterByCountry(v4Response.results, 'US');
Filtra per area amministrativa

Abbina il address.administrativeArea della tua richiesta al postalAddress.administrativeArea in ogni risultato. Analogamente ai codici paese, devi normalizzare l'input in lettere maiuscole prima del confronto. Questo è affidabile solo quando il administrativeArea nella richiesta viene fornito con un'abbreviazione standard di 2 lettere. Il valore postalAddress.administrativeArea nella risposta potrebbe non corrispondere direttamente ai suffissi dei codici ISO 3166-2 per diversi motivi. In primo luogo, in alcune aree la suddivisione corrispondente al codice ISO 3166-2 non fa parte della rappresentazione standard degli indirizzi postali. Ad esempio, in Spagna, l'area amministrativa di livello 1 (ad es. "CN" per le Canarie) potrebbe essere presente in addressComponents, ma postalAddress.administrativeArea potrebbe contenere l'area di livello 2 (ad es. "Santa Cruz de Tenerife"). In secondo luogo, in alcune aree l'abbreviazione della suddivisione non è di uso comune ed è rappresentata in postalAddress.administrativeArea con un nome più lungo (per motivi simili, addressComponents.shortText per il componente dell'indirizzo corrispondente alla suddivisione potrebbe non corrispondere al suffisso del codice ISO 3166-2 della suddivisione). Inoltre, in alcuni casi la suddivisione può essere rappresentata nel componente dell'indirizzo per administrative_area_level_n con n maggiore di 1. Per ottenere i risultati più completi, devi verificare la presenza di una corrispondenza sia in postalAddress.administrativeArea sia in qualsiasi addressComponents con un tipo administrative_area_level_n (ad es. administrative_area_level_1).

Esempio di codice Python 
def filter_by_admin_area(results, admin_area):
    target = admin_area.upper()
    filtered = []
    for res in results:
        # Check postalAddress
        pa_aa = res.get('postalAddress', {}).get('administrativeArea', '')
        if pa_aa == target:
            filtered.append(res)
            continue
        # Check all administrative area levels in addressComponents
        for comp in res.get('addressComponents', []):
            is_admin_level = any(t.startswith('administrative_area_level_')
                               for t in comp.get('types', []))
            if is_admin_level:
                short = comp.get('shortText', '')
                if short == target:
                    filtered.append(res)
                    break
    return filtered

# Example usage:
# filtered = filter_by_admin_area(v4_response.get('results', []), 'CA')
Esempio di codice Node.js 
function filterByAdminArea(results, adminArea) {
    const target = adminArea.toUpperCase();
    return results.filter(res => {
        // Check postalAddress.administrativeArea
        if (res.postalAddress?.administrativeArea === target) {
            return true;
        }
        // Check addressComponents for any administrative area level
        return res.addressComponents?.some(c => {
            const isAdmin = c.types?.some(t => t.startsWith('administrative_area_level_'));
            return isAdmin && c.shortText === target;
        });
    });
}

// Example usage:
// const filtered = filterByAdminArea(v4Response.results, 'CA');
Filtra per codice postale

Abbina il address.postalCode della tua richiesta al postalAddress.postalCode in ogni risultato. Devi normalizzare sia i codici postali di input che quelli dei risultati prima del confronto. La logica di normalizzazione dipende molto dalla regione. Un approccio di base prevede la rimozione di spazi e trattini e la conversione in un formato coerente.

Potrebbe essere necessaria una normalizzazione più avanzata per gestire i prefissi dei codici postali (ad es. "L2" nel Regno Unito) o i suffissi (ad es. "+4" nei codici postali degli Stati Uniti). La logica di normalizzazione specifica richiesta varia a seconda del paese e dei formati dei codici postali coinvolti. Potresti dover adattare le funzioni di normalizzazione fornite o implementare una logica più sofisticata per le regioni di targeting.

L'esempio fornito gestisce i codici postali degli Stati Uniti e consente la corrispondenza sulla base di 5 cifre anche se viene fornito o restituito il codice postale + 4.

Esempio di codice Python (incentrato sul codice postale degli Stati Uniti) 
import re

def normalize_postal_code_us(pc):
    # Basic normalization for US: uppercase, alphanumeric only
    if not pc:
        return ""
    normalized = re.sub(r'[^A-Z0-9]', '', pc.upper())
    # Return only the first 5 digits for US ZIP codes
    return normalized[:5]

def filter_by_postal_code_us(results, postal_code):
    normalized_input = normalize_postal_code_us(postal_code)
    if not normalized_input:
        return []
    filtered_results = []
    for res in results:
        pa_pc = res.get('postalAddress', {}).get('postalCode', '')
        if normalize_postal_code_us(pa_pc) == normalized_input:
            filtered_results.append(res)
    return filtered_results

# Example usage:
# Matches '94043', '94043-1351', '940431351'
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043')
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043-1234')
Esempio di codice Node.js (incentrato sul codice postale degli Stati Uniti) 
function normalizePostalCodeUs(pc) {
    // Basic normalization for US: uppercase, alphanumeric only
    const normalized = (pc || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
    // Return only the first 5 digits for US ZIP codes
    return normalized.substring(0, 5);
}

function filterByPostalCodeUs(results, postalCode) {
    const normalizedInput = normalizePostalCodeUs(postalCode);
    if (!normalizedInput) {
        return [];
    }
    return results.filter(res => {
        const paPc = res.postalAddress?.postalCode || '';
        return normalizePostalCodeUs(paPc) === normalizedInput;
    });
}

// Example usage:
// Matches '94043', '94043-1351', '940431351'
// const filtered = filterByPostalCodeUs(v4Response.results, '94043');
// const filtered = filterByPostalCodeUs(v4Response.results, '94043-1234');

Eseguire la migrazione dalla geocodifica inversa v3

Se utilizzi la geocodifica inversa v3 per trasformare le coordinate in indirizzi, devi eseguire la migrazione al metodo v4 Geocodifica inversa di una località, 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 di campo per specificare i campi che vuoi che vengano restituiti nella risposta.

Modifiche ai parametri di richiesta

Parametro v3 Parametro v4 Note
language languageCode Rinominato. Se omesso, v3 utilizza l'intestazione Accept-Language o il valore predefinito en, mentre v4 utilizza per impostazione predefinita la lingua e lo script locali della località.
region regionCode Rinominato. Se omesso, v3 ha come valore predefinito us, mentre v4 non ha un valore predefinito.
result_type types Rinominato; utilizza parametri di query ripetuti.
location_type granularity Rinominato; utilizza parametri di query ripetuti.
extra_computations Rimosso Sostituito dal metodo SearchDestinations.

Modifiche al campo di risposta

Campo v3 Campo v4 Note
status, error_message Rimosso La versione v4 utilizza i codici di stato HTTP e i 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 dell'indirizzo specifico.
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.

Esegui la migrazione dai descrittori degli indirizzi v3

Se utilizzi address_descriptor per ottenere informazioni aggiuntive su una località con Geocoding v3, devi eseguire la migrazione all'utilizzo del campo landmarks di SearchDestinationsResponse.

Esegui la migrazione dalla geocodifica dei luoghi v3

Se utilizzi place_id per ottenere l'indirizzo di un ID luogo specifico con Geocoding v3, devi eseguire la migrazione al metodo Geocoding dei luoghi v4, 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.

Modifiche ai parametri di richiesta

Parametro v3 Parametro v4 Note
place_id Campo place nel proto della richiesta L'ID luogo viene ora fornito come parametro di percorso places/{place}, ad esempio: https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. Questo corrisponde al campo del luogo nella richiesta sottostante.
language languageCode Rinominato. Se omesso, v3 utilizza l'intestazione Accept-Language o il valore predefinito en, mentre v4 utilizza per impostazione predefinita la lingua e lo script locali della località.
region regionCode Rinominato. Se omesso, v3 ha come valore predefinito us, mentre v4 non ha un valore predefinito.

Modifiche ai campi di risposta

Campo v3 Campo v4 Note
status, error_message Rimosso La versione v4 utilizza i codici di stato HTTP e i 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 richiede >1).
Novità addressComponents.languageCode Lingua del componente dell'indirizzo specifico.
Novità bounds Limiti espliciti che utilizzano high/low.
Novità place Il nome della risorsa per il luogo.
Novità postalAddress Oggetto PostalAddress strutturato.

Esegui la migrazione dai dati iperlocali di geocodifica a Destinations

Le seguenti funzionalità dell'API Geocoding v3 verranno sostituite dal metodo SearchDestinations dell'API Geocoding v4:

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

Se utilizzavi l'API Geocoding v3 per le funzionalità precedenti, utilizza questo documento per aiutarti a utilizzare il metodo SearchDestinations per ottenere queste funzionalità. Questo documento spiega dove trovare queste funzionalità nella risposta SearchDestinations e le differenze nel modo in cui queste funzionalità sono rappresentate nelle risposte dell'API tra l'API Geocoding v3 e il metodo 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 "Gate B".
  • location: si tratta di una località di tipo LatLng, che è diverso dal formato utilizzato nell'API Geocoding v3.
  • tags: corrisponde 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 relativo a un luogo di qualsiasi tipo, non necessariamente solo a un edificio.

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 è diversa dal formato utilizzato nell'API Geocoding v3.
  • travelModes: è simile al campo 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.

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

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

  • destination.primary: questo è il luogo principale della 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 il placeView che rappresenta l'edificio.
  • destination.subDestinations: si tratta di un campo ripetuto che può contenere le destinazioni secondarie del luogo principale. Ad esempio, i singoli appartamenti 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 del profilo dell'edificio nell'API Geocoding v3, ovvero il formato GeoJSON, che utilizza il formato RFC 7946.

Terreni

Analogamente ai profili degli edifici, per ottenere i terreni associati a un destination, devi utilizzare il campo displayPolygon degli oggetti placeView nel destination che rappresentano i terreni. Per ogni placeView, puoi verificare se si tratta di un terreno 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 terreni 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.

Precisione dei risultati

Nell'API Geocoding v3, il campo location_type nella geometria della risposta indicava la precisione dei risultati e alcuni client classificavano o filtrava i risultati in base a questi valori (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER e APPROXIMATE). Nelle migrazioni standard dell'API Geocoding v4, questo campo viene rinominato granularity.

Nell'API Destinations (v4 SearchDestinations), non esiste un campo location_type. Le informazioni spaziali vengono invece gestite in modo diverso:

  • Nessun filtro lato client manuale necessario: mentre il Geocoding standard fornisce più risultati con granularità diverse, il metodo SearchDestinations riduce al minimo l'ambiguità risolvendo in un'unica destinazione ottimizzata, quando possibile. In questo modo, i clienti non devono filtrare in base al tipo di località per determinare quale risultato è il migliore.
  • Informazioni spaziali rappresentate dal tipo di struttura e dai poligoni di visualizzazione: La geometria e la struttura spaziali sono indicate da:
    • displayPolygon (per la geometria esatta).
    • Il campo structureType all'interno dell'oggetto placeView.
  • Mappatura del tipo di struttura:
    • Un structureType di POINT, BUILDING o SECTION corrisponde generalmente a quello che in precedenza era chiamato ROOFTOP.
    • Un structureType di GROUNDS corrisponde in genere a GEOMETRIC_CENTER.

Utilizza una maschera di campo per richiedere queste funzionalità

Il metodo SearchDestinations richiede una maschera di campo, come spiegato in Scegli 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/v4/geocode/destinations

Considerazioni sulla sicurezza

L'API Geocoding v4 è progettata come API server-to-server. Non esiste un percorso di migrazione diretto per gli utenti JavaScript dalla versione 3 alla versione 4. La chiamata diretta ai metodi v4 da JavaScript lato client (ad esempio in un browser) utilizzando una chiave API espone la chiave API a un rischio elevato di furto e uso improprio.

Le limitazioni dei referrer HTTP, sebbene utili, non sono una protezione sufficiente per gli endpoint dei servizi web, in quanto possono essere facilmente aggirate da utenti malintenzionati che falsificano l'intestazione Referer nelle loro richieste.

Il modo consigliato per utilizzare l'API Geocoding v4 è dal tuo server di backend. L'applicazione client deve inviare richieste a questo server intermediario, che poi chiama l'API di Google in modo sicuro utilizzando una chiave API protetta (ad esempio, una chiave archiviata in una variabile di ambiente o in un Secret Manager). In questo modo, la chiave API non viene mai esposta nel codice frontend.

Alternative per le esigenze lato client

Se hai esigenze lato client che richiedono la geocodifica, valuta la possibilità di utilizzare una delle soluzioni lato client esistenti: