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 Address Validation API to usługa Google Maps Platform, która pomaga klientom sprawdzić, czy adres jest prawidłowy.

Geokodowanie za pomocą interfejsu Geocoding API to proces konwertowania adresów na współrzędne geograficzne, które można wykorzystać do umieszczania znaczników na mapie lub do określania położenia na mapie.

Ogólny przegląd różnic między interfejsami API weryfikacji adresów a Geokodowania znajdziesz tutaj.

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

Kiedy wybrać interfejs API weryfikacji adresów, 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 Address Validation API, aby poprawić zbiory danych.

Na podstawie poniższego schematu decyzyjnego możesz wybrać jedną usługę zamiast drugiej w wielu sytuacjach. 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że prawdopodobieństwo, że dane są wątpliwe lub że podanie nieprawidłowego adresu będzie miało negatywny wpływ na dalsze działania; 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.

Interfejs Geocoding API może być przydatny w przypadku:

• Twoim głównym celem jest pobranie lokalizacji adresu, a dokładność poszczególnych adresów może nie być kluczowa.
  • Na przykład do generowania mapy ciepła na podstawie dużego zbioru danych.
• Potrzebujesz globalnego rozwiązania, 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"
 }

W tym przypadku ważną właściwością do sprawdzenia 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).

Używając tego samego adresu z interfejsem Geocoding API, można dopasować „Kalifornię”, 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 weryfikacji adresu, jak i interfejs API geokodowania mogą poprawić te błędy i osiągnąć wynik 76 Buckingham Palace Road, London, SW1W 9TQ. Więcej informacji o tym procesie znajdziesz jednak w interfejsie Address Validation API.

Sprawdź jeden z elementów adresu, w którym występuje błąd pisowni:

{
  "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ę. Z tym flagiem można zaimplementować logikę biznesową, aby podwójnie sprawdzić poprawkę u dostawcy danych, np. u klienta podczas płatności w sklepie internetowym.

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 wartość 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.

Interpretowanie odpowiedzi 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 on następujący identyfikator 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 elementów danych wejściowych nie zostanie rozwiązany, interfejs API zwróci:

{
   "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)). Dzięki temu stopniowo zwiększysz poziom pewności, że adres istnieje, ale nie 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, które pozwoliłyby określić dokładność wyników.

Typ lokalizacji

Aby dobrze zrozumieć tę sekcję, musisz wiedzieć, jakie typy lokalizacji mogą zostać zwrócone w odpowiedzi interfejsu Geocoding API:

• ROOFTOP oznacza, że zwrócony wynik to dokładny geokod, dla którego mamy informacje o lokalizacji dokładne do adresu ulicy.
• 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 location_type ROOFTOP lub RANGE_INTERPOLATED, nie oznacza to, że adres istnieje. Podobnie, jeśli interfejs Geocoding API zwraca 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. Możesz też porównać adresy ulic, aby sprawdzić, czy nie ma w nich literówek lub czy nie są niekompletne.

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"
         ]

Ważniejsze niż wymienione powyżej typy lokalizacji jest uwzględnienie w odpowiedzi wartości 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ęść adresu.

Warto sprawdzić pierwotną prośbę, aby sprawdzić, czy adres jest niekompletny. Dopasowania częściowe występują najczęściej w przypadku adresów ulic, które nie istnieją w miejscowości określonej w żądaniu. W przypadku częściowego dopasowania może zostać zwrócona lista lokalizacji, które pasują do żądania w ramach tej samej lokalizacji.

Na przykład „21 Henr St, Bristol, UK” zwraca dopasowanie częściowe zarówno do Henry Street, jak i do Henrietta Street. Pamiętaj, że jeśli żądanie zawiera niepoprawnie zapisany element adresu, Geocoding API może zaproponować alternatywny 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 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 właściwość: geometry.location_type=APPROXIMATE.

Jeśli w odpowiedzi pojawią się takie wskaźniki, oznacz adres wejściowy jako nieprawidłowy i spróbuj ponownie go zweryfikować za pomocą innego sposobu.

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

Interpretowanie odpowiedzi interfejsu Address Validation API

W dokumentacji znajdziesz już szczegółowe informacje o interpretowaniu odpowiedzi z interfejsu Address Validation API, więc nie będziemy tutaj podawać więcej szczegółów.

• Omówienie obiektu odpowiedzi znajdziesz tutaj.
• Demo, które pokazuje różne elementy odpowiedzi, znajdziesz 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 – uwzględnianie 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 przechowywać informacje o lokalizacji z Google Maps Platform na potrzeby przyszłych żądań, możesz zapisać identyfikator miejsca na stałe w swojej 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 ze względu na możliwość dostarczenia.
• Dane wejściowe są niskiej jakości. Interfejs Address Validation API jest bardziej tolerancyjny wobec błędów danych wejściowych, będzie wyróżniać nieweryfikowalne elementy 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 adresów w procesie płatności e-commerce
• Dokumentacja autouzupełniania miejsc
• Dokumentacja interfejsu Address Validation API
• Raporty Google Maps Platform

Współtwórcy

Google jest autorem tego artykułu. 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ń