Odpowiedź na podstawowe informacje o weryfikacji adresu

Interfejs API weryfikacji adresów dostarcza elementu treści odpowiedzi w postaci obiektu JSON, który zawiera 2 właściwości najwyższego poziomu:

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

Ten dokument dotyczy obiektu result. Informacje o funkcji responseID znajdziesz w artykule Zarządzanie zaktualizowanymi adresami.

Właściwość verdict

Właściwość verdict podsumowuje wyniki walidacji adresu i powinna być pierwszą właściwością, którą należy ocenić podczas tworzenia logiki sprawdzania adresu. Właściwość może zwracać różne pola w zależności od jakości adresu docelowego. Na przykład poniżej pokazano właściwość verdict adresu o dobrej jakości, która zwraca 4 pola dla tego konkretnego żądania:

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

W następnych sekcjach podano podsumowanie wszystkich pól właściwości verdict.

Więcej informacji znajdziesz w sekcji Werdykt w przewodniku.

Możliwe dalsze działania

Właściwość possibleNextAction zawiera interpretacyjne podsumowanie reszty odpowiedzi interfejsu API, aby pomóc Ci określić, czy należy poprosić klienta o sprawdzenie lub zmodyfikowanie adresu. Więcej informacji znajdziesz w artykule Tworzenie logiki walidacji.

Szczegółowość adresu

Dokładność adresu odnosi się do poziomu szczegółowości używanego do określania dokładności adresu lub kodu geograficznego. Szczegóły adresu w odpowiedzi validationGranularity są kluczowym sygnałem wskazującym, czy adres jest prawidłowy.

Właściwość verdict zwraca te sygnały o wysokiej szczegółowości:

  • inputGranularity – określa poziom szczegółowości danych adresu wysłanego do interfejsu Address Validation API. Poziom szczegółowości adresu w prośbie wpływa na poziom szczegółowości adresu w odpowiedzi z weryfikacji. Na przykład adres z wartością inputGranularity poniżej poziomu PREMISE zwykle nie powoduje zmiany z poziomu validationGranularity na poziom PREMISE.
  • validationGranularity – poziom szczegółowości, na którym interfejs Address Validation API może w pełni zweryfikować adres. W większości przypadków poziom szczegółowości PREMISE lub SUB_PREMISE wskazuje adres o wysokiej jakości, który prawdopodobnie można dostarczyć.
  • geocodeGranularity – określa poziom szczegółowości powiązanego z adresem geokodu. Na przykład dane Google mogą wskazywać na istnienie mieszkania, ale nie jego dokładnej lokalizacji w ramach dużego kompleksu mieszkaniowego. W takim przypadku validationGranularity to SUB_PREMISE, ale geocodeGranularity to isPREMISE`.
Więcej informacji znajdziesz w sekcji Dokładność w przewodniku.

Kompletność adresu

Werdykt zwraca właściwość addressComplete jako sygnał o adresie o wysokiej jakości, co oznacza, że nie ma w nim brakujących, nierozwiązanych ani nieoczekiwanych komponentów:

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

Jeśli adres zawiera brakujące, nierozwiązane lub nieoczekiwane komponenty, pole ma wartość false.

W przewodniku addressComplete w sekcji Wyrok i Adres.

Jakość adresu

Niektóre możliwe pola wskazują na problemy z elementami adresu lub ich korekty, np. brakujące lub wywnioskowane elementy adresu. Na przykład ta właściwość verdict wskazuje adres z niepotwierdzonymi komponentami i brakującym polem addressComplete:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
Więcej informacji o werdowaniu znajdziesz w przewodniku.

Właściwości address i addressComponent

Właściwość address zapewnia formatowanie przetworzonego adresu podanego w żądaniu wraz z podsumowaniem adresu na poziomie komponentu, w tym części adresu z błędami pisowni, zastąpione części z błędami i wywnioskowane brakujące części.

Więcej informacji znajdziesz w sekcji Address w przewodniku.

Właściwość addressComponent jest podelementem address, który zawiera szczegółową listę elementów lub komponentów adresu przetworzonego przez interfejs Address Validation API. Interfejs API identyfikuje każde pole komponentu na podstawie jego nazwy, typu i poziomu potwierdzenia.

Więcej informacji znajdziesz w sekcji addressComponent w przewodniku.

Właściwość geocode

Właściwość geocode wskazuje zgeokodowaną lokalizację powiązaną z podanym adresem. Ta właściwość zawiera informacje o samej lokalizacji, takie jak identyfikator miejsca.

Więcej informacji znajdziesz w sekcji Geocode w przewodniku.

Właściwość metadata

Ta właściwość może nie być wypełniona w przypadku każdego adresu przetworzonego przez interfejs API do weryfikacji adresów, ale wskazuje, czy adres jest adresem zamieszkania, firmy czy skrytki pocztowej.

Zapoznaj się z zasięgiem interfejsu Address Validation API i dokumentacją dotyczącą Address metadata.

Właściwość uspsData

Ta usługa dostarcza przydatnych informacji o adresach pocztowych w Stanach Zjednoczonych. Nie możemy jednak zagwarantować, że w przypadku każdego adresu zweryfikowanego przez usługę dane będą w pełni wypełnione. Z tego powodu nie należy polegać na tej usłudze jako na jedynym sposobie sprawdzania adresów. Należy też sprawdzić właściwości verdict i address.

Zapoznaj się z artykułem Praca z adresami w Stanach Zjednoczonych i informacjami o UspsData.
Wstecz
Wysyłanie prośby o weryfikację adresu
Dalej
Opracuj logikę weryfikacji