Migracja z interfejsu Geocoding API w wersji 3 do wersji 4

Geocoding API w wersji 4 wprowadza kilka nowych metod, które zastępują funkcje z wersji 3. Z tego przewodnika dowiesz się, jak przenieść aplikację, aby korzystała z nowych metod w wersji 4.

Możesz używać dotychczasowych kluczy interfejsu API z nowymi metodami w wersji 4. Jeśli jednak poprosisz o zwiększenie limitu w przypadku interfejsu API w wersji 3, musisz poprosić o zwiększenie limitu w przypadku nowych interfejsów API w wersji 4.

Migracja z geokodowania w wersji 3

Jeśli do geokodowania adresów używasz Geocoding w wersji 3, przejdź na metodę Geocode an address w wersji 4, która akceptuje żądanie GET.

Interfejs API w wersji 4 zmienia nazwy, strukturę i obsługę kilku parametrów. Zdecydowanie zalecamy użycie maski pola, aby określić pola, które chcesz otrzymać w odpowiedzi.

Zmiany parametrów żądania

Zmiany w polu odpowiedzi

Odtwarzanie filtrów komponentów w wersji 3

Geokodowanie w wersji 3 zawierało parametr components, który umożliwiał dokładne filtrowanie wyników pod kątem określonych komponentów (np. components=country:US). Geokodowanie w wersji 4 nie obsługuje tego typu dokładnego filtrowania w parametrach żądania. W wersji 4 możesz podać informacje o adresie jako pojedynczy nieuporządkowany ciąg znaków w ścieżce lub jako uporządkowane parametry zapytania, takie jak address.addressLines, address.locality, address.administrativeArea, address.postalCode i address.regionCode. Parametry strukturalne nie działają jak filtry ścisłe. Zamiast tego wszystkie podane komponenty są łączone w pełny adres, który interfejs API spróbuje zakodować geograficznie. Interfejs API wyszukuje najlepsze dopasowanie dla całego adresu we wszystkich komponentach. Podanie komponentów w uporządkowany sposób może pomóc interfejsowi API lepiej zrozumieć intencje, zwłaszcza gdy informacje o adresie są zbierane z oddzielnych pól formularza. Może to pomóc interfejsowi API w obsłudze drobnych literówek lub niejednoznaczności w poszczególnych komponentach, ponieważ typ informacji w każdym polu jest jasny.

Aby uzyskać działanie podobne do filtrów komponentów twardych w wersji 3, musisz zaimplementować filtrowanie po stronie klienta w tablicy results zwracanej przez interfejs API w wersji 4 na podstawie obiektów postalAddress i addressComponents w odpowiedzi.

W tabeli poniżej znajdziesz najlepsze dopasowanie filtrów components w wersji 3 do pól postalAddress w wersji 4:

Przykłady filtrowania po stronie klienta

Poniższe przykłady pokazują, jak filtrować wyniki, aby uzyskać zachowanie podobne do filtrowania komponentów w wersji 3 w przypadku obsługiwanych pól: kraj, region i kod pocztowy. Nie zalecamy filtrowania według innych pól, ponieważ nie ma wiarygodnych kryteriów filtrowania.

Filtruj według kraju

Dopasuj parametr address.regionCode z żądania do parametru postalAddress.regionCode w każdym wyniku. Pamiętaj, że chociaż interfejs API akceptuje w żądaniu kody regionów pisane małymi literami, w odpowiedzi zawsze zwraca je pisane wielkimi literami, więc przed porównaniem musisz znormalizować dane wejściowe do wielkich liter.

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')

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');

Filtruj według regionu

