Odpowiedź na podstawowe informacje o weryfikacji adresu

Interfejs Address Validation API udostępnia treść 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 skupia się na obiekcie result. Informacje na temat responseID znajdziesz w sekcji Obsługa zaktualizowanych adresów.

Właściwość verdict

Właściwość verdict podsumowuje wyniki weryfikacji adresu i powinna być pierwszą właściwość do oceny przy tworzeniu logiki sprawdzania adresu. W zależności od jakości adresu wyjściowego właściwość może zwracać różne pola. Na przykład poniżej widać właściwość verdict adresu o dobrej jakości, która zwraca 4 pola w przypadku tego konkretnego żądania:

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

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

Przeczytaj Decyzję w przewodniku.

Szczegółowość adresu

Szczegółowość adresu odnosi się do poziomu szczegółowości adresu lub geokodu. Szczegółowe informacje o adresie w odpowiedzi validationGranularity są kluczowym sygnałem informującym o tym, czy adres zostanie dostarczony.

Usługa verdict zwraca te sygnały dotyczące szczegółowości:

  • inputGranularity – opisuje poziom szczegółów przechwytywanych z adresu wysłanego do interfejsu Address Validation API. Poziom szczegółów adresu w prośbie wpływa na poziom szczegółowości adresu w odpowiedzi w celu weryfikacji. Na przykład adres z inputGranularity niższym niż PREMISE poziomem zwykle nie prowadzi do poziomu validationGranularity na poziom PREMISE.
  • validationGranularity – poziom szczegółowości, na który 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 wysokiej jakości, który prawdopodobnie będzie możliwy do zrealizowania.
  • geocodeGranularity – określa poziom szczegółowości geokodu powiązanego z adresem. Na przykład dane Google mogą wskazywać na istnienie numeru mieszkania, ale nie mogą wskazywać dokładnej lokalizacji tego konkretnego apartamentu w dużym kompleksie mieszkalnym. W tym przypadku validationGranularity ma wartość SUB_PREMISE, ale geocodeGranularityisPREMISE`.
Zapoznaj się z informacjami o szczegółowości w przewodniku.

Kompletność adresu

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

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

Jeśli w adresie brakuje komponentów, które są nierozstrzygnięte lub nieoczekiwane, pole ma wartość false.

Więcej informacji znajdziesz w sekcji addressComplete w sekcjach Wynik i Adres w przewodniku.

Jakość adresu

Kilka możliwych pól wskazuje problemy ze składnikami adresu lub ich korekty, np. wynikające z domniemanej lub brakującej części 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
}
Przeczytaj artykuł Decyzja w przewodniku.

Właściwości address i addressComponent

Właściwość address umożliwia formatowanie przetworzonego adresu podanego w żądaniu, a także podsumowania na poziomie komponentu, w tym błędne części adresu, zastąpione nieprawidłowe części i domniemane brakujące części.

Przeczytaj artykuł Address w przewodniku.

Właściwość addressComponent jest komponentem podrzędnym address, który zawiera szczegółową listę elementów (lub komponentów) adresu przetworzonego przez interfejs Address Validation API. Interfejs API identyfikuje poszczególne pola komponentu według nazwy, typu i poziomu potwierdzenia.

Przeczytaj artykuł addressComponent w przewodniku.

Właściwość geocode

Właściwość geocode wskazuje lokalizację geograficzną powiązaną z adresem wejściowym. Właściwość ta zawiera szczegółowe informacje o lokalizacji, np. identyfikator miejsca.

Przeczytaj artykuł Geocode w przewodniku.

Właściwość metadata

Ta właściwość może nie być wypełniona w przypadku niektórych adresów przetwarzanych przez interfejs Address Validation API, ale wskazuje, czy adres jest adresem zamieszkania, firmy czy skrytki pocztowej.

Zobacz zasięg interfejsu Address Validation API i dokumentację dotyczącą Address metadata.

Właściwość uspsData

Ta właściwość zawiera przydatne informacje dotyczące adresów pocztowych w Stanach Zjednoczonych. Nie ma jednak gwarancji, że dla każdego adresu potwierdzonego przez usługę wypełniane będą pełne dane. Dlatego nie należy stosować tej właściwości jako jedynej metody sprawdzania adresów, ale lepiej sprawdzać verdict i address.

Zobacz Obsługa adresów w Stanach Zjednoczonych i informacje o UspsData.