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. Ten dokument pomoże Ci wybrać jedną z 2 głównych usług weryfikacji lokalizacji: interfejs API weryfikacji adresów lub interfejs API kodowania adresów.

Interfejs API weryfikacji adresu to usługa platformy Mapy Google, 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 pozycji na mapie.

Ogólny przegląd różnic między interfejsami API weryfikacji adresu i geokodowania znajdziesz tutaj.

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

Kiedy wybrać usługę Walidacja adresu, a kiedy Geokodowanie API

Uwagi dotyczące poniższego schematu przepływu danych:

• Przypadek użycia interakcji z użytkownikiem odnosi się do sytuacji, gdy użytkownik jest obecny i interaguje się z wynikami.
• Autocomplete Places to interfejs API JavaScript, 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 kody geograficzne, zalecamy użycie interfejsu API weryfikacji adresów, aby poprawić zbiory danych.

Na podstawie powyższego drzewka decyzyjnego możesz w wielu sytuacjach wybrać jeden produkt zamiast drugiego. W innych sytuacjach do realizacji swoich celów możesz jednak potrzebować obu tych usług.

Zamiast interfejsu Geocoding API możesz użyć interfejsu Address Validation 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 dane wejściowe nie uzyskały wysokiej dokładności.
• Musisz poprawić dane wejściowe użytkownika (np. błędy ortograficzne lub brakujące pola), co zwiększa prawdopodobieństwo uzyskania prawidłowego wyniku.
• Twój region docelowy zwraca więcej metadanych z interfejsu Address Validation API niż z interfejsu Geocoding API, np. klasyfikację typu budynku jako mieszkalnego lub komercyjnego.

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

• Twoim głównym celem jest pobranie lokalizacji adresu, a dokładność poszczególnych adresów może nie być kluczowa.
  • Na przykład do wygenerowania mapy ciepła na podstawie dużego zbioru danych.
• Potrzebujesz rozwiązania globalnego, a interfejs API weryfikacji adresu jest niedostępny w niektórych 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 weryfikacji adresu dzieli te dane na poszczególne elementy adresu (ulica, miasto, województwo itp.). Może też szczegółowo informować, 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 informacjach o zwróconym komponencie:

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

Ważną właściwością do sprawdzenia 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.

Na podstawie wyniku interfejsu API można stwierdzić, że problem dotyczy elementu ulicy w tym adresie (Fake St).

Używając tego samego adresu w ramach interfejsu 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 pisowni

76 Buckingham 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 weryfikacji adresów, jak i interfejs API geokodowania mogą poprawić te błędy i otrzymać wynik 76 Buckingham Palace Road, London, SW1W 9TQ. Więcej informacji o tym procesie można jednak uzyskać z interfejsu Address Validation API.

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

{
  "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 e-sklepie.

Przykład błędu związanego z brakiem danych i błędem pisowniowym

Bollschestraße 86, 12587, DE

W powyższym adresie występuje błąd ortograficzny w nazwie ulicy i brak 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 zweryfikowany na poziomie PREMISE:

Bölschestraße 86, 12587 Berlin, DE

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

Przykład dodatkowych metadanych adresu

111 8th Avenue Ste 123, New York, NY 10011-5201, USA

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

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

obiekt:

"business": true

Dodatkowo wartość dpvConfirmation zwracana w ramach 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 interfejsu Geocoding API

Omówienie

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

Interfejs Geocoding API działa poprzez 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 w tej kolejności. W tym przypadku pierwszym dopasowaniem jest Chicago, a dokładniej kod pocztowy 60007. W związku z tym zwraca 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 zwraca:

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

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

"types": [
  "route"
]

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

Uwaga: aby sprawdzić, czy adres istnieje, sprawdź, czy w odpowiedzi Geokodowania API ustawione są jakiekolwiek parametry (takie jak types, 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ą tych metod możesz zwiększyć pewność co do dokładności adresu na podstawie odpowiedzi interfejsu Geocoding API. Jednak w odróżnieniu od interfejsu API do weryfikacji adresów interfejs Geocoding API nie zwraca dokładnych informacji zwrotnych, 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 z dokładnością 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ą zwykle zwracane, gdy geokody dachów są niedostępne dla adresu ulicznego.
• GEOMETRIC_CENTER wskazuje, że zwrócony wynik to geometryczny środek wyniku, np. łamany (np. ulica) lub wielokąt (region).
• APPROXIMATE (PRZYBLIŻONY) 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ć nadal odpowiedni wynik.

Ten typ fałszywego dopasowania jest bardzo trudnym problemem do rozwiązania za pomocą interfejsu Geocoding API. Warto przynajmniej wdrożyć podstawowe weryfikowanie kraju i miejscowości w ramach przetwarzania wstępnego. Co więcej, warto 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 fałszywe

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

Jeszcze ważniejsze niż wymienione wyż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ęść żądanego adresu.

Warto sprawdzić pierwotną prośbę, aby zobaczyć, czy zawiera ona niepełny adres. Dopasowania częściowe występują najczęściej w przypadku adresów ulic, które nie występują w miejscowości określonej w żądaniu. W przypadku częściowego dopasowania może zostać zwrócony wynik, gdy żądanie pasuje do co najmniej 2 lokalizacji w tej samej miejscowości.

Na przykład „21 Henr St, Bristol, UK” zwraca częściowe dopasowanie do ulicy Henry Street i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera niepoprawnie zapisany element adresu, interfejs Geocoding API może zasugerować alternatywny adres. W ten sposób wywoływane sugestie nie będą oznaczane jako dopasowanie częściowe.

Adresy syntetyczne

Interfejs API geokodowania 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 następującą właściwość: geometry.location_type=APPROXIMATE.

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

Uwaga: to kolejny przykład, w którym interfejs API weryfikacji adresów umożliwia uzyskanie bezpośredniej informacji o nieistniejącym adresie.

Odpowiedź interfejsu Address Validation API

Istnieje już obszerna dokumentacja dotycząca interpretacji odpowiedzi 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 dotyczącej 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 różne sposoby:

• Geocoding API – uwzględnianie regionu

  Jeśli wiesz, że geokody będą się znajdować w określonym kraju, możesz uzyskać znacznie lepsze wyniki, stosując ustawienie Regionu docelowego. 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 jednak uzyskać wyniki spoza regionu.

• Interfejs API weryfikacji adresów – 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 Platformy Map Google na potrzeby przyszłych zapytań, 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

Ten dokument opisuje główne różnice między interfejsami API 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 API weryfikacji adresów jest bardziej tolerancyjny wobec błędów danych wejściowych, podświetla nieweryfikowalne elementy adresu i wprowadza poprawki w danych wejściowych.
• W przypadku adresu wymagane są dodatkowe informacje, np. czy jest to adres do celów mieszkalnych czy komercyjnych (dostępne w wybranych regionach).

Następne kroki

Pobierz białą księgę Ulepszenie procesu płatności, dostawy i działalności dzięki wiarygodnym adresom oraz obejrzyj webinar Ulepszenie procesu płatności, dostawy i działalności dzięki walidacji adresów .

Sugerowane artykuły:

• Weryfikacja adresu 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ń