Dopasuj parametr address.administrativeArea z żądania do parametru postalAddress.administrativeArea w każdym wyniku. Podobnie jak w przypadku kodów krajów, przed porównaniem należy znormalizować dane wejściowe do wielkich liter. Jest to wiarygodne tylko wtedy, gdy parametr administrativeArea w żądaniu jest podany ze standardowym 2-literowym skrótem. Symbol postalAddress.administrativeArea w odpowiedzi może nie odpowiadać bezpośrednio sufiksom kodów ISO 3166-2 z kilku powodów. Po pierwsze, w niektórych obszarach podział odpowiadający kodowi ISO 3166-2 nie jest częścią standardowej reprezentacji adresów pocztowych. Na przykład w Hiszpanii region administracyjny poziomu 1 (np. „CN” dla Wysp Kanaryjskich) może być obecny w addressComponents, ale postalAddress.administrativeArea może zawierać region poziomu 2 (np. „Santa Cruz de Tenerife”). Po drugie, w niektórych obszarach skrót nazwy podregionu nie jest powszechnie używany i jest reprezentowany w postalAddress.administrativeArea dłuższą nazwą (z podobnych powodów addressComponents.shortText dla komponentu adresu odpowiadającego podregionowi może nie pasować do sufiksu kodu ISO 3166-2 podregionu). W niektórych przypadkach podział może być też reprezentowany w komponencie adresu administrative_area_level_n, gdzie n jest większe niż 1. Aby uzyskać najbardziej wyczerpujące wyniki, sprawdź, czy występuje dopasowanie zarówno w postalAddress.administrativeArea, jak i w dowolnym addressComponents z typem administrative_area_level_n (np. administrative_area_level_1).

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')

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');

Filtrowanie według kodu pocztowego

Dopasuj parametr address.postalCode z żądania do parametru postalAddress.postalCode w każdym wyniku. Przed porównaniem musisz znormalizować zarówno wejściowe, jak i wynikowe kody pocztowe. Logika normalizacji zależy w dużej mierze od regionu. Podstawowe podejście polega na usunięciu spacji i łączników oraz przekształceniu tekstu na jednolity format.

W przypadku prefiksów kodów pocztowych (np. „L2” w Wielkiej Brytanii) lub sufiksów (np. „+4” w kodach pocztowych w USA) może być konieczna bardziej zaawansowana normalizacja. Wymagana logika normalizacji różni się w zależności od kraju i formatów kodów pocztowych. Może być konieczne dostosowanie podanych funkcji normalizacji lub wdrożenie bardziej zaawansowanej logiki w przypadku regionów, na które kierujesz reklamy.

Podany przykład dotyczy kodów pocztowych w USA i umożliwia dopasowanie na podstawie 5-cyfrowego kodu, nawet jeśli podany lub zwrócony jest kod ZIP+4.

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')

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');

Migracja z geokodowania odwrotnego w wersji 3

Jeśli używasz geokodowania zwrotnego w wersji 3 do przekształcania współrzędnych w adresy, musisz przejść na metodę Geokodowanie zwrotne lokalizacji w wersji 4, która akceptuje żądanie GET.

Interfejs API w wersji 4 zmienia nazwy, strukturę i obsługę kilku parametrów. Zdecydowanie zalecamy używanie maski pola do określania pól, które mają zostać zwrócone w odpowiedzi.

Zmiany parametrów żądania

Zmiany w polu odpowiedzi

Migracja z deskryptorów adresu w wersji 3

Jeśli używasz parametru address_descriptor, aby uzyskać dodatkowe informacje o lokalizacji za pomocą Geocoding v3, musisz przejść na używanie pola landmarks w SearchDestinationsResponse.

Migracja z geokodowania miejsc w wersji 3

Jeśli używasz place_id do pobierania adresu dla konkretnego identyfikatora miejsca za pomocą interfejsu Geocoding API w wersji 3, musisz przejść na metodę Place Geocoding w wersji 4, która akceptuje żądanie GET.

Interfejs API w wersji 4 zmienia nazwy, strukturę i obsługę kilku parametrów. Zdecydowanie zalecamy używanie maski pola do określania pól, które mają zostać zwrócone w odpowiedzi.

Zmiany parametrów żądania

Zmiany w polu odpowiedzi

Migracja z geokodowania hiperlokalnych danych do miejsc docelowych

Te funkcje interfejsu Geocoding API w wersji 3 są zastępowane przez metodę SearchDestinations interfejsu Geocoding API w wersji 4:

• Wejścia
• Punkty nawigacyjne
• Tworzenie konspektów
• Tereny posiadłości

