Przetwarzanie adresów przy dużej liczbie adresów za pomocą interfejsu Address Validation API

Cel

Jako programista często pracujesz ze zbiorami danych zawierającymi adresy klientów, które mogą być niskiej jakości. Musisz się upewnić, że adresy są prawidłowe w różnych przypadkach użycia, od weryfikacji identyfikatora klienta po dostawę.

Interfejs Address Validation API to usługa Google Maps Platform, która służy do weryfikowania adresu. Przetwarza jednak tylko 1 adres naraz. Z tego dokumentu dowiesz się, jak korzystać z walidacji dużej ilości adresów w różnych sytuacjach, od testowania interfejsów API po jednorazową i cykliczną weryfikację adresów.

Przykłady zastosowań

Teraz przyjrzymy się przypadkom użycia, w których przydaje się weryfikacja adresów o dużej liczbie adresów.

Testowanie

Często chcesz przetestować interfejs Address Verificationation API, uruchamiając tysiące adresów. Być może masz adresy w pliku wartości rozdzielanych przecinkami i chcesz sprawdzić ich jakość.

Jednorazowa weryfikacja adresów

Podczas rozpoczynania pracy z interfejsem Address Verification API chcesz sprawdzić, czy Twoja istniejąca baza danych adresów korzysta z bazy danych użytkowników.

Cykliczna weryfikacja adresów

Istnieje wiele scenariuszy wymagających cyklicznego weryfikowania adresów:

  • Możesz mieć zaplanowane zadania do weryfikacji adresów w celu weryfikacji szczegółów rejestrowanych w ciągu dnia, na przykład rejestracji klientów, szczegółów zamówień czy harmonogramów dostaw.
  • Możesz otrzymywać zrzuty danych zawierające adresy z różnych działów, np. działu sprzedaży po marketing. Nowy dział otrzymujący adresy często chce je zweryfikować przed użyciem.
  • Możesz zbierać adresy podczas ankiet i różnych promocji, a później aktualizować je w systemie online. Chcesz sprawdzić poprawność adresów podczas wpisywania ich do systemu.

Szczegółowe informacje techniczne

Na potrzeby tego dokumentu zakładamy, że:

  • Wywołujesz interfejs API do weryfikacji adresów za pomocą adresów z bazy danych klienta (np.bazy danych z informacjami o kliencie).
  • Możesz buforować flagi ważności dla poszczególnych adresów w swojej bazie danych.
  • Flagi ważności są pobierane z interfejsu Address Verificationation API podczas logowania się danego klienta.

Buforowanie na potrzeby środowiska produkcyjnego

Podczas korzystania z interfejsu Address Verification API często chcesz przechowywać w pamięci podręcznej część odpowiedzi z wywołania interfejsu API. Nasze Warunki korzystania z usługi ograniczają zakres danych, które można przechowywać w pamięci podręcznej. Jednak wszelkie dane, które można przechowywać w pamięci podręcznej za pomocą interfejsu Address Verificationation API, muszą być przechowywane w pamięci podręcznej na koncie użytkownika. Oznacza to, że w bazie danych adres lub metadane adresów muszą być przechowywane w pamięci podręcznej wraz z adresem e-mail użytkownika albo z innym podstawowym identyfikatorem.

W przypadku walidacji adresów dużej ilości danych przechowywanie danych w pamięci podręcznej musi być zgodne ze szczegółowymi warunkami korzystania z usługi Address Review API opisanych w artykule 11.3. Na podstawie tych informacji możesz ustalić, czy adres użytkownika jest nieprawidłowy. W takim przypadku przy kolejnej interakcji z aplikacją poprosimy go o poprawny adres.

  • Dane z obiektu AddressComponent
    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

Jeśli chcesz przechowywać w pamięci podręcznej jakiekolwiek informacje dotyczące rzeczywistego adresu, musisz je przechowywać w pamięci podręcznej tylko za zgodą użytkownika. Dzięki temu użytkownik dokładnie wie, dlaczego dana usługa przechowuje jego adres, i akceptuje warunki udostępniania adresu.

Przykładem zgody użytkownika może być bezpośrednia interakcja z formularzem adresu e-commerce na stronie płatności. Musisz rozumieć, że adres będzie przechowywany w pamięci podręcznej, a następnie przetwarzany na potrzeby wysyłki przesyłki.

Za zgodą użytkownika możesz zapisać w pamięci podręcznej formattedAddress i inne kluczowe komponenty z odpowiedzi. Jednak w sytuacji bez interfejsu graficznego użytkownik nie może wyrazić zgody, ponieważ weryfikacja adresu odbywa się z backendu. Dlatego w takim przypadku można przechowywać w pamięci podręcznej bardzo ograniczone informacje.

Interpretowanie odpowiedzi

Jeśli odpowiedź interfejsu Address Verification API zawiera te znaczniki, możesz mieć pewność, że adres wejściowy ma wysoką jakość:

  • Znacznik addressComplete w obiekcie Wynik to true.
  • Wartość validationGranularity w obiekcie Verdict to PREMISE lub SUB_PREMISE
  • Żaden z elementów AddressComponent nie jest oznaczony jako:
    • Inferred(Uwaga:: inferred=truemoże wystąpić, gdy addressComplete=true)
    • spellCorrected
    • replaced
    • unexpected i
  • confirmationLevel: poziom potwierdzenia w AddressComponent jest ustawiony na CONFIRMEDlubUNCONFIRMED_BUT_PLAUSIBLE

