Weryfikacja adresu a geokodowanie

Cel

Często musisz sprawdzić lokalizację miejsca. W Google Maps Platform jest kilka usług, które mogą Ci w tym pomóc. Z tego dokumentu dowiesz się, jak wybrać jedną z 2 głównych usług weryfikacji lokalizacji – Address Validation API i Geocoding API.

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

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

Ogólne informacje o różnicach między Weryfikacją adresów a Geocoding API znajdziesz tutaj.

Kiedy wybrać Weryfikację adresów zamiast Geocoding API

Address-Validation-vs-Geocoding

Uwagi dotyczące powyższego schematu blokowego:

  • Przypadek użycia interakcji z użytkownikiem odnosi się do sytuacji, w której użytkownik jest obecny i może wchodzić w interakcje z wynikami.
  • Autouzupełnianie miejsc to interfejs API JavaScript, dlatego nadaje się do integracji z interfejsami użytkownika.
  • Możesz mieć świadomość problemów z jakością danych w swoich dotychczasowych adresach. Dlatego, chociaż możesz potrzebować tylko geokodów, zalecamy sprawdzenie tych lokalizacji za pomocą Address Validation API, aby poprawić zbiory danych.

W wielu sytuacjach możesz wybrać, na podstawie powyższego drzewa decyzyjnego, jeden produkt zamiast drugiego. W innych sytuacjach do osiągnięcia celów może być konieczne użycie obu produktów.

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

  • istnieje duże prawdopodobieństwo, że dane są wątpliwe, lub gdy nieprawidłowy adres będzie miał negatywny wpływ na dalsze działania. Dzieje się tak, ponieważ Address Validation API zapewnia 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ększa prawdopodobieństwo uzyskania dokładnego wyniku.
  • region docelowy zwraca więcej metadanych z Address Validation API niż z Geocoding API, np. klasyfikację typu budynku jako mieszkalny lub komercyjny.

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 nie jest krytyczna.
    • Możesz na przykład wygenerować mapę cieplną na podstawie dużego zbioru danych.
  • potrzebujesz szczegółowych informacji o lokalizacji, takich jak wejścia do budynku, obrysy budynku lub punkty nawigacyjne odbioru i wysiadania (dostępne w metodzie SearchDestinations w Geocoding API w wersji 4).
  • potrzebujesz rozwiązania globalnego, a Address Validation API nie jest dostępne we wszystkich regionach docelowych.

Oto kilka przykładów, które pokazują możliwości Address Validation API w porównaniu z 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, stan 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, a Address Validation API odzwierciedla to 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 w przypadku ulicy Fake St, interfejs API stwierdził, że ulica może mieć taką nazwę, ale nie można jej dopasować do danych adresu.

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

Używając tego samego adresu w Geocoding API, można dopasować go do „Kalifornii”, jak widać na zrzucie ekranu z narzędzia do geokodowania, które możesz wypróbować tutaj:

alt_text

Wynikiem jest jednak geokod całego stanu z minimalnymi informacjami o tym, które komponenty danych wejściowych były potencjalnie nieprawidłowe.

Przykład błędu pisowni

76 Buckingamm Palace Road, Londn, SW1W 9TQ, GB

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

Zarówno 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 podać więcej informacji o tym procesie.

Spójrz na jeden z komponentów adresu, w którym wystąpił błąd pisowni:

{
  "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ę. Na podstawie tej flagi można zaimplementować logikę biznesową, aby sprawdzić poprawkę u dostawcy danych, np. u klienta podczas płatności w e-sklepie.

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

Bollschestraße 86, 12587, DE

Powyższy adres zawiera błąd pisowni w nazwie ulicy i brakuje w nim miasta (miejscowości) Berlin.

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

Bölschestraße 86, 12587 Berlin, DE

W tym przypadku Geocoding API nie może skutecznie naprawić błędów w 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 (Ste 123), który nie istnieje w budynku.

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

lokal:

"business": true

Dodatkowo wartość dpvConfirmation zwrócona w ramach uspsData w odpowiedzi to S:

"dpvConfirmation": "S"

Wartość dpvConfirmation równa S oznacza, że adres został zweryfikowany do poziomu 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 Geocoding API

Przegląd

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

Geocoding API działa na zasadzie rozwiązywania komponentów adresu w hierarchii.

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

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

ChIJwRKzf8ixD4gRHiXqucwr_HQ

Geocode API zawiera w odpowiedzi te informacje:

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

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

Jeśli nie uda się rozwiązać żadnego z komponentów danych wejściowych, interfejs API zwróci:

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

Wysłanie żądania tylko z adresem ulicy bez numeru domu spowoduje zwrócenie wyniku w postaci:

"types": [
  "route"
]

Oznacza to, że Geocoding API nie udało się znaleźć ani dopasować numeru domu.

Uwaga: aby sprawdzić, czy adres istnieje, sprawdź, czy w odpowiedzi Geocoding API są ustawione któreś z parametrów (np. types, partial_match, results, status)). Stopniowo zwiększy to poziom pewności, że adres może istnieć, ale nie będzie on w 100% dokładny. Dlatego potrzebujemy Address Validation API.