Jeśli do korzystania z powyższych funkcji używasz interfejsu Geocoding API w wersji 3, zapoznaj się z tym dokumentem, aby dowiedzieć się, jak zamiast tego używać metody SearchDestinations. Z tego dokumentu dowiesz się, gdzie w SearchDestinationsodpowiedziSearchDestinations znajdziesz te funkcje, oraz poznasz różnice w sposobie ich reprezentowania w odpowiedziach interfejsu API między interfejsem Geocoding API w wersji 3 a metodą SearchDestinationsSearchDestinations interfejsu Geocoding API w wersji 4.

Wejścia

Aby uzyskać wejścia powiązane z destination, użyj pola destination.entrances.

Pamiętaj, że format entrance nieco się różni od formatu wejścia w Geocoding API w wersji 3. Każde wejście w obiekcie destination.entrances zawiera te pola:

• displayName – to nowe opcjonalne pole, które będzie zawierać zrozumiałą dla człowieka nazwę wejścia, np. „Brama B”.
• location – jest to lokalizacja typu LatLng, która różni się od formatu używanego w Geocoding API w wersji 3.
• tags – jest to to samo co pole tags wejść z interfejsu Geocoding API w wersji 3.
• place – odpowiednik pola buildingPlaceId wejść z interfejsu Geocoding API w wersji 3. Jednak identyfikator miejsca w tym polu może dotyczyć miejsca dowolnego typu, niekoniecznie budynku.

Punkty nawigacyjne

Aby uzyskać punkty nawigacyjne powiązane z destination, użyj pola destination.navigationPoints.

Pamiętaj, że format navigationPoint nieco się różni od formatu punktu nawigacyjnego w Geocoding API w wersji 3. Każdy punkt nawigacyjny w obiekcie destination.navigationPoints ma te pola:

• displayName – to nowe opcjonalne pole, które będzie zawierać zrozumiałą dla człowieka nazwę punktu nawigacyjnego, np. „5th Ave”.
• location – to lokalizacja typu LatLng, która różni się od formatu używanego w Geocoding API w wersji 3.
• travelModes – jest to podobne do pola restrictedTravelModes punktów nawigacyjnych z interfejsu Geocoding API w wersji 3. Możliwe wartości typu wyliczeniowego są takie same. Jedyna różnica polega na tym, że to pole reprezentuje teraz akceptowalne środki transportu dla punktu nawigacyjnego, a nie ograniczone środki transportu.
• usage – to nowe pole, które zawiera przypadki użycia obsługiwane przez punkt nawigacyjny.

Tworzenie konspektów

Aby uzyskać kontury budynków powiązane z destination, użyj pola displayPolygon obiektów placeView w destination, które reprezentują budynki. W przypadku każdego elementu placeView możesz sprawdzić, czy jest to budynek, za pomocą pola placeView.structureType. Jeśli typ struktury to BUILDING, możesz pobrać konspekt z pola placeView.displayPolygon. placeView będzie też zawierać dodatkowe pola dotyczące budynku, których nie było w interfejsie Geocoding API w wersji 3.

destination może mieć obiekt placeView reprezentujący budynek w tych polach:

• destination.primary – to jest główne miejsce docelowe.
• destination.containingPlaces – jest to pole powtarzane, które może zawierać większe miejsca, które „zawierają” miejsce główne. Jeśli na przykład głównym miejscem jest subpremise, containingPlaces zwykle zawiera placeView reprezentujący budynek.
• destination.subDestinations – jest to pole powtarzane, które może zawierać podrzędne miejsca docelowe głównego miejsca. Na przykład poszczególne mieszkania w budynku. To pole zwykle nie zawiera elementu placeView reprezentującego budynek.

Pamiętaj, że format placeView.displayPolygon jest zgodny z formatem konturu budynku w interfejsie Geocoding API wersji 3, czyli formatem GeoJSON, który korzysta z formatu RFC 7946.

Tereny posiadłości

Podobnie jak w przypadku konturów budynków, aby uzyskać tereny powiązane z destination, użyj pola displayPolygon obiektów placeView w destination, które reprezentują tereny. W przypadku każdego placeView możesz sprawdzić, czy jest to podstawa, korzystając z pola placeView.structureType. Jeśli typ struktury to GROUNDS, możesz pobrać konspekt z pola placeView.displayPolygon. placeView będzie też zawierać dodatkowe pola dotyczące terenów, których nie było w interfejsie Geocoding API w wersji 3.