Jeśli odpowiedź interfejsu API nie zawiera powyższych znaczników, adres wejściowy prawdopodobnie ma niską jakość, i możesz to odzwierciedlić w pamięci podręcznej flagi w bazie danych. Flagi z pamięci podręcznej wskazują, że cały adres ma niską jakość, a bardziej szczegółowe flagi, takie jak poprawiona pisownia, wskazują konkretny typ problemu z jakością adresu. Podczas następnej interakcji klienta z adresem oznaczonym jako niskiej jakości możesz użyć tego adresu w interfejsie API do weryfikacji adresów. Interfejs Address Verification API zwróci poprawiony adres, który możesz wyświetlić w interfejsie. Gdy klient zaakceptuje sformatowany adres, z odpowiedzi możesz buforować:

  • formattedAddress
  • postalAddress
  • addressComponent componentNames lub
  • UspsData standardizedAddress

Wdrażanie weryfikacji adresu bez interfejsu graficznego

Na podstawie dyskusji powyżej:

  • Ze względów biznesowych często konieczne jest zapisywanie w pamięci podręcznej pewnej części odpowiedzi z interfejsu Address Billing API.
  • Jednakże Warunki korzystania z usługi w Google Maps Platform ograniczają, jakie dane można przechowywać w pamięci podręcznej.

W kolejnej części omówimy dwuetapowy proces zapewniania zgodności z Warunkami korzystania z usługi i wdrażania dużej liczby adresów.

Krok 1.

W pierwszym kroku pokażemy, jak wdrożyć skrypt weryfikacji adresów o dużej ilości danych z istniejącego potoku danych. Ten proces pozwoli Ci przechowywać określone pola z odpowiedzi interfejsu Address Review API w sposób zgodny z Warunkami korzystania z usługi.

Diagram A: na diagramie poniżej widać, jak można ulepszyć potok danych za pomocą logiki walidacji adresów dużej ilości danych.

alt_text

  • Zgodnie z Warunkami korzystania z usługi możesz buforować addressComplete, validationGranularity and validationFlags podczas walidacji adresów bez interfejsu graficznego.

  • Możesz buforować addressComplete,validationGranularity and validationFlags, PlaceID dla określonego identyfikatora UserID w bazie danych klienta.

Dlatego na tym etapie implementacji będziemy zapisywać w pamięci podręcznej wymienione wyżej pola związane z identyfikatorem UserID.

Więcej informacji o rzeczywistej strukturze danych.

Krok 2.

W kroku 1 zebraliśmy opinie, że niektóre adresy w wejściowym zbiorze danych mogą nie być wysokiej jakości. W następnym kroku weźmiemy oznaczone adresy i zaprezentujemy je użytkownikowi oraz uzyskamy ich zgodę na poprawienie zapisanego adresu.

Diagram B: ten schemat przedstawia, jak może wyglądać kompleksowa integracja procesu uzyskiwania zgody użytkownika:

alt_text

  1. Po zalogowaniu się użytkownika sprawdź najpierw, czy w pamięci podręcznej znajdują się flagi weryfikacji, np.:

    • Pole addressComplete ma wartość prawda
    • Wartość validationGranularity nie ma wartości PREMISE ani SUB_PREMISE
    • validationFlags to inferred,spellCorrected,replaced,unexpected.
      • Jeśli nie ma żadnych flag, istnieje duża szansa, że istniejący adres w pamięci podręcznej ma dobrą jakość i można go użyć.

  2. Jeśli flaga jest stosowana, należy wyświetlić użytkownikowi interfejs umożliwiający poprawienie/zaktualizowanie adresu.

  3. Możesz ponownie wywołać interfejs Address Verificationation API za pomocą zaktualizowanego lub zapisanego adresu w pamięci podręcznej, a następnie wyświetlić użytkownikowi poprawiony adres, aby go potwierdzić.

  4. Jeśli adres jest dobrej jakości, interfejs Address Verificationation API zwraca błąd formattedAddress.

  5. Możesz przedstawić ten adres użytkownikowi, jeśli wprowadź poprawki, lub dyskretnie zaakceptować, jeśli nie ma żadnych poprawek.

  6. Gdy użytkownik zaakceptuje prośbę, możesz buforować formattedAddress w bazie danych.

Pseudokod implementujący krok 2:

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

Podsumowanie

Weryfikacja adresów dużej liczby adresów to typowy przypadek użycia, który może występować w wielu aplikacjach. W tym dokumencie próbujemy zademonstrować kilka scenariuszy i wzorzec projektowy wdrażania takiego rozwiązania zgodnego z Warunkami korzystania z Google Maps Platform.

Opracowaliśmy również referencyjną wdrożenie weryfikacji adresów wielu adresów w postaci biblioteki open source w GitHubie. Skorzystaj z niej, aby szybko zacząć tworzyć walidację adresów na dużą skalę. Przeczytaj też artykuł o wzorcach korzystania z biblioteki w różnych sytuacjach.

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ń