Przewodnik po rozwiązaniu do weryfikacji adresu

Cel

Weryfikacja adresów jest przydatna w różnych przypadkach użycia. Oprócz samej jakości wyników testów warto wziąć pod uwagę kilka kluczowych kwestii. Na przykład: całościowy widok zgodnych produktów w wzorcu przeglądania, takich jak Autouzupełnianie miejsc i Mapy, dostępność regionalna oraz zaufanie i niezawodność w firmie.

Gdy dojdziesz do etapu oceny interfejsu Address Validation API, zalecamy skorzystanie z tych wskazówek w ramach testów.

Cele tego testu:

1. Sprawdź, czy interfejs Address Validation API jest odpowiedni do Twojego przypadku użycia.
2. Sprawdź, jak Address Validation API spełnia wymagania Twojego rozwiązania, takie jak:
   • Identyfikowanie adresów dobrej jakości.
   • Alerty dotyczące danych wejściowych o niskiej jakości.
   • wprowadzanie poprawek w danych adresowych, w tym wnioskowanie, zastępowanie i poprawianie pisowni;
   • Podanie sformatowanego adresu dostawy.
   • Ostrzeżenia o brakujących lub nieprawidłowych danych dotyczących lokalu (tylko w Stanach Zjednoczonych).
3. Upewnij się, że wdrożenie interfejsu API przyniesie Ci wymierne korzyści.

Po przeprowadzeniu testu będziesz w stanie odpowiedzieć na powyższe pytania i ustalić, czy interfejs API jest odpowiedni dla Twojej firmy.

Przygotowywanie danych

Test powinien zostać przeprowadzony na próbce istniejących danych adresowych. Nie wybieraj danych do testu ręcznie, ale wybierz losowe próbki, które są reprezentatywne dla regionów, w których działasz. Oznacza to, że jeśli prowadzisz działalność zarówno w Stanach Zjednoczonych, jak i w Wielkiej Brytanii, ale 70% Twojej działalności odbywa się w Wielkiej Brytanii, a 30% w Stanach Zjednoczonych, próbka powinna odzwierciedlać ten podział.

Użyj adresów z miejsca przechwycenia. Jeśli na przykład planujesz wdrożyć weryfikację adresów w procesie płatności w e-commerce, użyj adresów wpisanych przez klientów w formularzu, zanim zostaną one przetworzone w sposób, który może zostać zastąpiony przez wdrożenie interfejsu Address Validation API.

Przygotuj do testu próbkę o rozmiarze około 5000–10 000 rekordów.

Wywoływanie interfejsu API

Warunek wstępny: musisz wiedzieć, jak wysłać żądanie weryfikacji adresu.

Po przygotowaniu danych musisz uruchomić każdy rekord adresu w interfejsie API.

Wskazówki dotyczące wywoływania interfejsu API znajdziesz w dokumentacji Address Validation API. Mamy też artykuł opisujący sprawdzone metody korzystania z interfejsu Address Validation API do przetwarzania dużej liczby adresów.

Wynikiem tego kroku powinny być dane wyjściowe z interfejsu API dla każdego rekordu adresu. Następnie możesz przeanalizować wyniki, aby określić, czy interfejs API jest odpowiedni do Twojego przypadku użycia. To, czy użyjesz arkusza kalkulacyjnego, bazy danych czy innego narzędzia, zależy od Ciebie.

Sprawdzanie wyników

Wymagania wstępne: musisz wiedzieć, jak obsługiwać odpowiedź dotyczącą weryfikacji, a zwłaszcza znać koncepcję naprawiania, potwierdzania i akceptowania.

W tej sekcji omówimy scenariusze wyjściowe, które możesz przeanalizować, aby ocenić dopasowanie rozwiązania.

Omówienie najważniejszych pól interfejsu API opisanych w tym dokumencie

