Eseguire la migrazione da Geocoding v3 a v4

Sviluppatori dello Spazio economico europeo (SEE)

L'API Geocoding v4 introduce diversi nuovi metodi che sostituiscono le funzionalità della v3 dell'API. Questa guida mostra come eseguire la migrazione dell'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 versione 3 dell'API, devi richiedere un aumento nelle nuove API v4.

Migrazione dalla codifica geografica 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 del 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.*. Vedi Riprodurre i filtri dei componenti v3.
bounds locationBias.rectangle Rinominato; la struttura è stata modificata in oggetto.
language languageCode Rinominato.
region regionCode Rinominato.
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 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à (è richiesta la versione 3 > 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.

Riprodurre 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 v4, 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. Al contrario, 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. Ciò può aiutare l'API a 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 rigidi dei componenti della v3, devi implementare il filtro lato client sull'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 della versione 3 e i campi postalAddress della versione 4:

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 della versione 3 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 valore è affidabile solo se il administrativeArea nella richiesta viene fornito con un'abbreviazione standard di due lettere. Il valore di postalAddress.administrativeArea nella risposta potrebbe non corrispondere direttamente ai suffissi del codice ISO 3166-2 per diversi motivi. Innanzitutto, in alcune aree la suddivisione corrispondente al codice ISO 3166-2 non fa parte della rappresentazione standard degli indirizzi postali. Ad esempio, in Spagna, il livello 1 dell'area amministrativa (ad es. "CN" per Canarias) potrebbe essere presente in addressComponents, ma postalAddress.administrativeArea potrebbe contenere il livello 2 dell'area (ad es. "Santa Cruz de Tenerife"). In secondo luogo, in alcune aree l'abbreviazione della suddivisione non è comunemente utilizzata 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 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 sia 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.

Per gestire i prefissi (ad es. "L2" nel Regno Unito) o i suffissi (ad es. "+4" nei codici postali statunitensi) dei codici postali potrebbe essere necessaria una normalizzazione più avanzata. 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'handle di esempio fornito gestisce i codici ZIP degli Stati Uniti e consente la corrispondenza con la base a 5 cifre anche se viene fornito o restituito ZIP+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 sui codici postali 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');

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 del 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.
region regionCode Rinominato.
result_type types Ridenominato; utilizza parametri di query ripetuti.
location_type granularity Ridenominato; utilizza parametri di query ripetuti.
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 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.

Esegui la migrazione dai descrittori dell'indirizzo 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.

Migrazione dalla geocodifica di Places v3

Se utilizzi place_id per ottenere l'indirizzo di un ID luogo specifico con Geocoding v3, devi eseguire la migrazione al metodo Place Geocoding 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 place campo 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 campo corrisponde al campo luogo nella richiesta sottostante.
language languageCode Rinominato.
region regionCode Rinominato.

Modifiche ai campi di risposta

Campo v3 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à (è richiesta la versione 3 > 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 Dati iperlocali di geocodifica a Destinazioni

Le seguenti funzionalità dell'API Geocoding v3 vengono 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 utilizzare il metodo SearchDestinations per ottenere queste funzionalità. Questo documento spiega in quale punto della risposta 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 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 "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.

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

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 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, 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, che è il formato GeoJSON, utilizzando 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 è presente il campo location_type. Le informazioni spaziali vengono invece gestite in modo diverso:

  • Nessun filtro manuale lato client necessario: mentre il geocoding standard fornisce più risultati con granularità diverse, il metodo SearchDestinations riduce al minimo l'ambiguità risolvendo una singola destinazione ottimizzata, ove possibile. In questo modo, i clienti non devono filtrare in base al tipo di località per determinare quale risultato è 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 in genere corrisponde a quello che in precedenza era chiamato ROOFTOP.
    • Un structureType di GROUNDS corrisponde generalmente a GEOMETRIC_CENTER.

Utilizzare una maschera di campo per richiedere queste funzionalità

Il metodo 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/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. Chiamare i metodi v4 direttamente da JavaScript lato client (ad esempio, in un browser) utilizzando una chiave API espone la chiave API a un elevato rischio di furto e uso improprio.

Le limitazioni del referrer HTTP, sebbene utili, non sono una protezione sufficiente per gli endpoint dei servizi web, in quanto possono essere facilmente aggirate dagli autori di attacchi 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 effettuare richieste a questo server intermediario, che chiama in modo sicuro l'API Google utilizzando una chiave API protetta (ad esempio, una chiave memorizzata in una variabile di ambiente o in un secret manager). In questo modo, la tua chiave API non viene mai esposta nel codice frontend.

Alternative per le esigenze lato client

Se hai esigenze lato client che richiedono il geocoding, valuta l'utilizzo di una delle soluzioni lato client esistenti: