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

Cel

Często musisz sprawdzić lokalizację miejsca. W Google Maps Platform jest kilka usług, które mogą Ci w tym pomóc. Z tego dokumentu dowiesz się, jak wybrać jedną z 2 głównych usług weryfikacji lokalizacji – Address Validation API i Geocoding API.

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

Geokodowanie za pomocą Geocoding API to proces przekształcania adresów na współrzędne geograficzne, których możesz użyć do umieszczenia znaczników na mapie lub pozycji na mapie.

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

Kiedy wybrać Address Validation API, a kiedy Geocoding API

Address-Validation-vs-Geocoding

Uwagi dotyczące powyższego schematu blokowego:

  • Przypadek użycia interakcji z użytkownikiem 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 JavaScript, dlatego nadaje się do integracji z interfejsami użytkownika.
  • Możesz mieć świadomość problemów z jakością danych w dotychczasowych adresach. Dlatego, chociaż możesz potrzebować tylko geokodów, zalecamy sprawdzenie tych lokalizacji za pomocą Address Validation API, aby poprawić zbiory danych.

W wielu sytuacjach możesz na podstawie powyższego drzewa decyzyjnego wybrać jeden produkt zamiast drugiego. W innych sytuacjach do osiągnięcia celów może być konieczne użycie obu produktów.

Możesz wybrać Address Validation API zamiast Geocoding API, gdy:

  • Istnieje duże prawdopodobieństwo, że dane są wątpliwe lub że nieprawidłowy adres będzie miał negatywny wpływ na dalsze procesy. Dzieje się tak, ponieważ Address Validation API dostarcza więcej informacji o tym, dlaczego dane wejściowe nie otrzymały wyniku o wysokiej precyzji.
  • Musisz poprawić dane wejściowe użytkownika (np. błędy ortograficzne lub brakujące pola), co zwiększa prawdopodobieństwo uzyskania dokładnego wyniku.
  • Twój region docelowy zwraca więcej metadanych z Address Validation API niż z Geocoding API, np. klasyfikację typu budynku jako mieszkalny lub komercyjny.

Możesz wybrać Geocoding API zamiast Address Validation API, gdy:

  • Twoim głównym celem jest pobranie lokalizacji adresu, a dokładność poszczególnych adresów nie jest krytyczna.
    • Możesz na przykład chcieć wygenerować mapę cieplną na podstawie dużego zbioru danych.
  • Potrzebujesz szczegółowych informacji o lokalizacji, takich jak wejścia do budynku, obrysy budynku lub punkty nawigacyjne odbioru i wysiadania (dostępne w metodzie SearchDestinations w Geocoding API w wersji 4).
  • Potrzebujesz rozwiązania globalnego, a Address Validation API nie jest dostępne we wszystkich regionach docelowych.

Oto kilka przykładów, które pokazują możliwości Address Validation API w porównaniu z Geocoding API.

Przykład nieprawidłowego adresu

1 Fake St, Mountain View, CA 94043, USA

Address Validation API dzieli te dane wejściowe na poszczególne komponenty adresu (ulica, miasto, stan itp.). Może też podać 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 Address Validation API odzwierciedla to w zwróconych szczegółach 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 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 wywnioskować, że problem dotyczy komponentu ulicy (Fake St).

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

alt_text

Wynikiem jest jednak geokod całego stanu z minimalnymi informacjami o tym, które komponenty danych wejściowych mogą być nieprawidłowe.

Przykład błędu ortograficznego

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

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

Zarówno Address Validation API, jak i Geocoding API mogą poprawić te błędy i uzyskać wynik 76 Buckingham Palace Road, London, SW1W 9TQ. Address Validation API może jednak podać więcej informacji o tym procesie.

Spójrz na jeden z komponentów adresu, w którym wystąpił błąd ortograficzny:

{
  "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ę. Na podstawie tej flagi można zaimplementować logikę biznesową, aby sprawdzić poprawkę u dostawcy danych, np. u klienta w procesie płatności w e-commerce.

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

Bollschestraße 86, 12587, DE

Powyższy adres zawiera błąd ortograficzny w nazwie ulicy i brakuje w nim miasta (miejscowości) Berlin.

Address Validation API może naprawić oba te błędy i zwrócić geokod na poziomie PREMISE oraz adres, który został zweryfikowany do poziomu PREMISE:

Bölschestraße 86, 12587 Berlin, DE

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

Przykład dodatkowych metadanych adresu

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

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

Address Validation API może zweryfikować adres do poziomu PREMISE (111 8th Ave) i podać metadane dotyczące nieruchomości, w tym informację, że jest to lokal

komercyjny:

"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 do poziomu PREMISE, ale numer lokalu podany w danych wejściowych nie jest powiązany z tym adresem.

Geocoding API nie może podać tych informacji.

Interpretowanie odpowiedzi Geocoding API

Przegląd

Jeśli używasz Geocoding API, wynik geokodu zawiera w odpowiedzi różne wskazówki, które mogą pomóc w zrozumieniu szczegółów podanego adresu.

Geocoding API działa na zasadzie rozwiązywania 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ędzie oceniany w tej kolejności. W tym przypadku pierwszym dopasowaniem jest Chicago, a dokładniej kod pocztowy 60007. Dlatego zwraca on ten identyfikator miejsca dla tego kodu pocztowego:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

Geocode API zawiera w odpowiedzi te informacje:

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

Geocoding API może potwierdzić, do jakiego rodzaju miejsca należy ten adres. Listę adresów types zwracanych przez Geocoding API znajdziesz tutaj.

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

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

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

"types": [
  "route"
]

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

Uwaga: aby sprawdzić, czy adres istnieje, sprawdź, czy w odpowiedzi Geocoding API są ustawione któreś z parametrów (np. types, partial_match, results, status)). Stopniowo zwiększy to poziom pewności, że adres może istnieć, ale nie będzie on w 100% dokładny. Dlatego potrzebujemy Address Validation API.

