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 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.

Więcej informacji znajdziesz w sekcji Verdict w przewodniku.

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`.
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
}

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

W przewodniku addressComplete znajdziesz informacje o Verdict i adresie.

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
}
Więcej informacji o Verdict 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.

W przewodniku znajdziesz informacje o Address.

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 przewodniku znajdziesz informacje o addressComponent.

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 przewodniku znajdziesz informacje o Geocode.

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 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.

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