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

Cel

Jako deweloper często pracujesz ze zbiorami danych zawierającymi adresy klientów, które mogą być niskiej jakości. Musisz mieć pewność, że adresy są prawidłowe w przypadku różnych zastosowań, od weryfikacji tożsamości klienta po dostawę i inne.

Interfejs Address Validation API to usługa Google Maps Platform, której możesz używać do weryfikowania adresów. Przetwarza jednak tylko jeden adres naraz. Z tego dokumentu dowiesz się, jak korzystać z weryfikacji adresów o dużej liczbie zapytań w różnych scenariuszach, od testowania interfejsu API po jednorazową i cykliczną weryfikację adresów.

Przypadki użycia

Teraz omówimy przypadki użycia, w których przydatna jest weryfikacja adresów o dużej liczbie zapytań.

Testowanie

Często chcesz przetestować interfejs Address Validation API, uruchamiając tysiące adresów. Możesz mieć adresy w pliku CSV i chcieć sprawdzić ich jakość.

Jednorazowa weryfikacja adresów

Podczas wprowadzania interfejsu Address Validation API chcesz zweryfikować swoją dotychczasową bazę danych adresów na podstawie bazy danych użytkowników.

Cykliczna weryfikacja adresów

W wielu sytuacjach konieczne jest regularne sprawdzanie poprawności adresów:

  • Możesz mieć zaplanowane zadania weryfikacji adresów na podstawie szczegółów zarejestrowanych w ciągu dnia, np. danych 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. z działu sprzedaży i marketingu. Nowy dział, który otrzymuje adresy, często chce je zweryfikować przed użyciem.
  • Adresy możesz zbierać podczas ankiet lub różnych promocji, a później aktualizować je w systemie online. Chcesz sprawdzić, czy adresy są prawidłowe podczas wpisywania ich w systemie.

Szczegółowe informacje techniczne

Na potrzeby tego dokumentu zakładamy, że:

  • wywołujesz interfejs Address Validation API z adresami z bazy danych klientów (czyli bazy danych ze szczegółami klientów);
  • Możesz zapisywać w bazie danych flagi ważności dla poszczególnych adresów.
  • Flagi ważności są pobierane z interfejsu Address Validation API, gdy zaloguje się klient indywidualny.

Pamięć podręczna do użytku w środowisku produkcyjnym

Podczas korzystania z interfejsu Address Validation API często warto buforować część odpowiedzi z wywołania interfejsu API. Nasze Warunki usługi ograniczają zakres danych, które można przechowywać w pamięci podręcznej. Jednak wszystkie dane, które można przechowywać w pamięci podręcznej z 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 w powiązaniu z adresem e-mail użytkownika lub innym podstawowym identyfikatorem.

W przypadku weryfikacji adresów o dużej liczbie zapytań buforowanie danych musi być zgodne z warunkami szczególnymi usługi interfejsu Address Validation API, które zostały opisane w sekcji 11.3. Na podstawie tych informacji możesz określić, czy adres użytkownika może być nieprawidłowy. W takim przypadku podczas następnej interakcji użytkownika z aplikacją poproś go o podanie poprawionego adresu.

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

Jeśli chcesz zapisać w pamięci podręcznej jakiekolwiek informacje o rzeczywistym adresie, musisz to zrobić tylko za zgodą użytkownika. Dzięki temu użytkownik będzie wiedział, dlaczego dana usługa przechowuje jego adres, i zaakceptuje warunki udostępniania adresu.

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

Za zgodą użytkownika możesz zapisywać w pamięci podręcznej formattedAddress i inne kluczowe komponenty z odpowiedzi. W przypadku bezgłowego środowiska użytkownik nie może jednak wyrazić zgody, ponieważ weryfikacja adresu odbywa się na backendzie. Dlatego w tym scenariuszu bez interfejsu możesz buforować bardzo ograniczone informacje.

Interpretowanie odpowiedzi

Jeśli odpowiedź interfejsu Address Validation API zawiera te znaczniki, możesz mieć pewność, że adres wejściowy jest odpowiedni do dostarczenia przesyłki:

  • Marker addressComplete w obiekcie Verdict ma wartość true.
  • Wartość validationGranularity w obiekcie Verdict to PREMISE lub SUB_PREMISE.
  • Żaden z elementów AddressComponent nie jest oznaczony jako:
    • Inferred(Uwaga:: inferred=true może się zdarzyć, gdyaddressComplete=true)
    • spellCorrected
    • replaced
    • unexpected i
  • confirmationLevel: poziom potwierdzenia w AddressComponent jest ustawiony naCONFIRMEDlubUNCONFIRMED_BUT_PLAUSIBLE

