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, 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 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ścią, która zostanie sprawdzona podczas sprawdzania logiki adresu. Właściwość może zwracać różne pola w zależności od jakości adresu wyjściowego. 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 poniższych sekcjach znajdziesz podsumowanie wszystkich pól we właściwości verdict.

Zapoznaj się z wynikiem w przewodniku.

szczegółowość adresu,

Szczegółowość adresu odnosi się do poziomu szczegółowości używanego do określania szczegółowości adresu lub kodu geograficznego. Konkretny adres w odpowiedzi validationGranularity to kluczowy sygnał, czy adres można dostarczyć.

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

• inputGranularity – określa poziom szczegółowości przechwytywanych z adresu przesłanego do interfejsu Address Validation API. Poziom szczegółowości adresu w żądaniu wpływa na poziom szczegółowości adresu w odpowiedzi na weryfikację. Na przykład adres z wartością inputGranularity poniżej PREMISE zwykle nie skutkuje uzyskaniem wartości validationGranularity na poziomie 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 wysokiej jakości adres, który prawdopodobnie zostanie dostarczony.
• 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 jego dokładną lokalizację w dużym kompleksie mieszkalnym. W takim przypadku validationGranularity to SUB_PREMISE, ale geocodeGranularityisPREMIUM.

Zapoznaj się z informacjami o szczegółowości w przewodniku.

Kompletność adresu

Wynik zwraca właściwość addressComplete jako sygnał dla wysokiej jakości adresu, co oznacza, że nie zawiera on ż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ą nierozwiązane lub nieoczekiwane, pole jest ustawione na false.

Zobacz addressComplete w sekcjach Wynik i Adres w przewodniku.

Jakość adresu

Wiele możliwych pól oznacza problemy z komponentami adresu lub korekty tych elementów, np. domniemane lub brakujące elementy adresu. Na przykład 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 Wynik w przewodniku.

Właściwości address i addressComponent

Właściwość address umożliwia formatowanie przetworzonego adresu podanego w żądaniu wraz z podsumowaniami na poziomie komponentu adresu, w tym błędnie zapisanymi częściami adresu, zastąpiono nieprawidłowe części i wnioskowane brakujące części.

Zobacz Address w przewodniku.

Właściwość addressComponent jest komponentem podrzędnym klasy 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 komponentów według nazwy, typu i poziomu potwierdzenia.

Zobacz addressComponent w przewodniku.

Właściwość geocode

Właściwość geocode wskazuje geokodowaną lokalizację powiązaną z podanym adresem. Ta właściwość zawiera informacje o samej lokalizacji, np. identyfikator miejsca.

Zobacz 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 należy do typu zamieszkania, firmy czy skrytki pocztowej.

Zapoznaj się z sekcją Zasięg interfejsu API do weryfikacji adresów i informacjami o Address metadata.

Właściwość uspsData

Ta usługa zawiera przydatne informacje dotyczące adresów 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 sekcją Obsługa adresów w Stanach Zjednoczonych i informacjami o UspsData.