Obiekt destination może zawierać obiekt placeView, który reprezentuje teren w tych polach:

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

Pamiętaj, że format placeView.displayPolygon jest zgodny z formatem konturu terenu w interfejsie Geocoding API w wersji 3, czyli formatem GeoJSON, który korzysta z formatu RFC 7946.

Dokładność wyników

W Geocoding API w wersji 3 pole location_type w geometrii odpowiedzi wskazywało precyzję wyników, a niektórzy klienci klasyfikowali lub filtrowali wyniki na podstawie tych wartości (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER i APPROXIMATE). W przypadku standardowych migracji do Geocoding API w wersji 4 to pole zostało zmienione na granularity.

W interfejsie Destinations API (wersja 4 SearchDestinations) nie ma pola location_type. Zamiast tego informacje przestrzenne są obsługiwane w inny sposób:

• Nie jest wymagane ręczne filtrowanie po stronie klienta: standardowe geokodowanie zapewnia wiele wyników o różnej szczegółowości, natomiast metoda SearchDestinations minimalizuje niejednoznaczność, zwracając w miarę możliwości pojedyncze, zoptymalizowane miejsce docelowe. Dzięki temu klienci nie muszą filtrować wyników według typu lokalizacji, aby określić, który z nich jest najlepszy.
• Informacje przestrzenne przedstawione za pomocą typu struktury i wielokątów wyświetlania: geometria przestrzenna i struktura są oznaczone:
  • displayPolygon (dla dokładnej geometrii).
  • Pole structureType w obiekcie placeView.
• Mapowanie typu struktury:
  • Wartość structureType w przypadku POINT, BUILDING lub SECTION odpowiada zwykle temu, co wcześniej nazywano ROOFTOP.
  • Wartość structureType równa GROUNDS odpowiada zwykle GEOMETRIC_CENTER.

Używanie maski pola do wysyłania żądań dotyczących tych funkcji

Metoda SearchDestinations wymaga maski pola, jak wyjaśniono w artykule Wybieranie pól do zwrócenia. Maskę pola można ustawić na *, aby zwrócić wszystkie pola, lub na konkretne pola, które chcesz otrzymać. Na przykład to żądanie API ustawia maskę pola, aby otrzymać wszystkie pola wymagane do uzyskania wejść, punktów nawigacyjnych, obrysów budynków i terenów miejsca docelowego:

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

Bezpieczeństwo

Interfejs Geocoding API w wersji 4 został zaprojektowany jako interfejs API między serwerami. Użytkownicy JavaScript nie mają bezpośredniej ścieżki migracji z wersji 3 do wersji 4. Wywoływanie metod w wersji 4 bezpośrednio z kodu JavaScript po stronie klienta (np. w przeglądarce) przy użyciu klucza interfejsu API naraża ten klucz na kradzież i niewłaściwe użycie.

Ograniczenia dotyczące odsyłającego HTTP, choć przydatne, nie zapewniają wystarczającej ochrony punktów końcowych usług internetowych, ponieważ mogą być łatwo omijane przez atakujących, którzy fałszują nagłówek Referer w swoich żądaniach.

Zalecane działania

Zalecany sposób korzystania z interfejsu Geocoding API w wersji 4 to używanie go na własnym serwerze backendu. Aplikacja kliencka powinna wysyłać żądania do tego serwera pośredniczącego, który następnie bezpiecznie wywołuje interfejs API Google za pomocą chronionego klucza interfejsu API (np. klucza przechowywanego w zmiennej środowiskowej lub Secret Managerze). Dzięki temu klucz interfejsu API nigdy nie będzie widoczny w kodzie interfejsu.

Alternatywne rozwiązania po stronie klienta

Jeśli masz potrzeby po stronie klienta, które wymagają geokodowania, rozważ użycie jednego z istniejących rozwiązań po stronie klienta:

• Usługa geokodowania w interfejsie Maps JavaScript API: usługa geokodowania nadal korzysta z backendu w wersji 3 i jest przeznaczona do użytku w środowisku przeglądarki.
• Places UI Kit: używaj Places UI Kit, w tym elementów autouzupełniania miejsc, do tworzenia elementów interfejsu użytkownika związanych z adresami.