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

Cel

Często zdarza się, że potrzebna jest weryfikacja lokalizacji miejsca. W Google Maps Platform dostępnych jest kilka usług, które mogą Ci w tym pomóc. Ten dokument pomoże Ci wybrać jedną z 2 głównych usług weryfikacji lokalizacji – interfejsu Address Verificationation API lub interfejsu Geocoding API.

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

Geokodowanie za pomocą interfejsu API geocoding polega na przekształcaniu adresów na współrzędne geograficzne, których możesz użyć do umieszczania znaczników na mapie lub w określonych miejscach na mapie.

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

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

Address-Validation-vs-Geocoding

Uwagi na temat powyższego schematu blokowego:

  • Przypadek użycia związany z interakcją 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 API języka JavaScript, odpowiedni do integracji z interfejsami użytkownika.
  • Być może już wiesz, że występują problemy z jakością danych w Twoich dotychczasowych adresach. Jeśli potrzebujesz po prostu kodów geograficznych, zalecamy uruchomienie tych lokalizacji za pomocą interfejsu Address Billingation API, aby poprawić zbiory danych.

Jest wiele sytuacji, w których na podstawie podanego wyżej schematu decyzyjnego możesz zdecydować się na korzystanie z jednej usługi zamiast drugiej. Jednak w innych sytuacjach do osiągnięcia celów mogą jednak wymagać używania obu tych usług.

Możesz zdecydować się na użycie interfejsu Address Verificationation API zamiast Geocoding API, gdy:

  • Istnieje duże prawdopodobieństwo pojawienia się podejrzanych danych oraz sytuacji, w których uzyskanie nieprawidłowego adresu może mieć negatywny wpływ na pobieranie. Dzieje się tak, ponieważ interfejs Address Review API dostarcza więcej informacji zwrotnych o tym, dlaczego dane wejściowe nie uzyskały wyniku o dużej 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.
  • Region docelowy zwraca więcej metadanych z interfejsu Address Verification API niż z interfejsu Geocoding API, na przykład klasyfikując typ budynku jako mieszkalny i komercyjny.

Możesz zdecydować się na użycie geokodowania przez interfejs API weryfikacji adresów, gdy:

  • Twoim głównym celem jest uzyskanie informacji o lokalizacji adresu, a dokładność poszczególnych adresów może nie być niezbędna.
    • np. do wygenerowania mapy termicznej na podstawie dużego zbioru danych.
  • Potrzebujesz rozwiązania globalnego, a interfejs Address Review API nie jest dostępny we wszystkich regionach docelowych.

Poniżej znajdziesz kilka przykładów obrazujących funkcje interfejsu Address Verificationation API w porównaniu z interfejsem Geocoding API.

Przykład nieprawidłowego adresu

1 Fake St, Mountain View, CA 94043, USA

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

Nie istnieje w Mountain View w Kalifornii w Kalifornii, a interfejs Address Billingation API odzwierciedla to w szczegółach zwróconych komponentów:

