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

Cel

Często musisz potwierdzać lokalizację miejsca. W Google Maps Platform dostępnych jest kilka różnych 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 Address Validation API i interfejs Geocoding API.

Address Validation API to usługa Google Maps Platform, która pomaga klientom sprawdzać, 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żesz używać do umieszczania znaczników na mapie lub określania pozycji na mapie.

Ogólne informacje o różnicach między interfejsem Address Validation API a Geocoding API znajdziesz tutaj.

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

Kiedy wybrać Address Validation API, a kiedy Geocoding API

Uwagi dotyczące powyższego schematu blokowego:

• Przypadek użycia interakcji użytkownika odnosi się do sytuacji, w której użytkownik jest obecny i może wchodzić w interakcję z wynikami.
• Autouzupełnianie miejsc to interfejs JavaScript API, który można zintegrować z interfejsami użytkownika.
• Możesz mieć świadomość problemów z jakością danych w przypadku dotychczasowych adresów. Dlatego, mimo że możesz potrzebować tylko geokodów, zalecamy uruchomienie tych lokalizacji za pomocą interfejsu Address Validation API, aby poprawić zbiory danych.

Na podstawie powyższego drzewa decyzyjnego możesz w wielu sytuacjach wybrać jeden produkt zamiast drugiego. W innych sytuacjach możesz jednak używać obu tych usług, aby osiągnąć swoje cele.

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ż interfejs Address Validation API dostarcza więcej informacji o tym, dlaczego dane wejściowe nie dał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.
• W przypadku regionu docelowego interfejs Address Validation API zwraca więcej metadanych niż interfejs Geocoding API, np. klasyfikację typu budynku jako mieszkalny lub komercyjny.

Możesz użyć interfejsu 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że to być np. generowanie mapy cieplnej 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 przykłady, 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 dane wejściowe na poszczególne komponenty adresu (ulica, miasto, stan itp.). Może też przekazywać 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 interfejs Address Validation API odzwierciedla to w szczegółach zwróconych 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 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 adresowych.

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

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

Wynikiem jest jednak geokod całego stanu, a informacje zwrotne dotyczące potencjalnie wadliwych komponentów danych wejściowych są minimalne.

Przykład błędu w pisowni

76 Buckingamm Palace Road, Londn, 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 potrafią poprawić te błędy i uzyskać wynik 76 Buckingham Palace Road, London, SW1W 9TQ. Więcej informacji o tym procesie znajdziesz w dokumentacji interfejsu Address Validation API.

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ę. W odniesieniu do tego sygnału można wdrożyć logikę biznesową, aby dwukrotnie sprawdzić korektę u dostawcy danych, np. u klienta podczas płatności w sklepie internetowym.

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

Bollschestraße 86, 12587, DE

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

Interfejs Address Validation API może naprawić oba te błędy i zwraca 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 poradzić sobie z błędami w danych wejściowych i zwraca wynik ZERO_RESULTS.

Przykład dodatkowych metadanych adresu

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

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

Interfejs Address Validation API może zweryfikować adres PREMISE (111 8th Ave) i podać metadane dotyczące nieruchomości, w tym informację, że jest to obiekt 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 na poziomie PREMISE, ale numer lokalu podany w danych wejściowych nie jest powiązany z tym adresem.

Interfejs 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 można wykorzystać do zrozumienia szczegółów podanego adresu.

Interfejs Geocoding API działa poprzez rozwiązywanie 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ędą oceniane w tej kolejności. W tym przypadku pierwszym dopasowaniem jest Chicago, a dokładniej 60007 kod pocztowy. Dlatego zwraca następujący identyfikator miejsca 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 zwracanych przez interfejs Geocoding API znajdziesz tutaj.

Jeśli żaden z komponentów danych wejściowych nie zostanie rozpoznany, interfejs API zwróci:

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

Wysłanie żądania z samym adresem ulicy bez numeru domu zwraca wynik w postaci:

"types": [
  "route"
]

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