Za pomocą powyższych metod możesz zwiększyć pewność co do dokładności adresu na podstawie samej odpowiedzi interfejsu API Geocoding API. Jednak w przeciwieństwie do wyniku Address Validation API, Geocoding API nie zwróci dokładnych informacji, które pozwolą 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 Geocoding API response:

  • ROOFTOP oznacza, że zwrócony wynik to dokładny geokod, dla którego mamy informacje o lokalizacji dokładne do adresu ulicy.
  • RANGE_INTERPOLATED oznacza, ż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 dla adresu ulicy nie są dostępne geokody na dachu.
  • GEOMETRIC_CENTER oznacza, że zwrócony wynik to geometryczny środek wyniku, np. linii łamanej (np. ulicy) lub wielokąta (regionu).
  • APPROXIMATE oznacza, że zwrócony wynik nie jest żadnym z powyższych.

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

Ten rodzaj fałszywego dopasowania jest bardzo trudny do rozwiązania za pomocą Geocoding API. W najgorszym przypadku możesz rozważyć wdrożenie podstawowej weryfikacji po przetworzeniu danych na podstawie kraju i miejscowości w żądaniu lub odpowiedzi. Jeszcze lepiej porównaj rzeczywiste adresy ulic pod kątem błędów pisowni lub niepełnego adresu.

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

Częściowe dopasowanie i fałszywe dopasowanie

Jeśli adres jest częściowym dopasowaniem, co oznacza, że Geocoding API nie udało się dokładnie zidentyfikować adresu, odpowiedź zawiera:

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

Jeszcze ważniejsze niż powyższe typy lokalizacji jest sprawdzenie, kiedy partial_match = true pojawia się w odpowiedzi. partial_match oznacza, że Geocoding API nie zwróciło dopasowania ścisłego do pierwotnego żądania, ale udało mu się dopasować część żądanego adresu.

Możesz sprawdzić pierwotne żądanie pod kątem niepełnego adresu. Częściowe dopasowania najczęściej występują w przypadku adresów ulic, 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 do ulicy Henry Street, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera komponent adresu z błędem pisowni, Geocoding API może zasugerować alternatywny adres. Sugestie wywołane w ten sposób nie będą oznaczane jako częściowe dopasowanie.

Adresy syntetyczne

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 znajdziesz te wskaźniki, oznacz adres wejściowy jako nieprawidłowy i spróbuj ponownie go zweryfikować innymi sposobami.

Uwaga: to kolejny przykład, w którym Address Validation API bezpośrednio informuje, czy adres nie istnieje.

Interpretowanie odpowiedzi Address Validation API

Istnieje już świetna dokumentacja na temat interpretowania odpowiedzi z Address Validation API, więc nie będziemy tu wchodzić w szczegóły.

  • Przegląd obiektu odpowiedzi znajdziesz tutaj.
  • Wersja demonstracyjna, która ilustruje różne komponenty odpowiedzi, jest dostępna tutaj
  • W dokumencie Weryfikacja adresu na potrzeby płatności znajdziesz szczegółowy opis tego, jak odróżnić prawidłowe adresy od nieprawidłowych.

Sprawdzone metody

Określanie położenia geograficznego

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

  • Geocoding API – preferowanie regionu

    Jeśli wiesz, że geokody będą znajdować się w określonym kraju, możesz uzyskać znacznie lepsze wyniki, korzystając z preferowania regionu. Jeśli na przykład geokodujesz w Kanadzie, zalecamy dodanie &region=ca do żądań, aby preferować Kanadę. Pamiętaj, że preferowanie regionu preferuje tylko wyniki w tym regionie. 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 za pomocą pola regionCode.

Przechowywanie identyfikatorów miejsc

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

Aby mieć zawsze najbardziej aktualne informacje, odświeżaj identyfikatory miejsc co 12 miesięcy za pomocą żądania informacje o miejscu z parametrem place_id.

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

Podsumowanie

W tym dokumencie opisujemy główne różnice między Address Validation API a Geocoding API. Podsumowując, rozważ użycie Address Validation API, gdy:

  • wymagany jest dokładny adres pocztowy, zwłaszcza na potrzeby dostarczania przesyłek.
  • dane wejściowe są niskiej jakości. Address Validation API jest bardziej tolerancyjny na błędy w danych wejściowych, wyróżnia niezweryfikowane komponenty adresu i wprowadza poprawki w danych wejściowych.
  • potrzebujesz więcej informacji o adresie, np. czy jest to adres mieszkalny czy komercyjny (dostępne w wybranych regionach).

Następne kroki

Pobierz dokument Improve checkout, delivery, and operations with reliable addresses (Usprawnianie płatności, dostawy i operacji dzięki wiarygodnym adresom) i obejrzyj webinar Improving checkout, delivery, and operations with Address Validation (Usprawnianie płatności, dostawy i operacji dzięki weryfikacji adresu).

Sugerowane dalsze lektury:

Współtwórcy

Google jest autorem tego artykułu. Pierwotnie napisali go ci współtwórcy:

Główni autorzy:

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

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

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