Odpowiedź na podstawowe informacje o weryfikacji adresu

Interfejs Address Validation API zwraca treść 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. Więcej informacji o responseID znajdziesz w artykule Obsługa zaktualizowanych adresów.

Usługa verdict

Właściwość verdict podsumowuje wyniki weryfikacji 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 wyjściowego. Na przykład poniżej przedstawiono właściwość verdict adresu o dobrej jakości, która w przypadku tego konkretnego żądania zwraca 4 pola:

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

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

Możliwe następne działanie

Właściwość possibleNextAction zawiera interpretacyjne podsumowanie pozostałej części odpowiedzi interfejsu API. Ma ono pomóc Ci określić, czy należy poprosić klienta o sprawdzenie lub edytowanie adresu. Więcej informacji znajdziesz w artykule Tworzenie logiki weryfikacji.

Szczegółowość adresu

Granularność adresu odnosi się do poziomu szczegółowości użytego do określenia precyzyjności adresu lub geokodu. Szczegółowość adresu w odpowiedzi validationGranularityjest kluczowym sygnałem wskazującym, czy adres jest prawidłowy.

Właściwość verdict zwraca te sygnały dotyczące szczegółowości:

• inputGranularity – opisuje poziom szczegółowości danych pobranych z adresu wysłanego do interfejsu Address Validation API. Poziom szczegółowości adresu w żądaniu wpływa na poziom szczegółowości adresu w odpowiedzi weryfikacyjnej. Na przykład adres z inputGranularity poniżej PREMISE poniżej poziomu zwykle nie powoduje przejścia z 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 na wysokiej jakości adres, który prawdopodobnie jest prawidłowy.
• geocodeGranularity – opisuje poziom szczegółowości geokodu powiązanego z adresem. Na przykład w dokumentach Google może być podany numer mieszkania, ale nie jego dokładna lokalizacja w dużym kompleksie budynków. W tym przypadku validationGranularity to SUB_PREMISE, ale geocodeGranularityisPREMISE`.

Kompletność adresu

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

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

Jeśli w adresie brakuje komponentów, są one nierozwiązane lub nieoczekiwane, pole jest ustawione na false.

Jakość adresu

Szereg możliwych pól wskazuje problemy ze składnikami adresu lub ich korekty, takie jak wywnioskowane 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 zawiera formatowanie przetworzonego adresu podanego w żądaniu, a także podsumowania adresu na poziomie komponentów, w tym błędnie napisane części adresu, zastąpione nieprawidłowe części i wywnioskowane brakujące części.

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

Usługa geocode

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

Usługa metadata

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

Usługa uspsData

Ta właściwość zawiera przydatne informacje o adresach pocztowych w Stanach Zjednoczonych. Nie gwarantujemy jednak, że w przypadku każdego adresu zweryfikowanego przez usługę będzie on w pełni wypełniony. Z tego powodu nie należy polegać na tej właściwości jako jedynym sposobie weryfikacji adresów, ale sprawdzać też verdict i address.