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

Cel

Często musisz weryfikować 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: interfejs API weryfikacji adresów lub interfejs API geokodowania.

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

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ólny opis 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ć interfejs Address Validation API, a kiedy Geocoding API

Uwagi dotyczące powyższego schematu blokowego:

• Przypadek użycia interakcji z użytkownikiem odnosi się do sytuacji, gdy użytkownik jest obecny i wchodzi w interakcję z wynikami.
• Autouzupełnianie miejsc to interfejs JavaScript API, który nadaje się do integracji z interfejsami użytkownika.
• Możesz mieć świadomość problemów z jakością danych w dotychczasowych adresach. Chociaż interesują Cię tylko geokody, zalecamy użycie interfejsu API weryfikacji adresów, aby poprawić zbiory danych.

Biorąc pod uwagę powyższe schematy decyzyjne, jest wiele sytuacji, w których możesz zdecydować się na używanie jednej usługi zamiast drugiej. W innych sytuacjach do osiągnięcia celów może być potrzebne użycie obu usług.

Interfejs Address Validation API może być przydatny zamiast Geocoding API, gdy:

• Istnieje duża szansa, że otrzymasz wątpliwe dane, lub gdy uzyskanie nieprawidłowego adresu będzie mieć negatywny wpływ na dalszą pracę. Dzieje się tak, ponieważ interfejs Address Validation API udostępnia więcej informacji o tym, dlaczego podany adres nie został zweryfikowany z wysoką dokładnością.
• Musisz poprawić dane wejściowe użytkownika (np. poprawić błędy ortograficzne lub uzupełnić brakujące pola), co zwiększa prawdopodobieństwo uzyskania prawidłowego wyniku.
• W porównaniu z interfejsem Geocoding API Twój region docelowy zwraca więcej metadanych z interfejsu Address Validation API, np. klasyfikację typu budynku jako mieszkalnego lub komercyjnego.

Możesz użyć Geokodowania zamiast interfejsu API weryfikacji adresu, 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ą na podstawie dużego zbioru danych.
• Potrzebujesz rozwiązania globalnego, a interfejs API weryfikacji adresu jest niedostę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 Address Validation API dzieli te dane na poszczególne elementy 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 nie istnieje w Mountain View w Kalifornii, a interfejs Address Validation API odzwierciedla to w zwróconych szczegółach 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 UNCONFIRMED_BUT_PLAUSIBLE w przypadku Fake St, interfejs API stwierdził, że ulica może mieć taką nazwę, ale nie można jej dopasować do danych adresu.

Z wyniku interfejsu API można wywnioskować, że winny jest element ulicy w tym wejściu (Fake St).

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:

Wynikiem jest jednak geokod całego stanu z minimalną informacją o tym, które komponenty danych wejściowych mogły być wadliwe.

Przykład błędu ortograficznego

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

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

Zarówno interfejs API do weryfikacji adresów, jak i interfejs 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 znajdziesz jednak w interfejsie Address Validation API.

Sprawdź jeden z elementów adresu, który został wpisany z błędem:

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

Interfejs API weryfikacji adresu zwraca flagę, która wskazuje, ż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 błędu dotyczącego braku danych i błędu pisowni

Bollschestraße 86, 12587, DE

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

Interfejs API weryfikacji adresów może naprawić oba te błędy i zwraca kod geograficzny na poziomie PREMISE oraz adres, który jest weryfikowany na poziomie PREMISE:

Bölschestraße 86, 12587 Berlin, DE

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

Przykład dodatkowych metadanych adresu

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

Adres jest prawidłowy, z wyjątkiem numeru mieszkania (123), którego nie ma w budynku.

Interfejs API weryfikacji adresu może zweryfikować adres PREMISE (111 8th Ave) i podać niektóre metadane dotyczące obiektu, w tym informację, że jest to budynek komercyjny.

premises:

"business": true

Dodatkowo wartość dpvConfirmation zwracana w ramach elementu uspsData w odpowiedzi to S:

"dpvConfirmation": "S"

Wartość dpvConfirmation S oznacza, że adres jest weryfikowany na poziomie PREMISE, ale podany w danych numer jednostki nie jest powiązany z tym adresem.

Interfejs Geocoding API nie może podać tych informacji.

Zrozumienie odpowiedzi interfejsu Geocoding API

Omówienie

Jeśli używasz interfejsu Geocoding API, wynik geokodowania zawiera w odpowiedzi różne wskazówki, które można wykorzystać do zrozumienia szczegółów podanego adresu.

Interfejs Geocoding API działa przez rozwiązywanie elementów adresu w hierarchii.

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

/ Example Street/ Chicago/ 60007/ USA będą oceniane w tej kolejności. W tym przypadku pierwsze dopasowanie to 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 dany adres. Listę adresów types zwróconych przez interfejs Geocoding API znajdziesz tutaj.

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

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

Przesłanie żądania z tylko adresem ulicy bez numeru budynku spowoduje zwrócenie wyniku w formie:

"types": [
  "route"
]

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

