Potwierdź adres – przykłady

W tym dokumencie opisujemy kilka rzeczywistych sytuacji, w których interfejs Address Validation API dostarcza sygnały odpowiedzi dla adresów, które zapewniają potwierdzenie działania systemu. Kontekst znajdziesz w artykule Omówienie przepływu pracy w artykule Tworzenie logiki weryfikacji.

Uwaga: podane tu przykłady mają charakter poglądowy, ale nie są wyczerpujące.

Typowe przykłady: potwierdzenie

Poniższy przykład ilustruje przypadek obszarów metropolitalnych z podobnymi nazwami ulic. Załóżmy, że użytkownik chce wpisać adres budynku Google D w Kirkland (Warszawie, USA). Zamiast jednak Kirkland jako miasto, zostają one przypadkowo wprowadzone do Seattle.

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

Efekt zastąpienia danych

Poniższy przykład przedstawia ważne sygnały z odpowiedzi.

{
  "inputGranularity": "SUB_PREMISE",
  "validationGranularity": "PREMISE_PROXIMITY",
  "geocodeGranularity": "PREMISE_PROXIMITY",
  "addressComplete": true,
  "hasUnconfirmedComponents": true
  "hasReplacedComponents": true
}

Pole PREMISE_PROXIMITY wskazuje blisko adresu na poziomie budynku, ale nie jest tak szczegółowe jak SUB_PREMISE, czyli poziom szczegółowości danych wejściowych. Odpowiedź zawiera też niepotwierdzone i zastąpione komponenty, dlatego kombinacja ta uwzględnia te elementy w kategorii confirm (potwierdź).

Zapytanie dotyczące komponentów adresu dostarcza tych obszarów problemu:

{
  "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żone przybliżenie do podanego adresu w Seattle i zastąpił kod pocztowy (komponent wyższego poziomu) na adres w Seattle. Może to być prawidłowe zamiennik, ale w związku z tym, że elementy nie zostały potwierdzone, warto upewnić się, że użytkownik wpisuje adres w Krakowie, a nie coś innego, np. w Krakowie.

Wskazówka: sprawdź w pokazie prawidłowy adres, używając adresu 451 7th Avenue South, Kirkland, WA 98033, aby zobaczyć odpowiedź dotyczącą pierwotnego adresu.

Działanie: potwierdź adres klienta.

Przykłady przypadków skrajnych: potwierdź

Poniższe przykłady ilustrują następujące skrajne wielkości liter:

• Drobne wnioskowania, które ZOSTAŁY potwierdzone. Interfejs Address Validation API ustala kraj, kod pocztowy lub stan, ale wszystkie pozostałe informacje są podawane i potwierdzone. Połączenie szczegółowości i poziomu potwierdzenia umożliwia niewielkie wywnioskowanie, które nie wymaga potwierdzenia działania.
• Nieoczekiwany składnik adresu NIE potwierdzono. Niepotwierdzone komponenty adresu zwiększają ryzyko związane z adresem. Może to wymagać potwierdzenia.
• Nieoczekiwany komponent adresu, który został potwierdzony. Komponent nie jest wymagany do poprawnego adresu, a interfejs Address Validation API usuwa go z danych wyjściowych. Problemy z formatowaniem zwykle nie wymagają potwierdzenia.

Drobne wnioski, które ZOSTAŁY potwierdzone

W połączeniu z potwierdzonymi danymi na bardziej szczegółowym poziomie interfejs API może nadal generować prawidłowe wnioskowanie, jeśli brakuje w nich tylko jednego komponentu tych typów:

• Miasto
• Stan
• Kod pocztowy
• Kraj

Przykład: klient podaje prawidłowy adres restauracji McDonald's w Warszawie, ale zapomni podać nazwę miasta i musi podać kod pocztowy bez rozszerzenia czterocyfrowego.

Wpisano adres	Region
1402 Allen St, MA 01118, USA	Stany Zjednoczone

Wniosek dotyczący zaginięcia miasta

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

W sytuacjach, gdy interfejs Address Validation API ustala komponenty wyższego poziomu, aby uzyskać adres do dostarczenia, możesz mieć większą pewność, że dane z systemu są prawidłowe. Dzieje się tak, ponieważ domniemane komponenty, które reprezentują 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ą, jak np. Springfield w Stanach Zjednoczonych, inne składniki w połączeniu z nią mogą zapewniać unikalny adres.

W naszym przykładzie skanowanie wszystkich komponentów adresu pokazuje, że każdy składnik został potwierdzony, co oznacza, że pasuje on do danych przechowywanych przez interfejs Address Validation API, a usługa wykorzystuje 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
}

