Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Weryfikacja adresu a geokodowanie

Cel

Często musisz sprawdzać lokalizację miejsca. W Google Maps Platform jest kilka usług, które mogą Ci pomóc w tym przypadku użycia. Ten dokument pomoże Ci wybrać jedną z 2 głównych usług weryfikacji lokalizacji – Address Validation API lub Geocoding API.

Address Validation API to usługa Google Maps Platform, która pomaga klientom sprawdzić, czy adres jest prawidłowy.

Geokodowanie za pomocą interfejsu Geocoding API to proces przekształcania adresów we współrzędne geograficzne, których można używać do umieszczania znaczników na mapie lub pozycji na mapie.

Ogólne omówienie różnic między interfejsami Weryfikacja adresów i Geocoding API znajdziesz tutaj.

Kiedy wybrać Address Validation API, a kiedy Geocoding API

Address-Validation-vs-Geocoding

Uwagi dotyczące powyższego schematu blokowego:

Przypadek użycia związany z interakcją użytkownika odnosi się do sytuacji, gdy użytkownik jest obecny, aby wejść w interakcję z wynikami.
Autouzupełnianie miejsc to interfejs API JavaScript, który nadaje się do integracji z interfejsami użytkownika.
Możesz mieć świadomość problemów z jakością danych w przypadku istniejących adresów. Dlatego nawet jeśli potrzebujesz tylko kodów geograficznych, zalecamy sprawdzenie tych lokalizacji za pomocą interfejsu Address Validation API, aby poprawić zbiory danych.

Istnieje wiele sytuacji, w których na podstawie powyższego drzewa decyzyjnego możesz wybrać jedną usługę zamiast drugiej. W innych sytuacjach do osiągnięcia celów może być konieczne użycie obu usług.

Możesz użyć interfejsu Address Validation API zamiast Geocoding API, gdy:

Istnieje duże prawdopodobieństwo, że dane są wątpliwe lub że uzyskanie nieprawidłowego adresu będzie miało negatywny wpływ na dalsze działania. Dzieje się tak, ponieważ Address Validation API dostarcza więcej informacji o tym, dlaczego dane wejściowe nie uzyskały wyniku o wysokiej precyzji.
Musisz poprawić dane wejściowe użytkownika (np. błędy pisowni lub brakujące pola), co zwiększy prawdopodobieństwo uzyskania dokładnego wyniku na wyjściu.
W przypadku regionu docelowego interfejs Address Validation API zwraca więcej metadanych niż interfejs Geocoding API, np. klasyfikację typu budynku jako mieszkalnego lub komercyjnego.

Możesz wybrać Geocoding API zamiast Address Validation API, gdy:

Twoim głównym celem jest pobranie lokalizacji adresu, a dokładność poszczególnych adresów może nie być kluczowa.
- Możesz na przykład wygenerować mapę termiczną z dużego zbioru danych.
potrzebujesz bardzo szczegółowych informacji o miejscu docelowym, takich jak wejścia do budynków, ich obrysy czy punkty nawigacyjne odbioru i wysiadania (dostępne w metodzie SearchDestinations w Geocoding API w wersji 4);
Potrzebujesz rozwiązania globalnego, a interfejs Address Validation API nie jest dostępny we wszystkich regionach docelowych.

Poniżej znajdziesz kilka przykładów, które pokazują możliwości interfejsu Address Validation API w porównaniu z interfejsem Geocoding API.

Przykład nieprawidłowego adresu

1 Fake St, Mountain View, CA 94043, USA

Address Validation API dzieli te dane wejściowe na poszczególne komponenty adresu (ulica, miasto, województwo itp.). Może też podać szczegółowe informacje o tym, dlaczego adres jest nieprawidłowy, aż do poziomu PREMISE.

Ulica Fake St nie istnieje w Mountain View w Kalifornii, co Address Validation API odzwierciedla w zwróconych szczegółach na poziomie komponentu:

{
  "componentName": {
    "text": "Fake St",
    "languageCode": "en"
   },
   "componentType": "route",
   "confirmationLevel":"UNCONFIRMED_BUT_PLAUSIBLE"
 }

W tym przypadku ważną właściwością do sprawdzenia jest confirmationLevel. Zwracając wartość UNCONFIRMED_BUT_PLAUSIBLE dla Fake St, interfejs API określił, że ulica może mieć taką nazwę, ale nie można jej dopasować do danych adresowych.