Uwaga: aby sprawdzić, czy adres istnieje, sprawdź, czy w odpowiedzi interfejsu Geocoding API ustawiono któryś z parametrów (takich jak types czy partial_match, results, status)). Spowoduje to stopniowe zwiększenie poziomu ufności, że adres może istnieć, ale nie sprawi, że będzie on w 100% dokładny. Dlatego potrzebujemy interfejsu Address Validation API.

Za pomocą powyższych metod możesz zwiększyć pewność co do dokładności adresu na podstawie odpowiedzi interfejsu Geocoding API. Jednak w przeciwieństwie do interfejsu Address Validation API interfejs Geocoding API nie zwraca dokładnych informacji zwrotnych, które pozwoliłyby 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żenie (zwykle na drodze) interpolowane między 2 dokładnymi punktami (np. skrzyżowaniami). Interpolowane wyniki są zwracane, gdy kody geolokalizacji na dachu budynku są niedostępne dla adresu ulicznego.
• GEOMETRIC_CENTER wskazuje, że zwrócony wynik to środek geometryczny wyniku, np. łamany (np. ulica) lub wielokąt (region).
• APPROXIMATE oznacza, że zwrócony wynik nie jest żadnym z wymienionych powyżej.

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

Ten typ fałszywego dopasowania jest bardzo trudnym problemem do rozwiązania za pomocą Geocoding API. Warto przynajmniej wdrożyć podstawowe weryfikowanie kraju i miejscowości w ramach przetwarzania wstępnego. 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ę użyć interfejsu Geocoding API, zalecamy regularne sprawdzanie jakości danych między początkowym żądaniem a odpowiedzią interfejsu Geocoding API.

Dopasowanie częściowe i nieprawidłowe

Jeśli adres jest częściowo zgodny, co oznacza, że interfejs Geocoding API nie mógł 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. partial_match oznacza, że interfejs Geocoding API nie zwrócił dokładnego dopasowania do pierwotnego żądania, ale udało mu się dopasować część adresu.

Sprawdź, czy pierwotne żądanie zawiera niepełne adresy. Zgodności częściowe występują najczęściej w przypadku adresów ulic, które nie istnieją w miejscowości określonej 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. W ten sposób wywoływane sugestie nie będą oznaczane jako dopasowanie częściowe.

Adresy syntetyczne

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 przypadkach obiekt odpowiedzi często zawiera długi identyfikator miejsca i właściwość: geometry.location_type=APPROXIMATE.

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

Uwaga: to kolejny przykład, w którym interfejs Address Validation API zapewnia bezpośrednie informacje o nieistniejącym adresie.

Interpretowanie odpowiedzi interfejsu Address Validation API

Istnieje już obszerna dokumentacja dotycząca interpretacji odpowiedzi z interfejsu Address Validation API, więc nie będziemy tutaj podawać więcej szczegółów.

• Omówienie obiektu odpowiedzi znajdziesz tutaj.
• Demonstracja ilustrująca różne komponenty odpowiedzi jest dostępna tutaj
• W dokumentacji weryfikacji adresu podczas płatności znajdziesz szczegółowy opis tego, jak odróżnić poprawne adresy od nieprawidłowych.

Sprawdzone metody

Określanie obszaru geograficznego

Podczas wywoływania interfejsów API weryfikacji adresów lub geokodowania zalecamy ograniczenie obszaru geograficznego, w którym ma być wyszukiwany adres. Oba interfejsy API implementują to na 2 sposoby:

• Geocoding API – preferowanie regionu

  Jeśli wiesz, że geokody będą się znajdować w danym kraju, możesz uzyskać znacznie lepsze wyniki, korzystając z ustawienia preferencji regionalnych. Jeśli na przykład wykonujesz geokodowanie w Kanadzie, zalecamy dodanie do żądań parametru &region=ca, aby zwiększyć prawdopodobieństwo uzyskania wyników z Kanady. Pamiętaj, że ustawienie Region Biasing tylko preferuje wyniki z tego regionu. Nadal możesz uzyskiwać wyniki spoza regionu.

• Interfejs Address Validation API – kod regionu

  Podobnie interfejs Address Validation API zapewnia dokładniejsze wyniki, jeśli w żądaniu zostanie przekazany kod ISO2 za pomocą pola regionCode.

Przechowywanie identyfikatorów miejsc

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. Wystarczy wysłać żądanie Znajdź miejsce tylko raz na identyfikator miejsca. Możesz też wyszukać identyfikator miejsca za każdym razem, gdy użytkownik poprosi o szczegóły transakcji.

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

Uwaga: zapoznaj się też ze sprawdzonymi metodami dotyczącymi 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 na potrzeby dostawy.
• 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.
• Wymagane są dodatkowe informacje o adresie, np. czy jest to adres do celów mieszkalnych czy komercyjnych (dostępne w wybranych regionach).

Następne kroki

Pobierz białą księgę Ulepsz proces płatności, dostawy i obsługi dzięki wiarygodnym adresom oraz obejrzyj webinar Ulepsz proces płatności, dostawy i obsługi dzięki weryfikacji adresów .

Sugerowane materiały do dalszego zapoznania się z tematem:

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

Współtwórcy

Ten artykuł jest prowadzony przez Google. Pierwotnie napisali go autorzy wymienieni poniżej.

Główni autorzy:

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

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

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