Tworzenie możliwości weryfikacji lokalizacji przy użyciu Google Maps Platform

Cel

Często konieczne jest zweryfikowanie lokalizacji miejsca. W Google Maps Platform jest kilka różnych usług, które mogą Ci w tym pomóc. Ten dokument ułatwia wybór 2 głównych usług weryfikacji lokalizacji – interfejsu Address Validation API lub interfejsu Geocoding API.

Adres API weryfikacji adresów to oferta Google Maps Platform, która pomaga klientom sprawdzić, czy adres jest dokładny.

Geokodowanie w interfejsie Geocoding API to proces konwertowania adresów na współrzędne geograficzne, które można wykorzystać do umieszczania znaczników na mapie lub w jej miejscu.

Ogólne omówienie różnic między walidacją adresów a interfejsem Geocoding API znajdziesz tutaj.

Wypróbuj teraz: otwórz konsolę Google Cloud i włącz interfejsy Address Validation API oraz Places API.

Kiedy wybrać weryfikację adresów, a kiedy interfejs Geocoding API

Uwagi na temat powyższego schematu blokowego:

• Przypadek użycia związany z interakcją użytkownika odnosi się do sytuacji, gdy użytkownik jest obecny podczas interakcji z wynikami.
• Autouzupełnianie w Miejscach to interfejs API JavaScript, który nadaje się do integracji z interfejsami użytkownika.
• być może wiesz już o problemach z jakością danych w przypadku dotychczasowych adresów. Choć potrzebujesz tylko geokodów, zalecamy uruchamianie tych lokalizacji za pomocą interfejsu Address Validation API, aby poprawić zbiory danych.

Biorąc pod uwagę powyższe schematy decyzyjne, jest wiele sytuacji, w których możesz zdecydować się na zastosowanie jednej usługi zamiast drugiej. W innych sytuacjach do realizacji celów może być jednak konieczne korzystanie z obu tych usług.

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

• Istnieje duża szansa, że otrzymasz wątpliwe dane, lub gdy uzyskanie nieprawidłowego adresu będzie miało negatywny wpływ na dalszą pracę. Wynika to z faktu, że interfejs Address Validation API dostarcza więcej informacji o tym, dlaczego dane wejściowe nie uzyskały wyniku o wysokiej dokładności.
• Musisz poprawić dane wejściowe użytkownika (np. literówki lub brakujące pola), co zwiększa prawdopodobieństwo uzyskania dokładnych wyników.
• Twój region docelowy zwraca więcej metadanych z interfejsu Address Validation API niż interfejs Geocoding API, np. klasyfikację budynku jako mieszkalnego i komercyjnego.

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

• Głównym celem jest uzyskanie informacji o lokalizacji adresu. Dokładność poszczególnych adresów może nie być kluczowa.
  • Możesz na przykład wygenerować mapę termiczną na podstawie dużego zbioru danych.
• 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

Interfejs API do weryfikacji adresu dzieli te dane na poszczególne składowe adresu (ulica, miasto, stan itp.). Może też podawać szczegółowe informacje o tym, dlaczego adres nie jest prawidłowy (do poziomu PREMISE).

Fałszywa ulica Street nie istnieje w Mountain View w Kalifornii, a interfejs Address Validation API znajduje się w zwracanych szczegółach na poziomie komponentu:

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

Ważną właściwością, którą należy sprawdzić w tym przypadku, jest confirmationLevel. Zwracając wartość UNCONFIRMED_BUT_PLAUSIBLE w przypadku Fake Street, interfejs API ustalił, że ulica może mieć taką nazwę, ale nie można jej dopasować do dodatkowych danych adresowych.

Korzystając z wyników interfejsu API jako informacji zwrotnych, można wywnioskować, że błąd występuje w komponencie ulicy w tych danych wejściowych (Fake Street).

Korzystając z tego samego adresu w interfejsie Geocoding API, narzędzie może dopasować słowo „Kalifornia”, tak jak widać na zrzucie ekranu z narzędzia do geokodowania, które możesz wypróbować tutaj:

Efektem jest jednak geokod dla całego stanu, z minimalnym informacjami o tym, które komponenty składowe danych wejściowych są potencjalnie wadliwe.

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 nazwie miejscowości.

Zarówno interfejs API walidacji adresów, jak i Geocoding API mogą naprawić te błędy i uzyskać wynik 76 Buckingham Palace Road, London, SW1W 9TQ, Wielka Brytania. Więcej informacji o tym procesie można uzyskać za pomocą interfejsu Address Validation API.

Przyjrzyj się jednemu z komponentów adresu, które zostały błędnie wpisane:

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

Interfejs Address Validation API zwraca flagę wskazującą, że w polu wprowadzono poprawkę. W odniesieniu do tej flagi można wdrożyć logikę biznesową, aby dokładnie sprawdzić poprawkę u dostawcy danych, np. u klienta podczas płatności e-commerce.

Przykład brakujących danych i błędów pisowni

Bollschestraße 86, 12587, Niemcy

