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ą nie być dobrej jakości. Musisz się upewnić, że adresy są prawidłowe w różnych przypadkach użycia, takich jak weryfikacja tożsamości klienta czy dostawa.

Interfejs API weryfikacji adresów to usługa w Google Maps Platform, której możesz używać do sprawdzania adresów. Jednak przetwarza tylko jeden adres naraz. W tym dokumencie omówimy sposób korzystania z weryfikacji adresów o dużej liczbie adresów w różnych scenariuszach, od testowania interfejsu API po jednorazową i powtarzalną weryfikację adresów.

Przypadki użycia

Teraz poznamy przypadki użycia, w których przydaje się weryfikacja adresów w dużej ilości.

Testowanie

Często chcesz przetestować interfejs API weryfikacji adresów, wykonując testy na tysiącach adresów. Adresy mogą być w pliku CSV i chcesz sprawdzić ich jakość.

jednorazowa weryfikacja adresów;

Podczas wdrażania interfejsu Address Validation API chcesz zweryfikować istniejącą bazę danych adresów na podstawie bazy danych użytkowników.

okresowe sprawdzanie adresów;

Weryfikacja adresów jest wymagana w kilku sytuacjach:

  • Możesz mieć zaplanowane zadania służące do weryfikowania adresów pod kątem szczegółów rejestracji klientów, szczegółów zamówień i harmonogramów dostawy.
  • Możesz otrzymywać dane zawierające adresy z różnych działów, na przykład z działu sprzedaży lub marketingu. Nowy dział, który otrzymuje adresy, często chce je zweryfikować przed ich użyciem.
  • Adresy możesz zbierać podczas ankiet lub różnych promocji, a później aktualizować w systemie online. Chcesz sprawdzić, czy adresy są prawidłowe, gdy wprowadzasz je do systemu.

Szczegółowy opis techniczny

W ramach tego dokumentu przyjmujemy, że:

  • wywołujesz interfejs Address Validation API z adresami z bazy danych klienta (czyli bazy danych z danymi klienta);
  • Możesz przechowywać w pamięci podręcznej flagi ważności dla poszczególnych adresów w swojej bazie danych.
  • Flagi ważności są pobierane z interfejsu API weryfikacji adresów, gdy loguje się konkretny klient.

Pamięć podręczna na potrzeby wersji produkcyjnej

Podczas korzystania z interfejsu Address Validation API często warto zapisać w pamięci podręcznej część odpowiedzi z wywołania interfejsu API. Nasze Warunki korzystania z usługi ograniczają dane, które można przechowywać w pamięci podręcznej. Jednak wszystkie dane, które można przechowywać w pamięci podręcznej za pomocą interfejsu API do weryfikacji adresów, muszą być przechowywane w pamięci podręcznej na koncie użytkownika. Oznacza to, że w bazie danych adres lub metadane adresu muszą być zapisane w pamięci podręcznej pod adresem e-mail użytkownika lub innym identyfikatorem głównym.

W przypadku weryfikacji adresów w dużej ilości dane muszą być przechowywane w pamięci podręcznej zgodnie z Warunkami dotyczącymi usługi API weryfikacji adresów (sekcja 11.3). Na podstawie tych informacji możesz określić, czy adres użytkownika może być nieprawidłowy. W takim przypadku poprosisz użytkownika o podanie prawidłowego adresu podczas następnej interakcji z Twoją aplikacją.

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

Jeśli chcesz zapisać w pamięci podręcznej jakiekolwiek informacje o rzeczywistym adresie, dane te muszą być zapisywane w pamięci podręcznej tylko za zgodą użytkownika. Dzięki temu użytkownik wie, dlaczego dany serwis przechowuje jego adres, i czy zgadza się na udostępnianie swojego adresu.

Przykładem zgody użytkownika jest bezpośrednie wprowadzenie adresu w formularzu e-commerce na stronie płatności. Zakładamy, że adres będzie przechowywany w pamięci podręcznej i przetwarzany w celu wysyłki paczki.

Za zgodą użytkownika możesz zapisać w pamięci podręcznej formattedAddress i inne kluczowe komponenty z odpowiedzi. W przypadku architektury bez serwera-klienta użytkownik nie może jednak wyrazić zgody, ponieważ weryfikacja adresu odbywa się po stronie serwera. W takim scenariuszu bez serwera możesz przechowywać w pamięci podręcznej bardzo ograniczoną ilość informacji.

Interpretowanie odpowiedzi

Jeśli odpowiedź interfejsu Address Validation API zawiera te znaczniki, możesz mieć pewność, że adres wejściowy jest nadający się do wysyłki:

  • znacznik addressComplete w obiekcie Verdict 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 się to zdarzyć, gdyaddressComplete=true)
    • spellCorrected
    • replaced
    • unexpected i
  • confirmationLevel: poziom potwierdzenia w AddressComponent ma wartośćCONFIRMEDlubUNCONFIRMED_BUT_PLAUSIBLE

