Odpowiedź na podstawowe informacje o weryfikacji adresu

Interfejs Address Validation API udostępnia treść odpowiedzi w postaci obiektu JSON z 2 właściwościami 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 na temat responseID 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ższy przykład pokazuje właściwość verdict adresu o dobrej jakości, który zwraca dla tego konkretnego żądania 4 pola:

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

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

Więcej informacji znajdziesz w sekcji Wyrok 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 z weryfikacji. Na przykład adres z wartością inputGranularity poniżej poziomu PREMISE zwykle nie powoduje zmiany z poziomu validationGranularity na poziom 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 dane Google mogą wskazywać na istnienie numeru mieszkania, ale nie jego dokładną lokalizację w dużym kompleksie mieszkalnym. 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 wyroku 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
}
Zobacz Verdict 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 Address Validation API, ale wskazuje, czy adres jest typu mieszkalny, firmowy czy skrytka pocztowa.

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 w przypadku każdego adresu zweryfikowanego przez usługę będzie ono wypełnione w całości. Dlatego nie używaj tej właściwości jako jedynego sposobu weryfikacji adresów. Zamiast tego sprawdź też 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