W podanym adresie występuje błąd pisowni w nazwie ulicy i brakuje miasta (rejonu) Berlina.

Interfejs Address Validation API może naprawić oba te błędy i zwróci geokod na poziomie PREMISE oraz adres, który został zweryfikowany na poziomie PREMISE:

Bölschestraße 86, 12587 Berlin, DE

W tym przypadku interfejs Geocoding API nie może pomyślnie przezwyciężyć błędów wejściowych i zwraca wynik ZERO_RESULTS.

Przykład dodatkowych metadanych adresu

111 8th Avenue Ste 123, Nowy Jork, NY 10011-5201, USA

Ten adres jest prawidłowy, z wyjątkiem numeru lokalu (Ste 123), którego nie ma w budynku.

Interfejs API do weryfikacji adresu może zweryfikować adres na stronie PREMISE (111 8th Ave) i podać pewne metadane dotyczące nieruchomości, w tym informację, że jest to adres komercyjny

obiekt:

"business": true

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

"dpvConfirmation": "S"

Wartość dpvConfirmation o wartości S oznacza, że adres został zweryfikowany na poziomie PREMISE, ale podany numer jednostki nie jest powiązany z tym adresem.

Interfejs Geocoding API nie może udostępnić tych informacji.

Zrozumienie odpowiedzi interfejsu Geocoding API

Przegląd

Jeśli używasz interfejsu Geocoding API, wynik geokodowania zawiera w odpowiedzi różne wskazówki, które pozwalają zrozumieć szczegółowe informacje o podanym adresie.

Sposób działania interfejsu Geocoding API polega na rozpoznawaniu komponentów adresu w hierarchii.

W przypadku **przykładu 123 Example Street, Chicago, 60007, USA rozstrzyga się w tej kolejności:

/ Example Street/ Chicago/ 60007/ USA , zostaną ocenione w tej kolejności. Pierwszym dopasowaniem w tym przypadku jest Chicago, a dokładniej: kod pocztowy 60007. W związku z tym zwraca następujące dane Place_id dla tego kodu pocztowego:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

Interfejs Geocode API zawiera w odpowiedzi 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ę adresów types zwróconych przez interfejs Geocoding API można znaleźć tutaj.

Jeśli żaden z komponentów danych wejściowych nie zostanie rozwiązany, interfejs API zwróci wartość:

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

Żądanie zawierające tylko ulicę i numer domu bez numeru domu zwraca wynik w takim formacie:

"types": [
  "route"
]

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

Uwaga: aby ustalić, czy adres istnieje, sprawdź, czy któryś z parametrów (np. types, partial_match, results, status)) jest ustawiony w odpowiedzi interfejsu Geocoding API. Spowoduje to stopniowe zwiększanie poziomu pewności, że adres może istnieć, ale nie sprawi, że będzie on w 100% dokładny. 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 interfejsu Address Validation API, interfejs Geocoding API nie zwraca dokładnych danych zwrotnych, aby określić dokładność wyników.

Typ lokalizacji

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

• ROOFTOP wskazuje, że zwrócony wynik to dokładny geokod, dla którego mamy informacje o lokalizacji z dokładnością do dokładnego adresu.
• RANGE_INTERPOLATED wskazuje, że zwrócony wynik odzwierciedla przybliżone (zwykle na drodze) interpolację między dwoma dokładnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy geokody dachowe dla adresu ulicy są niedostępne.
• GEOMETRIC_CENTER wskazuje, że zwrócony wynik stanowi środek geometryczny wyniku, np. linii łamanej (na przykład ulicy) lub wielokąta (region).
• APPROXIMATE oznacza, że zwrócony wynik nie należy do żadnego z powyższych.

Jeśli interfejs Geocoding API zwraca wartość location_type o wartości ROOFTOP lub RANGE_INTERPOLATED, nie musi to oznaczać, że adres istnieje. I podobnie, jeśli interfejs Geocoding API zwraca kod z flagą partial_match ustawioną na true, nadal może to być dla Ciebie właściwy wynik.

Ten typ fałszywego dopasowania to bardzo trudny problem do rozwiązania za pomocą interfejsu Geocoding API. Możesz rozważyć wdrożenie podstawowej weryfikacji po przetwarzaniu w kraju i regionie, z którego pochodzi prośba lub odpowiedź. Jeszcze lepiej jest porównać rzeczywiste adresy pocztowe pod kątem błędów pisowni i/lub niepełnych adresów.

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

Dopasowanie częściowe i fałszywe

Jeśli adres stanowi dopasowanie częściowe, co oznacza, że interfejs Geocoding API nie może dokładnie zidentyfikować adresu, odpowiedź zawiera:

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

Czas, w którym użytkownik partial_match = true znajduje się w odpowiedzi, ma jeszcze większe znaczenie niż w przypadku typów lokalizacji wymienionych powyżej. Wartość partial_match wskazuje, że interfejs Geocoding API nie zwrócił dokładnego dopasowania do pierwotnego żądania, mimo że był w stanie dopasować część żądanego adresu.