Za pomocą powyższych metod możesz zwiększyć pewność co do dokładności adresu na podstawie samej odpowiedzi Geocoding API. Jednak w przeciwieństwie do wyniku Address Validation API, Geocoding API nie zwróci dokładnych informacji, które pozwolą określić dokładność wyniku.

Typ lokalizacji

Aby prawidłowo zrozumieć tę sekcję, musisz poznać różne typy lokalizacji, które mogą być zwracane w odpowiedzi Geocoding API response:

  • ROOFTOP oznacza, że zwrócony wynik to dokładny geokod, dla którego mamy informacje o lokalizacji dokładne do adresu ulicy.
  • RANGE_INTERPOLATED oznacza, że zwrócony wynik odzwierciedla przybliżenie (zwykle na drodze) interpolowane między 2 dokładnymi punktami (np. skrzyżowaniami). Wyniki interpolowane są zwykle zwracane, gdy dla adresu ulicy nie są dostępne geokody na dachu.
  • GEOMETRIC_CENTER oznacza, że zwrócony wynik to geometryczny środek wyniku, np. linii łamanej (np. ulicy) lub wielokąta (regionu).
  • APPROXIMATE oznacza, że zwrócony wynik nie jest żadnym z powyższych.

Jeśli Geocoding API zwraca location_type o wartości ROOFTOP lub RANGE_INTERPOLATED, nie oznacza to, że adres istnieje. Podobnie, jeśli Geocoding API zwraca flagę partial_match ustawioną na true, może to być nadal prawidłowy 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 danych na podstawie kraju i miejscowości w żądaniu lub odpowiedzi. Jeszcze lepiej porównać rzeczywiste adresy ulic pod kątem błędów ortograficznych lub niepełnego adresu.

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

Częściowe dopasowanie i fałszywe dopasowanie

Jeśli adres jest częściowo dopasowany, co oznacza, że Geocoding API nie udało się dokładnie zidentyfikować adresu, odpowiedź zawiera:

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

Jeszcze ważniejsze niż powyższe typy lokalizacji jest sprawdzenie, kiedy partial_match = true występuje w odpowiedzi. partial_match oznacza, że Geocoding API nie zwróciło dokładnego dopasowania do pierwotnego żądania, ale udało mu się dopasować część żądanego adresu.

Możesz sprawdzić, czy pierwotne żądanie zawiera niepełny adres. 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ą też być zwracane, 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 zarówno do Henry Street, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera komponent adresu z błędem ortograficznym, Geocoding API może zasugerować alternatywny adres. Sugestie wywołane w ten sposób nie będą oznaczane jako częściowe dopasowanie.

Adresy syntetyczne

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 znajdziesz 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 Address Validation API bezpośrednio informuje, czy adres nie istnieje.

Interpretowanie odpowiedzi Address Validation API

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

  • Przegląd obiektu odpowiedzi znajdziesz tutaj.
  • Wersja demonstracyjna, która ilustruje różne komponenty odpowiedzi, jest dostępna tutaj
  • W dokumencie Weryfikacja adresu na potrzeby płatności znajdziesz szczegółowy opis tego, jak odróżnić prawidłowe adresy od nieprawidłowych.

Sprawdzone metody

Określanie lokalizacji

Podczas wywoływania Address Validation API lub Geocoding API 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 – preferowanie regionu

    Jeśli wiesz, że geokody będą znajdować się w określonym kraju, możesz uzyskać znacznie lepsze wyniki, korzystając z preferowania regionu. Jeśli na przykład geokodujesz w Kanadzie, zalecamy dodanie &region=ca do żądań, aby preferować Kanadę. Pamiętaj, że preferowanie regionu preferuje tylko wyniki w tym regionie. Nadal możesz otrzymywać wyniki spoza regionu.

  • Address Validation API – kod regionu

    Podobnie Address Validation API generuje dokładniejsze wyniki, jeśli w żądaniu zostanie przekazany kod ISO2 za pomocą 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 bazie danych bezterminowo jako atrybut lokalizacji. Żądanie Znajdź miejsce musisz wysł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ć pewność, że zawsze masz najbardziej aktualne informacje, odświeżaj identyfikatory miejsc co 12 miesięcy za pomocą żądania 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 Address Validation API a Geocoding API. Podsumowując, rozważ użycie Address Validation API, gdy:

  • Wymagany jest dokładny adres pocztowy, zwłaszcza na potrzeby dostarczania przesyłek.
  • Wiadomo, że dane wejściowe są niskiej jakości. Address Validation API jest bardziej tolerancyjny wobec błędów w danych wejściowych, wyróżnia niezweryfikowane komponenty adresu i wprowadza poprawki w danych wejściowych.
  • Potrzebujesz więcej informacji o adresie, np. czy jest to adres mieszkalny czy komercyjny (dostępne w wybranych regionach).

Następne kroki

Pobierz dokument techniczny Usprawnianie procesu płatności, dostawy i operacji dzięki wiarygodnym adresom i obejrzyj webinar Usprawnianie procesu płatności, dostawy i operacji dzięki Address Validation .

Sugerowane dalsze lektury:

Współtwórcy

Ten artykuł jest utrzymywany przez Google. Pierwotnie napisali go ci współtwórcy:

Główni autorzy:

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

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

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