Uwaga: aby sprawdzić, czy adres istnieje, sprawdź, czy w odpowiedzi interfejsu Geocoding API ustawiono którykolwiek z parametrów (np. types, partial_match, results, status)). Stopniowo zwiększy to poziom pewnoś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. W przeciwieństwie do interfejsu Address Validation API, 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 oznacza, że zwrócony wynik to dokładny geokod, dla którego mamy informacje o lokalizacji o dokładności adresu.
• RANGE_INTERPOLATED oznacza, że zwrócony wynik odzwierciedla przybliżenie (zwykle na drodze) interpolowane między 2 precyzyjnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy w przypadku adresu ulicy nie są dostępne geokody dachu.
• GEOMETRIC_CENTER oznacza, ż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 wartość location_type równą 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ć nadal odpowiedni 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 w odniesieniu do kraju i lokalizacji żądania lub odpowiedzi. Jeszcze lepiej będzie porównać rzeczywiste adresy ulic, aby sprawdzić, czy nie ma w nich błędów pisowni lub czy nie są niekompletne.

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 i fałszywe dopasowanie

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

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

Jeszcze ważniejsze niż powyższe typy lokalizacji jest sprawdzenie, kiedy w odpowiedzi występuje partial_match = true. partial_match oznacza, ż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ć pierwotną prośbę, aby dowiedzieć się, czy adres jest niekompletny. 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 dopasowanie częściowe zarówno dla ulicy Henry Street, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera błędnie napisaną część adresu, interfejs Geocoding API może zaproponować adres alternatywny. 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, oznacz adres wejściowy jako nieprawidłowy i spróbuj ponownie go zweryfikować w inny sposób.

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

Interpretowanie odpowiedzi interfejsu Address Validation API

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

• 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 tego, jak odróżnić prawidłowe adresy od nieprawidłowych.

Sprawdzone metody

Określanie obszaru geograficznego

Podczas wywoływania interfejsów API weryfikacji adresu lub geokodowania 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 – Region Biasing

  Jeśli wiesz, że kody geograficzne będą znajdować się w określonym kraju, możesz uzyskać znacznie lepsze wyniki, korzystając z ustawiania preferencji regionalnych. Jeśli na przykład przeprowadzasz geokodowanie w Kanadzie, zalecamy dodanie do żądań parametru &region=ca, aby zwiększyć prawdopodobieństwo uzyskania wyników z tego kraju. Pamiętaj, że funkcja preferowania regionu tylko preferuje wyniki z tego regionu. Nadal możesz otrzymywać wyniki spoza tego regionu.

• Address Validation API – kod regionu

  Podobnie interfejs Address Validation API generuje dokładniejsze wyniki, jeśli w żądaniu zostanie przekazany kod ISO2 przy użyciu 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 swojej bazie danych bezterminowo jako atrybut lokalizacji. Żądanie Find Place (Znajdź miejsce) należy wysyłać tylko raz na każdy 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, wysyłając żądanie Szczegóły miejsca z parametrem place_id.

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

Podsumowanie

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

• Wymagany jest dokładny adres pocztowy, zwłaszcza w celu zapewnienia dostarczalności.
• Dane wejściowe są znane z niskiej jakości. Interfejs Address Validation API jest bardziej tolerancyjny w stosunku do błędów w danych wejściowych, wyróżnia niezweryfikowane komponenty adresu i wprowadza poprawki do danych wejściowych.
• W przypadku adresu wymagane są dodatkowe informacje, np. czy jest to adres prywatny czy firmowy (dostępne w wybranych regionach).

Następne kroki

Pobierz białą księgę na temat usprawniania procesu płatności, dostawy i operacji dzięki wiarygodnym adresom i obejrzyj webinar na temat usprawniania procesu płatności, dostawy i operacji dzięki weryfikacji adresu .

Sugerowane dalsze lektury:

• Weryfikacja adresu podczas płatności w e-commerce
• Dokumentacja usługi Autouzupełnianie miejsc
• Dokumentacja Address Validation API
• Raportowanie w Google Maps Platform

Współtwórcy

Google jest autorem tego artykułu. Oryginalny tekst został napisany przez te osoby.

Główni autorzy:

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

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

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