Jeśli odpowiedź interfejsu API nie zawiera powyższych znaczników, adres wejściowy był prawdopodobnie niskiej jakości. Możesz umieścić w bazie danych flagi pamięci podręcznej, aby to odzwierciedlić. Flagi w pamięci podręcznej wskazują, że adres jako całość ma niską jakość, a bardziej szczegółowe flagi, takie jak „Poprawiono pisownię”, wskazują na konkretny typ problemu z jakością adresu. Podczas następnej interakcji klienta z adresem oznaczonym jako niskiej jakości możesz wywołać interfejs Address Validation API z dotychczasowym adresem. Interfejs API weryfikacji adresu zwróci poprawiony adres, który możesz wyświetlić za pomocą promptu w interfejsie. Gdy klient zaakceptuje sformatowany adres, możesz zapisać w pamięci podręcznej z odpowiedzi te informacje:

  • formattedAddress
  • postalAddress
  • addressComponent componentNameslub
  • UspsData standardizedAddress

Wdrożenie weryfikacji adresu w trybie headless

Na podstawie powyższego dialogu:

  • Z powodów biznesowych często trzeba przechowywać w pamięci podręcznej część odpowiedzi z interfejsu AddressValidation API.
  • Jednak Warunki korzystania z usługi w Google Maps Platform ograniczają, jakie dane mogą być przechowywane w pamięci podręcznej.

W następnej sekcji omówimy dwuetapowy proces zgodności z Warunkami korzystania z usługi i weryfikacji adresów w dużych ilościach.

Krok 1.

W pierwszym kroku zobaczysz, jak zaimplementować skrypt walidacji adresów o dużej objętości z dotychczasowego potoku danych. Dzięki temu będziesz mógł przechowywać określone pola z odpowiedzi interfejsu Address Validation API w sposób zgodny z Warunkami korzystania z usługi.

Diagram A: ten diagram pokazuje, jak można ulepszać przepływ danych za pomocą logiki weryfikacji adresów o dużej liczbie adresów.

alt_text

Zgodnie z Warunkami korzystania z usługi możesz zapisać w pamięci podręcznej te dane z addressComponent:

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

Dlatego na tym etapie wdrażania zapisane w pamięci podręcznej będą wspomniane pola w przypadku identyfikatora UserID.

Więcej informacji znajdziesz w szczegółach dotyczących rzeczywistej struktury danych.

Krok 2.

W kroku 1 zebraliśmy opinie, że niektóre adresy w danych wejściowych mogą nie być wysokiej jakości. W następnym kroku pokażemy użytkownikowi te adresy i poprosimy o potwierdzenie, że zgadza się na ich poprawienie.

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

alt_text

  1. Gdy użytkownik się zaloguje, najpierw sprawdź, czy masz w pamięci podręcznej jakieś flagi walidacji.
  2. Jeśli pojawią się flagi, należy wyświetlić użytkownikowi interfejs użytkownika, aby umożliwić mu poprawienie i zaktualizowanie adresu.
  3. Możesz ponownie wywołać interfejs Address Validation API, podając zaktualizowany lub zarchiwizowany adres, i przedstawić poprawiony adres do potwierdzenia użytkownikowi.
  4. Jeśli adres jest dobrej jakości, interfejs Address Validation API zwraca wartość formattedAddress.
  5. Możesz przedstawić ten adres użytkownikowi, jeśli zostały wprowadzone poprawki, lub zaakceptować go bez powiadamiania, jeśli nie ma żadnych poprawek.
  6. Gdy użytkownik zaakceptuje, możesz zapisać w pamięci podręcznej formattedAddress w bazie danych.

Podsumowanie

Walidacja adresów w dużych ilościach to typowy przypadek użycia, z którym możesz się spotkać w wielu aplikacjach. W tym dokumencie przedstawiamy kilka scenariuszy i schemat projektowania, które pomogą Ci wdrożyć takie rozwiązanie zgodnie z Warunkami korzystania z usługi Mapy Google.

W ramach tego projektu napisaliśmy też referencyjną implementację weryfikacji adresów w dużej skali jako bibliotekę open source w GitHub. Zapoznaj się z tym dokumentem, aby szybko rozpocząć tworzenie reguł weryfikacji adresów w dużej ilości. Przeczytaj też artykuł o wzorach projektowych, w którym znajdziesz wskazówki dotyczące korzystania z biblioteki w różnych sytuacjach.

Następne kroki

Pobierz białe papier dotyczące poprawy procesu płatności, dostawy i operacji dzięki wiarygodnym adresom i obejrzyj webinar dotyczący poprawy procesu płatności, dostawy i operacji dzięki weryfikacji adresów .

Sugerowane artykuły:

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ń