Jeśli odpowiedź interfejsu API nie zawiera powyższych znaczników, adres wejściowy był prawdopodobnie niskiej jakości i możesz zapisać w bazie danych odpowiednie flagi. Flagi w pamięci podręcznej wskazują, że adres jako całość jest niskiej jakości, a bardziej szczegółowe flagi, takie jak Spell Corrected (Poprawiona pisownia), wskazują konkretny rodzaj problemu z jakością adresu. Podczas kolejnej interakcji z klientem, w której użyje on adresu oznaczonego jako niskiej jakości, możesz wywołać interfejs Address Validation API z użyciem dotychczasowego adresu. Interfejs Address Validation API zwróci poprawiony adres, który możesz wyświetlić w oknie interfejsu. Gdy klient zaakceptuje sformatowany adres, możesz zapisać w pamięci podręcznej te informacje z odpowiedzi:

  • formattedAddress
  • postalAddress
  • addressComponent componentNames lub
  • UspsData standardizedAddress

Wdrażanie weryfikacji adresu bez interfejsu

Na podstawie powyższej dyskusji:

  • Często z przyczyn biznesowych konieczne jest buforowanie części odpowiedzi z interfejsu Address Validation API.
  • Jednak Warunki korzystania z usługi Google Maps Platform ograniczają zakres danych, które można przechowywać w pamięci podręcznej.

W sekcji poniżej omówimy 2-etapowy proces dostosowywania się do Warunków usługi i wdrażania weryfikacji adresów o dużej liczbie zapytań.

Krok 1.

W pierwszym kroku przyjrzymy się, jak wdrożyć skrypt weryfikacji dużej liczby adresów w ramach istniejącego potoku danych. Ten proces umożliwi Ci przechowywanie 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 ulepszyć potok danych za pomocą logiki weryfikacji adresów o dużej liczbie zapytań.

alt_text

Zgodnie z Warunkami korzystania z usługi możesz buforować te dane z addressComponent:

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

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

Więcej informacji znajdziesz w sekcji struktura danych.

Krok 2.

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

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 zapisane w pamięci podręcznej jakieś flagi weryfikacji.
  2. Jeśli są jakieś flagi, wyświetl użytkownikowi interfejs, w którym będzie mógł poprawić i zaktualizować adres.
  3. Możesz ponownie wywołać interfejs Address Validation API z zaktualizowanym lub zapisanym w pamięci podręcznej adresem i przedstawić użytkownikowi poprawiony adres do potwierdzenia.
  4. Jeśli adres jest dobrej jakości, interfejs Address Validation API zwraca wartość formattedAddress.
  5. Możesz wyświetlić ten adres użytkownikowi, jeśli wprowadzono poprawki, lub zaakceptować go bez powiadomienia, jeśli nie ma żadnych poprawek.
  6. Gdy użytkownik zaakceptuje prośbę, możesz zapisać formattedAddress w bazie danych.

Podsumowanie

Weryfikacja adresów o dużej liczbie zapytań to typowy przypadek użycia, z którym możesz się spotkać w wielu aplikacjach. W tym dokumencie przedstawiamy kilka scenariuszy i wzorców projektowych, które pokazują, jak wdrożyć takie rozwiązanie zgodnie z Warunkami korzystania z usługi Google Maps Platform.

Opracowaliśmy też referencyjną implementację weryfikacji adresów o dużej liczbie zapytań w postaci biblioteki open source w GitHubie. Zapoznaj się z nim, aby szybko rozpocząć tworzenie aplikacji z użyciem interfejsu High Volume Address Validation API. Zapoznaj się też z artykułem o wzorcach projektowych, w którym znajdziesz informacje o tym, jak korzystać z biblioteki w różnych scenariuszach.

Następne kroki

Pobierz białą księgę na temat usprawniania procesu płatności, dostawy i działań dzięki wiarygodnym adresom i obejrzyj webinar na temat usprawniania procesu płatności, dostawy i działań dzięki weryfikacji adresu .

Sugerowane dalsze lektury:

Współtwórcy

Google jest autorem tego artykułu. Oryginalni autorzy:
Główni autorzy:

Henrik Valve | Inżynier ds. rozwiązań
Thomas Anglaret | Inżynier ds. rozwiązań
Sarthak Ganguly | Inżynier ds. rozwiązań