Sprawdź, czy pierwotne żądanie zawiera niepełne adresy. Dopasowania częściowe pojawiają się najczęściej w przypadku adresów, których nie ma w rejonie podanym w żądaniu. Częściowe dopasowania mogą też zostać zwrócone, gdy żądanie pasuje do co najmniej 2 lokalizacji w tym samym regionie.

Na przykład „21 Henr St, Bristol, UK” zwraca częściowe dopasowanie zarówno do ulicy Henry’ego, jak i dla ulicy Henrietta. Pamiętaj, że jeśli żądanie zawiera błędny adres, interfejs Geocoding API może zaproponować inny adres. Sugestie wywołane w ten sposób nie zostaną oznaczone jako pasujące częściowe.

Syntetyczne adresy

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

W takich sytuacjach obiekt odpowiedzi często zawiera długi identyfikator miejsca i następującą właściwość: geometry.location_type=APPROXIMATE.

Jeśli w odpowiedzi zauważysz te wskaźniki, oznacz adres wejściowy jako nieprawidłowy i spróbuj go zweryfikować w inny sposób.

Uwaga: to inny przykład sytuacji, w której dzięki interfejsowi Address Validation API otrzymasz bezpośrednią opinię, gdy adres nie istnieje.

Zrozumienie odpowiedzi interfejsu Address Validation API

Istnieje już świetna dokumentacja, która wyjaśnia, jak interpretować odpowiedzi z interfejsu Address Validation API, więc nie będziemy tu omawiać dalszych szczegółów.

• Omówienie obiektu odpowiedzi znajdziesz tutaj.
• Demonstracja ilustrująca różne komponenty odpowiedzi jest dostępna tutaj
• W dokumencie dotyczącym weryfikacji adresu na potrzeby płatności znajdziesz szczegółowy opis odróżniania prawidłowych i nieprawidłowych adresów.

Sprawdzone metody

Określanie położenia geograficznego

Podczas wywoływania interfejsów API weryfikacji adresów lub geokodowania warto ograniczyć obszar geograficzny, w którym można wyszukiwać dany adres. Oba interfejsy API implementują to działanie na 2 sposoby:

• Geocoding API – promowanie według regionu

  Jeśli wiesz, że geokody będą znajdować się w określonym kraju, uzyskasz znacznie lepsze wyniki, używając promowania regionu. Jeśli na przykład działasz w obszarze geokodowania w Kanadzie, zalecamy dodanie do żądań pola &region=ca, aby kierować reklamy na Kanadę. Uwaga: promowanie według regionu preferuje tylko wyniki z tego regionu. Możesz nadal uzyskiwać wyniki spoza regionu.

• Adres API do weryfikacji adresów – kod regionu

  W podobny sposób interfejs Address Validation API generuje dokładniejsze wyniki, jeśli w żądaniu zostanie przekazany kod ISO2, wykorzystując pole regionCode.

Identyfikatory miejsc przechowywania

Aby w przyszłości przechowywać informacje o lokalizacji z Google Maps Platform, możesz zapisywać identyfikator miejsca bezterminowo w bazie danych jako atrybut lokalizacji. Żądanie Znajdź miejsce należy wysłać tylko raz dla każdego identyfikatora miejsca. Możesz też wyszukiwać identyfikator miejsca za każdym razem, gdy użytkownik poprosi o szczegóły transakcji.

Aby zapewnić Ci zawsze aktualne informacje, odświeżaj identyfikatory miejsc co 12 miesięcy, używając żądania Szczegóły miejsca z parametrem place_id.

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

Podsumowanie

W tym dokumencie opisujemy główne różnice między interfejsami API do weryfikacji adresów i geokodowania. Podsumowując, rozważ użycie interfejsu Address Validation API, gdy:

• Wymagany jest dokładny adres pocztowy, zwłaszcza ze względu na możliwość dostarczenia przesyłki.
• Wiadomo, że dane wejściowe są niskiej jakości. Interfejs Address Validation API pomija błędy w danych wejściowych, wyróżnia niemożliwe do zweryfikowania komponenty adresu i wprowadza poprawki w danych wejściowych.
• W przypadku adresu konieczne jest podanie dodatkowych informacji, takich jak numer mieszkalny lub komercyjny (dostępne w wybranych regionach).

Dalsze kroki

Pobierz dokument Usprawnij proces płatności, dostawy i operacji dzięki niezawodnym adresom i obejrzyj webinar Usprawnianie procesu płatności, dostawy i działań dzięki weryfikacji adresów .

Sugerujemy dodatkowe artykuły:

• Weryfikacja adresu na potrzeby płatności e-commerce
• Dokumentacja autouzupełniania miejsc
• Dokumentacja interfejsu Address Validation API
• Raportowanie w Google Maps Platform

Współtwórcy

Ten artykuł jest prowadzony przez Google. Poniżsi współtwórcy są autorami tych treści.

Główni autorzy:

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

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

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