Na podstawie wyniku interfejsu API można wywnioskować, że błąd dotyczy komponentu ulicy w tych danych wejściowych (Fake St).

Jeśli użyjesz tego samego adresu w interfejsie Geocoding API, będzie on mógł dopasować go do „Kalifornii”, jak pokazano na tym zrzucie ekranu z narzędzia Geocoder:

alt_text

Wynikiem jest jednak kod geograficzny całego stanu, z minimalną ilością informacji o tym, które komponenty w danych wejściowych były potencjalnie błędne.

Przykład błędu pisowni

76 Buckingham Palace Road, London, SW1W 9TQ, Wielka Brytania

Powyższy adres zawiera kilka błędów pisowni – jeden w nazwie ulicy, a drugi w nazwie miejscowości.

Zarówno interfejs Address Validation API, jak i Geocoding API mogą poprawić te błędy i uzyskać wynik 76 Buckingham Palace Road, London, SW1W 9TQ. Address Validation API może jednak dostarczyć więcej informacji o tym procesie.

Spójrz na jeden z komponentów adresu, który został błędnie wpisany:

{
  "componentName": {
    "text": "Buckingham Palace Road",
    "languageCode": "en"
        },
        "componentType": "route",
        "confirmationLevel": "CONFIRMED",
        "spellCorrected": true
     }
}

Address Validation API zwraca flagę wskazującą, że w polu wprowadzono poprawkę. Logika biznesowa może zostać zaimplementowana w odniesieniu do tego znacznika, aby dokładnie sprawdzić korektę u dostawcy danych, np. klienta w procesie płatności w e-commerce.

Przykład brakujących danych i błędu pisowni

Bollschestraße 86, 12587, DE

W powyższym adresie występuje błąd pisowni w nazwie ulicy i brakuje nazwy miasta (miejscowości) Berlin.

Interfejs Address Validation API może naprawić oba te błędy i zwrócić kod geograficzny na poziomie PREMISE oraz adres zweryfikowany na poziomie PREMISE:

Bölschestraße 86, 12587 Berlin, DE

W tym przypadku interfejs Geocoding API nie jest w stanie rozwiązać problemu z błędami danych wejściowych i zwraca wynik ZERO_RESULTS.

Przykład dodatkowych metadanych adresu

111 8th Avenue Ste 123, New York, NY 10011-5201, US

Ten adres jest prawidłowy, z wyjątkiem numeru lokalu (lok. 123), który nie istnieje w budynku.

Interfejs Address Validation API może zweryfikować adres do PREMISE (111 8th Ave) i podać pewne metadane dotyczące nieruchomości, w tym informację, że jest to nieruchomość komercyjna.

lokal:

"business": true

Dodatkowo wartość dpvConfirmation zwracana jako część uspsData w odpowiedzi to S:

"dpvConfirmation": "S"

Wartość dpvConfirmation równa S wskazuje, że adres został zweryfikowany na poziomie PREMISE, ale numer lokalu podany w danych wejściowych nie jest powiązany z tym adresem.

Geocoding API nie może podać tych informacji.

Interpretowanie odpowiedzi interfejsu Geocoding API

Przegląd

Jeśli używasz interfejsu Geocoding API, wynik geokodowania zawiera w odpowiedzi różne wskazówki, które mogą pomóc w zrozumieniu szczegółów podanego adresu.

Interfejs Geocoding API działa przez rozpoznawanie komponentów adresu w hierarchii.

Na przykład 123 Example Street, Chicago, 60007, USA jest rozwiązywane w tej kolejności:

/ Example Street/ Chicago/ 60007/ USA będą oceniane w tej kolejności. W tym przypadku pierwszym dopasowaniem jest Chicago, a dokładniej kod pocztowy 60007. Dlatego dla tego kodu pocztowego zwraca ten identyfikator Place_id:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

Odpowiedź z interfejsu Geocode API zawiera te informacje:

        "partial_match": true,
           "place_id": "ChIJwRKzf8ixD4gRHiXqucwr_HQ",
           "types": [
               "postal_code"
           ]

Interfejs Geocoding API może potwierdzić, do jakiego rodzaju miejsca należy ten adres. Listę types adresów zwracanych przez interfejs Geocoding API znajdziesz tutaj.