Działanie: Zaakceptuj. Takie adresy zapewniają wystarczająco potwierdzony poziom szczegółowości, a także potwierdza wywnioskowane komponenty, aby Twój system logiczny mógł je zaakceptować jako prawidłowe bez konieczności pytania klienta.

Nieoczekiwany składnik adresu NIE potwierdzono

Ten scenariusz pokazuje, jak ważne jest sprawdzenie, gdy komponenty nie są potwierdzone. Jeśli komponent adresu jest nieoczekiwany, interfejs Address Validation API usuwa go z danych wyjściowych. W takiej sytuacji możesz zaakceptować adres lub potwierdzić go u klienta w zależności od poziomu ryzyka i pewności.

Może to być na przykład adres z regionu, w którym klienci często wpisują szkodliwe informacje ignorowane przez urząd pocztowy. W takim przypadku możesz zaakceptować ten adres. Jednak w niektórych przypadkach elementy, które nie są potwierdzone, mogą nie być zadowalające.

Wpisano adres	Region
1 Rue Grenache, la caritat 2, 34630 Saint-Thibéry	Francja

Decyzja dotycząca nieoczekiwanego składnika adresu nie została potwierdzona

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

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

"formattedAddress": "1 Rue Grenache, 34630 Saint-Thibéry, France",

Skanowanie w poszukiwaniu niepotwierdzonych komponentów pokazuje, że interfejs API usunął ze zwróconego adresu la caritat 2:

{
  "componentName": {
    "text": "la caritat 2",
    "languageCode": "fr"
  },
  "componentType": "sublocality_level_1",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
  "unexpected": true
}

Działanie: potwierdź. W tym przypadku podrejon, który może wskazywać na dzielnicę mieszkaniową lub dzielnicę, może być prawidłowy, ale nadal ignorowany przez urząd pocztowy. Ponieważ jednak te informacje **nie** zostały potwierdzone przez interfejs Address Validation API, warto to potwierdzić z klientem. W tym momencie musisz zignorować proces usuwania treści lub je potwierdzić.

Nieoczekiwany komponent adresu, który został potwierdzony

Ten przykład pokazuje, że w podanym adresie podano kraj w Wielkiej Brytanii, co jest częste. Nie jest to jednak wymagane przez brytyjski urząd pocztowy i zasadniczo jest to zignorowane. Więcej informacji znajdziesz na stronie postoffice.co.uk i artykuł o adresowaniu poczty w Wielkiej Brytanii i międzynarodowej.

W efekcie gdy klient poda kraj 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 nieoczekiwanego komponentu adresu, który został potwierdzony

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

W tym przypadku address_complete zwraca wartość fałsz, a analiza składnika adresu wykrywa nieoczekiwaną flagę.

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

Ten komponent jest nieoczekiwany i potwierdzony, co oznacza, że:

• Potwierdzono jako prawidłowe dane. Wskazuje on, że komponent to właściwe hrabstwo zawierające adres.
• Nieoczekiwane jako dane wejściowe. Wskazuje, że komponent nie jest wymagany do prawidłowego formatowania adresu.

Gloucestershire jest prawidłowym krajem w przypadku wpisanego adresu, ale sam adres jest nieprawidłowo sformatowany. Warto pamiętać, że interfejs Address Validation API również ocenia informacje pod kątem prawidłowego formatowania.

Działanie: w tym przypadku zalecamy zignorowanie tego sygnału i zaakceptowanie adresu.