Dane odpowiedzi	Co to jest?	How To Evaluate	Jak to pomaga?
verdict.inputGranularity	Opisuje szczegółowość danych wejściowych adresu.	SUB_PREMISE PREMISE PREMISE_PROXIMITY ZABLOKUJ ROUTE INNA ODPOWIEDŹ	Umożliwia określenie, czy podany adres zawiera wystarczającą ilość danych, aby potencjalnie był prawidłowy.
verdict.validationGranularity	Opisuje ogólną weryfikację danych wyjściowych adresu.	SUB_PREMISE PREMISE PREMISE_PROXIMITY ZABLOKUJ ROUTE INNA ODPOWIEDŹ	Umożliwia określenie ogólnej jakości adresu na wyjściu z interfejsu API.
verdict.hasInferredComponents	Sygnalizuje, czy interfejs API wywnioskował komponent.	Prawda/Fałsz	Interfejs API może dodawać brakujące komponenty, jeśli może wywnioskować dane. Na przykład brak kodu stanu.
verdict.hasReplacedComponents	Sygnalizuje, czy interfejs API zastąpił komponent.	Prawda/Fałsz	W niektórych przypadkach interfejs API może zastąpić nieprawidłowe komponenty prawidłowymi danymi.
verdict.addressComplete	Sygnalizuje, czy adres jest kompletny.	Prawda/Fałsz	Jeśli interfejs API określi, że adres wyjściowy zawiera wszystkie niezbędne komponenty, ta wartość będzie mieć wartość true.
address.missingComponentTypes	Sygnał ostrzegający, jeśli w adresie brakuje komponentów.	Wartości znajdziesz w  tabeli 2.	Wyróżniaj brakujące elementy niepełnego adresu.

Sprawdzanie prawidłowych adresów

Posortuj dane zwrócone przez interfejs API, aby określić zestaw adresów, które Twój system zaakceptuje jako prawidłowe. Kluczowe sygnały, na które należy zwrócić uwagę w interfejsie API:

• verdict.validationGranularity zawiera PREMISE lub lepsze.
• verdict.addressComplete to true.
• Brak wywnioskowanych lub zastąpionych komponentów.

Więcej informacji znajdziesz w sekcji Akceptowanie adresu.

Wynikiem tego ćwiczenia powinien być podzbiór danych adresowych, które Twój system zaakceptuje jako prawidłowe. Na tym etapie możesz określić:

• Czy odsetek akceptacji jest akceptowalny?
• Jeśli używasz dotychczasowego procesu weryfikacji adresów, czy współczynnik akceptacji jest taki sam lub lepszy?

Przykład: prawidłowy adres

Podany adres	Region
76 Buckingham Palace Road, London SW1W 9TQ, Wielka Brytania	Wielka Brytania

Werdykt

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true
}

Sprawdzanie nieprawidłowych adresów

Ten krok umożliwia ręczne sprawdzenie niektórych danych adresowych, które zostały oznaczone jako nieprawidłowe, i sprawdzenie, czy bez użycia interfejsu Address Validation API ten nieprawidłowy adres może powodować problemy na dalszych etapach.

Posortuj dane zwrócone przez interfejs API, aby określić zestaw adresów, które system oznaczy jako nieprawidłowe. Kluczowe sygnały, na które należy zwrócić uwagę w interfejsie API:

• verdict.validationGranularity ustawione na OTHER lub ROUTE w zależności od poziomu ryzyka.
• verdict.addressComplete to false.

Więcej informacji znajdziesz w artykule Poprawianie adresu.

Wynikiem tego ćwiczenia powinien być podzbiór danych adresowych, które Twój system oznaczyłby jako nieprawidłowe. W tym momencie możesz określić, czy odsetek nieprawidłowych kliknięć jest akceptowalny.

Ważne jest, aby pamiętać, że oznaczanie adresów jako nieprawidłowych jest podstawową funkcją interfejsu Address Validation API, a wysoki odsetek adresów oznaczonych jako nieprawidłowe nie musi oznaczać, że interfejs API działa nieprawidłowo. Interfejs API informuje, że coś jest nie tak z adresem, co może zwiększyć wydajność przepływu pracy dzięki wcześniejszemu wykrywaniu błędów, zanim spowodują one problemy na dalszych etapach.

Przykład: nieprawidłowy adres

Podany adres	Region
21 45 40th street	USA

Werdykt

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "OTHER",
  "geocodeGranularity": "OTHER",
  "hasUnconfirmedComponents": true
}

Sprawdzanie brakujących lub niepotwierdzonych komponentów

Na tym etapie można też sprawdzić brakujące lub niepotwierdzone komponenty. Jest to część obiektu Address w odpowiedzi. Te 2 pola to missingComponentTypes i unconfirmedComponentTypes.

Użyj tych pól, aby wykryć, dlaczego adres został oznaczony przez interfejs API jako nieprawidłowy, i zebrać prawidłowe informacje o adresie, które umożliwią jego prawidłowe działanie, przekazując do punktu zbierania danych informacje o nieprawidłowych polach. W ten sposób interfejs API dostarcza wartościowych informacji o jakości danych.

Przykład: brakujący i niepotwierdzony komponent

Podany adres	Region
Fake St, New York, NY 10011	USA

