Odpowiedź na podstawowe informacje o weryfikacji adresu

Interfejs Address Validation API udostępnia treść odpowiedzi w postaci pliku 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 na temat responseID, więcej informacji znajdziesz w sekcji Obsługa 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 widać właściwość verdict elementu adresu o dobrej jakości, który zwraca dla tego konkretnego żądania 4 pola:

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

W poniższych sekcjach znajdziesz podsumowanie wszystkich pól we właściwości verdict.

szczegółowość adresu,

Szczegółowość 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 to kluczowy sygnał dotyczący tego, 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 rejestrowanych danych wysłany do interfejsu Address Validation API. Poziom szczegółowości adresu w wpływa na poziom szczegółowości adresu w odpowiedzi weryfikacyjnej. Na przykład adres z wartością inputGranularity poniżej PREMISE poziom zwykle nie skutkuje uzyskaniem wyniku od validationGranularity do PREMISE na poziomie 300%.
• validationGranularity – poziom szczegółowości 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

Wynik zwraca właściwość addressComplete jako sygnał dla wysokiej jakości, czyli zawierają wszystkie niezbędne informacje, nierozstrzygnięte lub nieoczekiwane komponenty:

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

Jeśli w adresie brakuje, nierozstrzygnięte lub nieprawidłowe komponenty, pole ma wartość false.

Jakość adresu

Wiele możliwych pól oznacza problemy z komponentami adresu lub ich korekty, na przykład domniemane lub brakujące składniki 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 umożliwia formatowanie przetworzonego adresu podanego w wraz z podsumowaniem na poziomie komponentu adresu, w tym błędnie napisane części adresu, zastąpiono nieprawidłowe części oraz domniemane brakujące elementy; części składowych.

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 Address Validation API, ale wskazuje, czy adres jest typu mieszkalny, firmowy czy skrytka pocztowa.

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 właściwości jako na potrzeby weryfikacji adresów, ale zamiast tego sprawdź verdict i address.