Jeśli nie uda się rozpoznać żadnego z komponentów danych wejściowych, interfejs API zwraca:

{
   "results": [],
   "status": "ZERO_RESULTS"
}

Żądanie zawierające tylko nazwę ulicy bez numeru domu zwraca wynik w formie:

"types": [
  "route"
]

Oznacza to, że interfejs Geocoding API nie mógł znaleźć lub dopasować numeru domu.

Uwaga: aby dowiedzieć się, czy adres istnieje, sprawdź, czy w odpowiedzi interfejsu Geocoding API są ustawione jakieś parametry (np. types, partial_match, results, status)). Spowoduje to stopniowe zwiększanie poziomu ufności, że adres może istnieć, ale nie zapewni 100% dokładności. Dlatego potrzebujemy interfejsu Address Validation API.

Możesz użyć powyższych technik, aby zwiększyć pewność co do dokładności adresu na podstawie samej odpowiedzi interfejsu Geocoding API. Jednak w przeciwieństwie do wyniku Address Validation API interfejs Geocoding API nie zwraca dokładnych informacji zwrotnych, które pozwalają określić dokładność wyniku.

Typ lokalizacji

Aby dobrze zrozumieć tę sekcję, musisz poznać różne typy lokalizacji, które mogą być zwracane w odpowiedzi interfejsu Geocoding API:

ROOFTOP wskazuje, że zwrócony wynik jest dokładnym kodem geograficznym, dla którego mamy informacje o lokalizacji z dokładnością do adresu ulicy.
RANGE_INTERPOLATED wskazuje, że zwrócony wynik odzwierciedla przybliżenie (zwykle na drodze) interpolowane między 2 dokładnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy kody geograficzne dachu są niedostępne dla adresu ulicy.
GEOMETRIC_CENTER wskazuje, że zwrócony wynik jest środkiem geometrycznym wyniku, np. linii łamanej (np. ulicy) lub wielokąta (regionu).
APPROXIMATE oznacza, że zwrócony wynik nie jest żadnym z powyższych.

Jeśli interfejs Geocoding API zwraca location_type o wartości ROOFTOP lub RANGE_INTERPOLATED, nie musi to oznaczać, że adres istnieje. Podobnie, jeśli interfejs Geocoding API zwraca flagę partial_match ustawioną na true, może to być prawidłowy wynik.

Ten rodzaj błędnego dopasowania jest bardzo trudny do rozwiązania za pomocą interfejsu Geocoding API. Możesz przynajmniej rozważyć wdrożenie podstawowej weryfikacji po przetworzeniu w przypadku kraju i miejscowości żądania/odpowiedzi. Najlepiej porównać adresy ulic pod kątem błędów pisowni lub niekompletnych adresów.

Uwaga: jeśli zdecydujesz się używać interfejsu Geocoding API, zalecamy regularne sprawdzanie jakości danych między początkowym żądaniem a odpowiedzią interfejsu Geocoding API.

Częściowe dopasowanie i fałszywe dopasowanie

Jeśli adres jest częściowo dopasowany, co oznacza, że interfejs Geocoding API nie mógł dokładnie zidentyfikować adresu, odpowiedź zawiera:

"partial_match": true,
"types": [
           "locality",
           "political"
         ]

Jeszcze ważniejsze od powyższych typów lokalizacji jest to, kiedy partial_match = true jest w odpowiedzi. partial_match wskazuje, że interfejs Geocoding API nie zwrócił dokładnego dopasowania do pierwotnego żądania, ale udało mu się dopasować część żądanego adresu.

Możesz sprawdzić, czy w pierwotnej prośbie nie ma niekompletnego adresu. Częściowe dopasowania występują najczęściej w przypadku adresów, które nie istnieją w miejscowości określonej w żądaniu. Częściowe dopasowania mogą być też zwracane, gdy żądanie pasuje do co najmniej 2 lokalizacji w tej samej miejscowości.

Na przykład „21 Henr St, Bristol, UK” zwraca częściowe dopasowanie zarówno dla Henry Street, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera błędnie wpisany komponent adresu, interfejs Geocoding API może zasugerować alternatywny adres. Sugestie wywołane w ten sposób nie będą oznaczane jako częściowe dopasowanie.

Adresy syntetyczne

