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ć wysokiej 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.

Adres Validation API to usługa w Google Maps Platform, której możesz używać do sprawdzania adresu. 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 poznasz przypadki użycia, w których przydaje się walidacja adresów w dużej ilości.

Testowanie

Często trzeba 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 wprowadzania interfejsu Address Validation API chcesz zweryfikować istniejącą bazę danych adresów na podstawie bazy danych użytkowników.

Ciągła weryfikacja adresów

W pewnych sytuacjach należy regularnie weryfikować adresy:

  • Możesz mieć zaplanowane zadania, które weryfikują adresy 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 potem aktualizować w systemie online. Chcesz sprawdzić, czy adresy są prawidłowe podczas wprowadzania ich do systemu.

Szczegóły techniczne

Na potrzeby tego dokumentu zakładamy, że:

  • wywołujesz interfejs Address Validation API z adresami z bazy danych klienta (czyli bazy danych z danymi klienta);
  • Możesz zapisać 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 Address Validation API, 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 Address Validation API, 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 głównym identyfikatorem.

W przypadku walidacji adresów w dużej ilości dane muszą być przechowywane w pamięci podręcznej zgodnie z Warunkami usługi interfejsu API do walidacji adresów określonymi w sekcji 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 dana usługa przechowuje jego adres, i wie, że zgadza się na udostępnianie tego adresu.

Przykładem zgody użytkownika jest bezpośrednie wypełnienie formularza adresowego w witrynie e-commerce na stronie płatności. Zgadzamy się, że adres będzie przechowywany w pamięci podręcznej i przetwarzany w celu wysyłki przesyłki.

Za zgodą użytkownika możesz zapisać w pamięci podręcznej odpowiedź z elementem formattedAddress i innymi kluczowymi elementami. W przypadku architektury headless użytkownik nie może jednak wyrazić zgody, ponieważ weryfikacja adresu odbywa się po stronie serwera. Dlatego w tym scenariuszu bez serwera możesz przechowywać w pamięci podręcznej bardzo ograniczone informacje.

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 dostarczenia:

  • 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ę tak zdarzyć, gdy addressComplete=true)
    • spellCorrected
    • replaced
    • unexpected i
  • confirmationLevel: poziom potwierdzenia w AddressComponent jest ustawiony na CONFIRMED lub UNCONFIRMED_BUT_PLAUSIBLE.

Jeśli odpowiedź interfejsu API nie zawiera powyższych znaczników, adres wejściowy prawdopodobnie był niskiej jakości. Możesz odzwierciedlić to w swojej bazie danych, korzystając z flag w pamięci podręcznej. 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 z klientem, którego adres został oznaczony 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ą komunikatu w interfejsie. Gdy klient zaakceptuje sformatowany adres, możesz zapisać w pamięci podręcznej te informacje z odpowiedzi:

  • formattedAddress
  • postalAddress
  • addressComponent componentNames lub
  • UspsData standardizedAddress

Implementacja weryfikacji adresu w trybie bez serwera

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 sekcji poniżej omówimy dwuetapowy proces dostosowania się do Warunków korzystania z usługi i implementacji weryfikacji adresów w dużych ilościach.

Krok 1.

Na początek pokażemy, jak zaimplementować skrypt do weryfikacji adresów o dużej liczbie adresów z dotychczasowego potoku danych. Dzięki temu będziesz mieć możliwość przechowywania określonych pól 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ć potok danych za pomocą logiki weryfikacji adresów o dużej liczbie rekordó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 zapisuje w pamięci podręcznej wymienione powyżej pola w związku z identyfikatorem UserID.

Więcej informacji znajdziesz w sekcji dotyczącej rzeczywistej struktury danych.

Krok 2.

W kroku 1 otrzymaliśmy informację, że niektóre adresy w danych wejściowych mogą nie być wysokiej jakości. W następnym kroku pokażemy użytkownikowi te adresy z oznacznikiem i poprosimy o potwierdzenie, że chce on poprawić zapisany adres.

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 w systemie masz w pamięci podręcznej jakieś flagi walidacji.
  2. Jeśli pojawią się flagi, wyświetl użytkownikowi interfejs, za pomocą którego będzie on mógł poprawić i zaktualizować adres.
  3. Możesz ponownie wywołać interfejs Address Validation API, podając zaktualizowany lub z pamięci podręcznej adres, a następnie wyświetlić poprawiony adres użytkownikowi w celu potwierdzenia.
  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 wzorzec projektowania, które pomogą Ci w wdrożeniu takiego rozwiązania zgodnie z Warunkami korzystania z usługi Mapy Google.

W ramach tego projektu napisaliśmy na GitHubie referencyjne rozwiązanie do weryfikacji adresów w dużej ilości w postaci biblioteki open source. Zapoznaj się z tym dokumentem, aby szybko rozpocząć tworzenie aplikacji z weryfikacją adresów o dużej liczbie adresów. Przeczytaj też artykuł o wzorach projektowych, w którym znajdziesz informacje o używaniu 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 materiały do dalszego zapoznania się z tematem:

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ń