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, obiekt typu ValidationResult
• responseID

{
  "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 responseID znajdziesz w artykule Przetwarzanie zaktualizowanych adresów.

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
}

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

Szczegółowość adresu

Dokładność adresu odnosi się do poziomu szczegółowości używanego do określania dokładności adresu lub geokodu. Szczegółowość adresu w odpowiedzi validationGranularity jest 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 zweryfikowanego adresu. Na przykład adres z wartością inputGranularity poniżej poziomu PREMISE zwykle nie powoduje zmiany poziomu validationGranularity na 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 rekordy Google mogą wskazywać na istnienie mieszkania, ale nie podają dokładnej lokalizacji tego mieszkania w ramach dużego kompleksu mieszkaniowego. W takim przypadku validationGranularity to SUB_PREMISE, ale geocodeGranularity to isPREMISE`.

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
}

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

Jakość adresu

Niektóre możliwe pola wskazują na problemy z elementami adresu lub ich korekty, takie jak 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
}

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.

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

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.

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.

Właściwość uspsData

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