Potwierdź adres – przykłady

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:

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.