{
  "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 przeciwko Fake St, interfejs API ustalił, że dana ulica może mieć taką nazwę, ale nie można jej dopasować do pomocniczych danych adresowych.

Na podstawie wyniku interfejsu API można wywnioskować, że błąd jest związany z elementem dotyczącym ulicy w tych danych wejściowych (Fake St).

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

alt_text

W efekcie powstaje geokod całego stanu z minimalnymi informacjami na temat tego, które komponenty danych wejściowych są potencjalnie uszkodzone.

Przykład błędu w 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 rejonie.

Zarówno interfejs Address Verificationation, jak i Geocoding API może naprawić te błędy i osiągnąć wynik 76 Buckingham Palace Road, London, SW1W 9TQ. Więcej informacji o tym procesie może jednak uzyskać interfejs Address Verificationation API.

Spójrz na jeden z komponentów adresu z błędną pisownią podczas wpisywania:

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

Interfejs Address Verification API zwraca flagę informującą o wprowadzeniu korekty w polu. Na podstawie tego oznaczenia można zaimplementować logikę biznesową, aby dokładnie sprawdzić poprawkę u dostawcy danych (np. klienta w procesie płatności e-commerce).

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

Bollschestraße 86, 12587, DE

Powyższy adres zawiera błąd pisowni w nazwie ulicy i nie zawiera nazwy Berlina.

Interfejs Address Validation API jest w stanie naprawić oba te błędy i zwraca geokod poziomu PREMISE oraz adres zweryfikowany na poziomie PREMISE:

Bölschestraße 86, 12587 Berlin, DE

W tym przypadku interfejs Geocoding API nie jest w stanie pokonać błędów wejściowych i zwraca wynik ZERO_RESULTS.

Przykład dodatkowych metadanych adresu

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

Ten adres jest prawidłowy, poza numerem lokalu (Ste 123), którego nie ma w budynku.

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

nieruchomości:

"business": true

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

"dpvConfirmation": "S"

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

Interfejs Geocoding API nie może udostępnić 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 informacji o podanym adresie.

Działanie interfejsu Geocoding API polega na interpretowaniu komponentów adresu w hierarchii.

Na przykład zapis 123 Example Street, Chicago, 60007, USA ma następującą kolejność:

/ Example Street/ Chicago/ 60007/ USA zostaną rozpatrzone w takiej kolejności. Pierwszym dopasowaniem w tym przypadku jest Chicago, a dokładniej kod pocztowy 60007. W związku z tym zwraca następujący identyfikator miejsca dla tego kodu pocztowego:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

Odpowiedź interfejsu Geocode API zawiera te informacje:

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

Interfejs Geocoding API może potwierdzić rodzaj miejsca, do którego należy ten adres. Listę adresów types zwróconych przez interfejs Geocoding API znajdziesz tutaj.

Jeśli żaden ze składników danych wejściowych nie zostanie rozpoznany, interfejs API zwróci taką odpowiedź:

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

Prośba z samym adresem domu bez numeru domu zwraca wynik w formularzu:

"types": [
  "route"
]

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

Uwaga: aby sprawdzić, czy adres istnieje, sprawdź, czy w odpowiedzi interfejsu Geocoding API jest ustawiony jakikolwiek parametr (np. types, partial_match, results, status)). Spowoduje to stopniowe zwiększenie poziomu pewności, że adres istnieje, ale nie spowoduje, że będzie on w 100% dokładny. Dlatego potrzebujemy interfejsu Address Verificationation API.

Możesz korzystać z technik opisanych powyżej, aby zwiększyć dokładność adresów na podstawie samej odpowiedzi interfejsu Geocoding API. Jednak w przeciwieństwie do wyniku interfejsu Address Billingation API, interfejs Geocoding API nie zwraca dokładnej informacji zwrotnej w celu określenia dokładności wyniku.

Typ lokalizacji

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

  • Parametr ROOFTOP wskazuje, że wynik to dokładny geokod, w przypadku którego mamy dane o lokalizacji z dokładnością aż do precyzyjnego adresu.
  • RANGE_INTERPOLATED oznacza, że zwrócony wynik odzwierciedla wartości przybliżone (zwykle na drodze) interpolowane między 2 precyzyjnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy geokody dachowe są niedostępne dla adresu.
  • GEOMETRIC_CENTER wskazuje, że zwrócony wynik jest geometrycznym środkiem 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 flagę partial_match ustawioną na true, może to być nadal dobry wynik.

Ten rodzaj fałszywego dopasowania jest bardzo trudny do rozwiązania za pomocą interfejsu Geocoding API. Rozważ wprowadzenie podstawowej weryfikacji danych po przetwarzaniu w kraju i miejscu, z którego pochodzi żądanie lub odpowiedź. Co więcej, warto porównać rzeczywiste adresy pocztowe pod kątem błędów pisowni i/lub niepełnych adresów.

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