Werdykt

{
     "inputGranularity": "ROUTE",
     "validationGranularity": "OTHER",
     "geocodeGranularity": "OTHER",
     "hasUnconfirmedComponents": true
}

Brakujące i niepotwierdzone komponenty

"missingComponentTypes": [
    "street_number"
],
"unconfirmedComponentTypes": [
    "route"
]

Sprawdzanie adresów z poprawkami

Interfejs Address Validation API może wprowadzać poprawki do danych wejściowych, pobierając potencjalnie nieprawidłowy adres i zwracając prawidłowe dane adresowe. To jeden ze sposobów, w jaki interfejs API dodaje wartość dodaną, i ważne jest, aby uwzględnić to w teście.

Kluczowe sygnały, na które należy zwrócić uwagę:

• inferred, replaced lub spellCorrected ustawione na true w dowolnym z addressComponents.
• verdict.hasInferredComponents lub verdict.hasReplacedComponents ustawiono na true.

Więcej informacji znajdziesz w artykule Potwierdzanie adresu.

Wynikiem tego ćwiczenia powinien być podzbiór danych adresowych, które zostały poprawione przez interfejs API.

Część tych danych można sprawdzić ręcznie, aby określić, czy interfejs API wprowadza poprawki do danych, które zmniejszyłyby problemy w dalszym procesie.

Przykład: adres z poprawką

Podany adres	Region
76 Buckingham Palace Road, London SW1W 9TQ	Wielka Brytania

Trasa addressComponent

{
    "componentName": {
        "text": "Buckingham Palace Road",
        "languageCode": "en"
    },
    "componentType": "route",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

[Tylko USA] Sprawdzanie adresu z brakującymi lub nieprawidłowymi danymi dotyczącymi lokalu

Interfejs Address Validation API może określić, czy w przypadku adresów w Stanach Zjednoczonych brakuje lokalu lub czy jest on nieprawidłowy.

Kluczowe sygnały, na które należy zwrócić uwagę:

• W obiekcie Address:
  • unconfirmedComponentTypes zawiera subpremise
  • missingComponentTypes zawiera subpremise
• W obiekcie UspsData:
  • dpvConfirmation to D (brak numeru lokalu)
  • dpvConfirmation to S (niepotwierdzony numer lokalu)

Więcej informacji znajdziesz w sekcji Obsługa adresów w Stanach Zjednoczonych.

Ten test pokaże, czy w Twoich danych występuje problem z brakującymi lub nieprawidłowymi danymi dotyczącymi lokalu, np. numerami mieszkań. Może to powodować problemy na dalszych etapach, zwłaszcza w przypadku dostawy. Address Validation API może zwiększyć wartość Twojego przepływu pracy, identyfikując ten problem wcześniej i umożliwiając wdrożenie kroków w celu zebrania poprawionych danych.

Przykład: brak numeru lokalu.

Podany adres	Region
111 8th Avenue, Manhattan, NY 10011, USA	US

Brakujący komponent

"missingComponentTypes": [
    "subpremise"
]

Potwierdzenie DPV danych USPS

"dpvConfirmation": "D"

[USA only] Review USPS standardizedAddress

Address Validation API zwraca też adresy w USA w formacie USPS. Jest to szczególnie ważne, jeśli na etykietach wysyłkowych muszą być drukowane adresy w formacie USPS.

Możesz sprawdzić UspsAddress, aby wyświetlić te dane i określić, czy są one przydatne w Twoim przepływie pracy.

Przykład: znormalizowany adres USPS

"standardizedAddress": {
    "firstAddressLine": "111 8TH AVE FL 11",
    "cityStateZipAddressLine": "NEW YORK NY 10011-5201",
    "city": "NEW YORK",
    "state": "NY",
    "zipCode": "10011",
    "zipCodeExtension": "5201"
}

Podsumowanie

Zacznij testować – już dziś rozpocznij testowanie interfejsu Address Validation API, aby zapewnić dokładne dane adresowe, poprawić wrażenia klientów i usprawnić operacje biznesowe. Po wykonaniu opisanych powyżej scenariuszy testowych będziesz mieć informacje potrzebne do określenia, czy interfejs Address Validation API przyniesie korzyści Twojemu przepływowi pracy.

Sugerowane artykuły:

• Dokumentacja dla deweloperów dotycząca interfejsu Address Validation API
• Przetwarzanie dużej liczby adresów za pomocą interfejsu Address Validation API
• Weryfikacja adresów podczas płatności w e-commerce

Współtwórcy

Henrik Valve | inżynier DevX