Interfejs Address Validation API udostępnia treść odpowiedzi w postaci obiektu JSON, który zawiera 2 właściwości najwyższego poziomu:
result
, obiekt typuValidationResult
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 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 zinputGranularity
niższym niżPREMISE
poziomem zwykle nie prowadzi do poziomuvalidationGranularity
na poziomPREMISE
.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ściPREMISE
lubSUB_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 przypadkuvalidationGranularity
ma wartośćSUB_PREMISE
, alegeocodeGranularity
is
PREMISE`.
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 .
|