W tym dokumencie opisano kilka scenariuszy, w których interfejs Address Validation API dostarcza sygnałów odpowiedzi dla adresów, które wymagają potwierdzenia przez Twój system. Aby uzyskać kontekst, zapoznaj się z artykułem Przegląd przepływu pracy w sekcji Tworzenie logiki sprawdzania.
Typowe przykłady: potwierdzenie
Poniższy przykład pokazuje obszar metropolitalny z podobnymi nazwami ulic. Załóżmy, że użytkownik chce wpisać adres budynku D firmy Google w Kirkland w stanie Waszyngton w Stanach Zjednoczonych. Jednak zamiast Kirkland jako miasta wpisują Seattle.
Adres został wpisany | Region |
---|---|
Budynek D, 451 7th Avenue South, Seattle, WA 98033 | Stany Zjednoczone |
Werdykt dotyczący zastąpionych danych
Przykład poniżej podkreśla ważne sygnały z odpowiedzi.
{
"inputGranularity": "SUB_PREMISE",
"validationGranularity": "PREMISE_PROXIMITY",
"geocodeGranularity": "PREMISE_PROXIMITY",
"addressComplete": true,
"hasUnconfirmedComponents": true
"hasReplacedComponents": true
}
Wartość PREMISE_PROXIMITY
wskazuje przybliżenie adresu na poziomie budynku, ale nie jest tak szczegółowa jak SUB_PREMISE
, która jest dokładnością podaną na wejściu.
Odpowiedź zawiera też elementy niezweryfikowane i zastąpione, dlatego ta kombinacja kwalifikuje się do kategorii potwierdzone.
Zapytanie o elementy adresu ujawnia te problemy:
{
"componentName": {
"text": "451",
},
"componentType": "street_number",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
...
{
"componentName": {
"text": "98104",
},
"componentType": "postal_code",
"confirmationLevel": "CONFIRMED",
"replaced": true
}
...
{
"componentName": {
"text": "Building D",
"language_code": "en"
},
"componentType": "subpremise",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
.......
"unconfirmedComponentTypes": [
"street_number",
"subpremise"
]
W tym przypadku interfejs Address Validation API znalazł adres zbliżony do podanego w Seattle i zastąpił kod pocztowy, który jest elementem wyższego poziomu, adresem w Seattle. Może to być prawidłowa wymiana, ale ze względu na fakt, że komponenty nie zostały potwierdzone, warto się upewnić, że użytkownik chce wpisać adres w Seattle, a nie inny, na przykład Kirkland.
Przykłady przypadków szczególnych: potwierdzenie
Poniższe przykłady obrazują te przypadki:
- Mniejsze wnioski, które zostały potwierdzone. Interfejs API weryfikacji adresu wykrywa kraj, kod pocztowy lub stan, ale wszystko inne jest podawane i potwierdzane. Połączenie szczegółowości i poziomu potwierdzenia powoduje, że mniejsze wnioskowanie nie wymaga koniecznie potwierdzenia.
- Nieoczekiwany element adresu NIE został potwierdzony. Niepotwierdzone komponenty adresu zwiększają poziom ryzyka związany z adresem. Może to wymagać potwierdzenia.
- Nieoczekiwany element adresu, który został potwierdzony. Ten element nie jest niezbędny do prawidłowego adresu, a interfejs Address Validation API usuwa go z wyjścia. Problemy z formatowaniem zazwyczaj nie wymagają potwierdzenia.
Drobne wnioski, które zostały potwierdzone
Po połączeniu z potwierdzonymi danymi na bardziej szczegółowym poziomie interfejs API może nadal wyciągać poprawne wnioski, jeśli w danych wejściowych brakuje tylko jednego elementu z tych typów:
- Miasto
- Stan
- Kod pocztowy
- Kraj
Klient podaje prawidłowy adres restauracji McDonald's w Springfield w Massachusetts, ale zapomina wpisać nazwę miasta i podaje kod pocztowy bez 4-cyfrowego rozszerzenia.
Adres wpisany | Region |
---|---|
1402 Allen St, MA 01118 | Stany Zjednoczone |
Werdykt dotyczący brakującego miasta
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"addressComplete": true,
"hasInferredComponents": true
}
W sytuacjach, gdy interfejs API do weryfikacji adresów wywnioskuje komponenty wyższego poziomu, aby wygenerować adres dostawy, możesz mieć większą pewność, że dane z systemu są prawidłowe. Dzieje się tak, ponieważ komponenty wywnioskowane, które reprezentują duży obszar geograficzny, są łatwiej dopasowywane do potwierdzonych komponentów adresu, które są bardziej szczegółowe. Nawet w krajach, w których nazwy miast są powtarzane, np. Springfield w Stanach Zjednoczonych, inne komponenty mogą zapewnić unikalny adres.
W naszym przykładzie skanowanie wszystkich elementów adresu wykazuje, że każdy z nich został potwierdzony, co oznacza, że pasuje do danych przechowywanych przez interfejs Address Validation API, a usługa wywnioskowała też 2 elementy wyższego poziomu.
{
"componentName": {
"text": "Springfield",
"languageCode": "en"
},
"componentType": "locality",
"confirmationLevel": "CONFIRMED",
"inferred": true
},
{
"componentName": {
"text": "1806"
},
"componentType": "postal_code_suffix",
"confirmationLevel": "CONFIRMED",
"inferred": true
}
Nieoczekiwany element adresu NIE został potwierdzony
Ten scenariusz pokazuje, jak ważne jest sprawdzanie, czy komponenty nie zostały potwierdzone. Jeśli element adresu jest nieoczekiwany, interfejs Address Validation API usuwa go z wyjścia. W takich przypadkach możesz zaakceptować adres lub potwierdzić go u klienta w zależności od poziomu ryzyka i poziomu zaufania.
Adres może na przykład pochodzić z regionu, w którym klienci często podają nieszkodliwe informacje ignorowane przez urząd pocztowy. W takim przypadku akceptujesz adres. W niektórych przypadkach jednak niepotwierdzony komponent może nie być tym, czego oczekuje klient.
Adres został wpisany | Region |
---|---|
1 Rue Grenache, la caritat 2, 34630 Saint-Thibéry | Francja |
Werdykt dotyczący nieoczekiwanego elementu adresu, który nie został potwierdzony
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE",
"unconfirmedComponents": true
}
Oprócz werdyktu z niepotwierdzonymi komponentami interfejs Address Validation API zwraca sformatowany adres w takiej postaci:
"formattedAddress": "1 Rue Grenache, 34630 Saint-Thibéry, France",
Skanowanie pod kątem niezweryfikowanych komponentów wykazało, że interfejs API usunął la caritat 2 z adresu zwracanego:
{
"componentName": {
"text": "la caritat 2",
"languageCode": "fr"
},
"componentType": "sublocality_level_1",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
"unexpected": true
}
Nieoczekiwany element adresu, który został potwierdzony
Ten przykład pokazuje, jak w podanym adresie uwzględnić hrabstwo w Wielkiej Brytanii, co jest powszechną praktyką. Nie jest to jednak wymagane przez brytyjskie władze pocztowe i jest w zasadzie ignorowane. Zobacz postoffice.co.uk i Jak adresować przesyłki do Wielkiej Brytanii i na cały świat.
W rezultacie, gdy klient podaje hrabstwo w adresie w Wielkiej Brytanii, usługa ocenia to jako nieoczekiwane dane wejściowe.
Adres został wpisany | Region |
---|---|
33 Dunalley St, Cheltenham, Gloucestershire, GL50 4AP | Wielka Brytania |
Werdykt dotyczący nieoczekiwanego elementu adresu, który został potwierdzony
{
"inputGranularity": "PREMISE",
"validationGranularity": "PREMISE",
"geocodeGranularity": "PREMISE"
}
Tutaj wyrażenie address_complete
przyjmuje wartość false, a analiza elementu adresu ujawnia nieoczekiwany znacznik.
{
"componentName": {
"text": "Gloucestershire",
"languageCode": "en"
},
"componentType": "administrative_area_level_2",
"confirmationLevel": "CONFIRMED",
"unexpected": true
}
Gloucestershire to prawidłowy okręg dla podanego adresu, ale sam adres jest nieprawidłowo sformatowany. Pamiętaj, że interfejs Address Validation API sprawdza też, czy dane są prawidłowo sformatowane.