Dopasowanie częściowe i fałszywe

Jeśli adres pasuje częściowe, czyli interfejs Geocoding API nie mógł dokładnie zidentyfikować adresu, odpowiedź zawiera:

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

Jeszcze ważniejsze niż typy lokalizacji opisane powyżej jest uwzględnienie, kiedy partial_match = true zawiera odpowiedź. partial_match wskazuje, że interfejs Geocoding API nie zwrócił dokładnego dopasowania do pierwotnego żądania, chociaż udało się dopasować część żądanego adresu.

Warto sprawdzić pierwotne żądanie pod kątem niepełnego adresu. Dopasowania częściowe występują najczęściej w przypadku adresów, które nie istnieją w rejonie określonym w żądaniu. Częściowo pasujące mogą być też zwracane, gdy żądanie odpowiada co najmniej 2 lokalizacji w tej samej okolicy.

Na przykład „21 Henr St, Bristol, UK” zwraca częściowe dopasowanie zarówno dla ulicy Henryka, jak i tej samej. Pamiętaj, że jeśli żądanie zawiera nieprawidłowo zapisany komponent adresu, interfejs Geocoding API może zasugerować adres alternatywny. Sugestie wygenerowane w ten sposób nie zostaną oznaczone jako dopasowania 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 tę właściwość: geometry.location_type=APPROXIMATE.

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

Uwaga: to kolejny przykład, w którym interfejs Address Review API pozwala uzyskać bezpośrednią opinię, gdy adres nie istnieje.

Interpretowanie odpowiedzi interfejsu Address Review API

Istnieje już świetna dokumentacja, w której wyjaśniamy, jak interpretować odpowiedzi z interfejsu Address Verificationation API. Nie będziemy tu zagłębiać się w szczegóły.

Sprawdzone metody

Określanie położenia geograficznego

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

  • Geocoding API – promowanie według regionu

    Jeśli wiesz, że geokody będą znajdować się w określonym kraju, znacznie lepsze wyniki uzyskasz, używając promowania regionu. Jeśli na przykład przeprowadzasz geokodowanie w Kanadzie, zalecamy dodanie do żądań atrybutu &region=ca, by informacje o Kanadzie były traktowane jako odchylenia od normy. Pamiętaj, że promowanie według regionu preferuje wyniki tylko z tego regionu. Nadal możesz uzyskiwać wyniki poza regionem.

  • Adres walidacji adresów – kod regionu

    W podobny sposób interfejs Address Review API pozwala uzyskać 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 zapisać identyfikator miejsca na czas nieokreślony w bazie danych jako atrybut lokalizacji. Żądanie Znajdź miejsce wystarczy wysłać tylko raz dla każdego identyfikatora miejsca. Możesz też wyszukiwać identyfikator miejsca za każdym razem, gdy użytkownik prosi o szczegóły transakcji.

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

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

Podsumowanie

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

  • Wymagany jest dokładny adres pocztowy, zwłaszcza w celu dostarczenia.
  • Wiadomo, że dane wejściowe są niskiej jakości. Interfejs Address Verification API lepiej sprawdza się w przypadku błędów w danych wejściowych, wyróżnia elementy adresu, których nie można zweryfikować, i wprowadza poprawki w danych wejściowych.
  • W przypadku adresu, na przykład do domu lub do użytku komercyjnego, wymagane jest podanie dodatkowych informacji (opcja dostępna w wybranych regionach).

Dalsze kroki

Pobierz dokument Usprawnij proces płatności, dostawy i operacji dzięki wiarygodnym adresom i obejrzyj webinar Jak usprawnić proces płatności, dostawy i operacji dzięki weryfikacji adresu .

Sugerowana dalsza analiza:

Współtwórcy

Google przechowuje ten artykuł. Następujący współtwórcy napisali go pierwotnie.

Główne autorzy:

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

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

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