Potwierdź adres – przykłady

W tym dokumencie opisujemy kilka rzeczywistych scenariuszy, w których interfejs Address Validation API zwraca sygnały odpowiedzi dla adresów, które mogą wymagać od systemu zachowania potwierdzającego. Więcej informacji znajdziesz w sekcji Przykładowe przepływy pracy w artykule Tworzenie logiki weryfikacji.

Typowe przykłady: potwierdzenie

Poniższy przykład ilustruje przypadek obszarów metropolitalnych o podobnych nazwach ulic. Załóżmy, że użytkownik chce wpisać adres budynku D Google w Kirkland w stanie Waszyngton w Stanach Zjednoczonych. Jednak zamiast Kirkland jako miasta nieumyślnie wpisują Seattle.

Wpisano adres Region
Building D, 451 7th Avenue South, Seattle, WA 98033 US

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,
  "possibleNextAction": "CONFIRM"
}

Symbol possibleNextAction wskazuje, że warto potwierdzić adres u klienta. Pozostałe sygnały w wyniku zawierają więcej szczegółów o tym, co może być nie tak z adresem. Symbol PREMISE_PROXIMITY oznacza przybliżenie adresu na poziomie budynku, ale nie jest tak szczegółowy jak SUB_PREMISE, czyli poziom szczegółowości podany na wejściu. Odpowiedź zawiera też niepotwierdzone i zastąpione komponenty.

Zapytanie dotyczące komponentów adresu ujawnia te obszary problemowe:

{
  "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ł zbliżony adres w Seattle i zastąpił kod pocztowy, czyli komponent wyższego poziomu, aby uzyskać adres w Seattle. Może to być prawidłowe zastąpienie, ale w połączeniu z faktem, że komponenty nie zostały potwierdzone, warto upewnić się, że użytkownik chce wpisać adres w Seattle, a nie w innym mieście, np. w Kirkland.

Przykłady przypadków granicznych: potwierdź

Poniższe przykłady ilustrują te typy przypadków brzegowych:

Drobne wnioski, które są potwierdzone

W połączeniu z potwierdzonymi danymi o większej szczegółowości interfejs API może nadal wyciągać prawidłowe wnioski, jeśli w danych wejściowych brakuje tylko jednego komponentu z tych typów:

  • Miasto
  • Stan
  • Kod pocztowy
  • Kraj

Na przykład klient podaje prawidłowy adres ulicy restauracji McDonald's w Springfield w stanie Massachusetts, ale zapomina wpisać nazwę miasta i podaje kod pocztowy bez 4-cyfrowego rozszerzenia.

Wpisano adres Region
1402 Allen St, MA 01118 US

Werdykt w przypadku braku miasta

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true,
  "hasInferredComponents": true,
  "possibleNextAction": "CONFIRM"
}

W sytuacjach, w których interfejs Address Validation API wnioskuje o składnikach wyższego poziomu, aby uzyskać adres dostawy, możesz mieć większą pewność, że dane z systemu są prawidłowe. Dzieje się tak, ponieważ wywnioskowane komponenty reprezentujące szeroki region geograficzny są łatwiej dopasowywane do potwierdzonych komponentów adresu, które są bardziej szczegółowe. Nawet w krajach, w których nazwy miast się powtarzają, np. Springfield w Stanach Zjednoczonych, pozostałe elementy adresu mogą w połączeniu z nią tworzyć unikalny adres.

W naszym przykładzie skanowanie wszystkich komponentów adresu pokazuje, że każdy z nich jest potwierdzony, co oznacza, że pasuje do danych przechowywanych przez interfejs Address Validation API. Usługa wywnioskowała też 2 komponenty 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 komponent adresu NIE został potwierdzony

Ten scenariusz pokazuje, jak ważne jest sprawdzanie, kiedy komponenty nie są potwierdzone. Jeśli składnik adresu jest nieoczekiwany, interfejs Address Validation API usuwa go z danych wyjściowych. W takich przypadkach możesz zaakceptować adres lub ponownie potwierdzić go z klientem, w zależności od poziomu ryzyka i pewności.

Na przykład adres może pochodzić z regionu, w którym klienci często wpisują nieszkodliwe informacje ignorowane przez urząd pocztowy. W takim przypadku możesz zaakceptować adres. Jednak w niektórych przypadkach niepotwierdzony komponent może nie spełniać oczekiwań klienta.

Wpisano adres Region
59 Cherrydown Avenue, Chingford, Londyn E4 8DT Wielka Brytania

Werdykt dotyczący nieoczekiwanego komponentu adresu nie został potwierdzony

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "unconfirmedComponents": true,
  "possibleNextAction": "ACCEPT"
}

Oprócz wyniku z niepotwierdzonymi komponentami interfejs Address Validation API zwraca sformatowany adres:

"formattedAddress": "59 Cherrydown Avenue, London E4 8DT, UK",

Skanowanie niepotwierdzonych komponentów pokazuje, że interfejs API usunął z zwróconego adresu element Chingford:

{
  "componentName": {
    "text": "Chingford",
    "languageCode": "en"
  },
  "componentType": "sublocality_level_1",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
  "unexpected": true
}

Nieoczekiwany komponent adresu, który JEST potwierdzony

Ten przykład ilustruje uwzględnienie w podanym adresie hrabstwa w Wielkiej Brytanii, co jest powszechną praktyką. Nie jest to jednak wymagane przez brytyjską pocztę i jest w zasadzie ignorowane. Zobacz postoffice.co.uk i How to address UK and international mail (Jak zaadresować pocztę w Wielkiej Brytanii i za granicą).

W rezultacie, gdy klient poda hrabstwo w adresie w Wielkiej Brytanii, usługa uzna to za nieoczekiwane dane wejściowe.

Wpisano adres Region
33 Dunalley St, Cheltenham, Gloucestershire, GL50 4AP Wielka Brytania

Wynik dla nieoczekiwanego komponentu adresu, który został potwierdzony

{
   "inputGranularity": "PREMISE",
   "validationGranularity": "PREMISE",
   "geocodeGranularity": "PREMISE",
   "possibleNextAction": "ACCEPT"
}

W tym przypadku funkcja address_complete zwraca wartość false, a analiza komponentu adresu ujawnia nieoczekiwany flag.

{
  "componentName": {
    "text": "Gloucestershire",
    "languageCode": "en"
  },
  "componentType": "administrative_area_level_2",
  "confirmationLevel": "CONFIRMED",
  "unexpected": true
}

Gloucestershire to prawidłowe hrabstwo dla podanego adresu, ale sam adres jest nieprawidłowo sformatowany. Pamiętaj, że interfejs Address Validation API sprawdza też, czy informacje mają prawidłowy format.