Interfejs Geocoding API może zwracać lokalizacje dla „syntetycznych” adresów, które nie istnieją jako dokładne lokalizacje w bazie danych Google.

W takich przypadkach obiekt odpowiedzi często zawiera długi identyfikator miejsca i tę właściwość: geometry.location_type=APPROXIMATE.

Jeśli w odpowiedzi pojawią się te wskaźniki, rozważ oznaczenie adresu wejściowego jako nieprawidłowego i spróbuj ponownie go zweryfikować w inny sposób.

Uwaga: to kolejny przykład, w którym dzięki Address Validation API otrzymujesz bezpośrednią informację zwrotną, jeśli adres nie istnieje.

Odpowiedź interfejsu Address Validation API

Istnieje już obszerna dokumentacja dotycząca interpretowania odpowiedzi z interfejsu Address Validation API, więc nie będziemy się tutaj zagłębiać w szczegóły.

Przegląd obiektu odpowiedzi znajdziesz tutaj.
Wersję demonstracyjną, która ilustruje różne komponenty odpowiedzi, znajdziesz tutaj.
W dokumencie dotyczącym weryfikacji adresów na potrzeby płatności znajdziesz szczegółowy opis tego, jak odróżnić prawidłowe adresy od nieprawidłowych.

Sprawdzone metody

Określanie lokalizacji geograficznej

Podczas wywoływania interfejsów Weryfikacja adresów API lub Geocoding API najlepiej jest ograniczyć obszar geograficzny, na którym ma być wyszukiwany adres. Te 2 interfejsy API implementują to na 2 różne sposoby:

Geocoding API – ukierunkowanie na region

Jeśli wiesz, że kody geograficzne będą znajdować się w określonym kraju, możesz uzyskać znacznie lepsze wyniki, korzystając z ustawień regionalnych. Jeśli na przykład geokodujesz w Kanadzie, zalecamy dodanie do żądań parametru &region=ca, aby wyniki były bardziej dopasowane do Kanady. Pamiętaj, że funkcja ta jedynie preferuje wyniki z danego regionu. Nadal możesz otrzymywać wyniki spoza regionu.
Address Validation API – kod regionu

Podobnie Address Validation API generuje dokładniejsze wyniki, jeśli w żądaniu zostanie przekazany kod ISO2 w polu regionCode.

Przechowywanie identyfikatorów miejsc

Aby przechowywać informacje z Google Maps Platform o lokalizacji na potrzeby przyszłych żądań, możesz bezterminowo przechowywać identyfikator miejsca w swojej bazie danych jako atrybut lokalizacji. Żądanie Znajdź miejsce wystarczy wysłać tylko raz na każdy identyfikator miejsca. Możesz też wyszukiwać identyfikator miejsca za każdym razem, gdy użytkownik prosi o szczegóły transakcji.

Aby mieć pewność, że zawsze masz najbardziej aktualne informacje, co 12 miesięcy odświeżaj identyfikatory miejsc, używając żądania informacji o miejscu z parametrem place_id.

Uwaga: zapoznaj się też z przewodnikiem po sprawdzonych metodach geokodowania.

Podsumowanie

W tym dokumencie opisujemy podstawowe różnice między interfejsami Weryfikacja adresów API i Geocoding API. Podsumowując, rozważ użycie interfejsu Address Validation API, gdy:

Dokładny adres pocztowy jest wymagany, zwłaszcza ze względu na możliwość dostarczenia przesyłki.
Dane wejściowe są niskiej jakości. Address Validation API jest bardziej wyrozumiały w przypadku błędów we wprowadzanych danych, wyróżnia nieweryfikowalne komponenty adresu i wprowadza poprawki do wprowadzonych danych.
Wymagane są dodatkowe informacje o adresie, np. czy jest to adres prywatny czy firmowy (dostępne w wybranych regionach).

Następne kroki

Pobierz dokument podsumowujący Usprawnianie procesów płatności, dostawy i operacji dzięki wiarygodnym adresom i obejrzyj webinar Usprawnianie procesów płatności, dostawy i operacji dzięki weryfikacji adresów .

Sugerowane artykuły:

Współtwórcy

Google zarządza tym artykułem. The following contributors originally wrote it.

Główni autorzy:

Henrik Valve | inżynier ds. rozwiązań

Thomas Anglaret | inżynier ds. rozwiązań

Sarthak Ganguly | inżynier ds. rozwiązań