Odpowiedź na podstawowe informacje o weryfikacji adresu

Odpowiedź interfejsu Address Validation API zawiera te właściwości najwyższego poziomu:

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // 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"
}

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 podano podsumowanie wszystkich pól właściwości verdict.

W przewodniku znajdziesz informacje o werdunku.

Szczegółowość adresu

Dokładność adresu odnosi się do poziomu szczegółowości używanego do określania dokładności adresu lub kodu geograficznego. Szczegóły adresu w odpowiedzi validationGranularity to kluczowy sygnał dotyczący tego, 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 adresu wysłanego do usługi walidacji adresu w interfejsie Maps JavaScript API. Poziom szczegółowości adresu w żądaniu 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 weryfikacja adresu w interfejsie Maps JavaScript 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 mieszkania, ale nie jego dokładną lokalizację w ramach dużego kompleksu mieszkaniowego. W takim przypadku validationGranularity to SUB_PREMISE, a geocodeGranularity to PREMISE.
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, np. 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 na temat werdunku 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.

Więcej informacji znajdziesz w sekcji Address w przewodniku.

Właściwość addressComponent jest podelementem address, który zawiera szczegółową listę elementów lub komponentów adresu, które zostały przetworzone przez walidację adresu w interfejsie Maps JavaScript API. Interfejs API identyfikuje każde pole komponentu według nazwy, typu i poziomu potwierdzenia.

Więcej informacji znajdziesz w sekcji addressComponent w przewodniku.

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.

Więcej informacji znajdziesz w sekcji Geocode w przewodniku.

Właściwość metadata

Ta właściwość może nie być wypełniona w przypadku każdego adresu przetworzonego przez walidację adresu w interfejsie Maps JavaScript API, ale wskazuje, czy adres jest typu mieszkalny, firmowy czy skrytka pocztowa.

Zapoznaj się z zasięgiem interfejsu Address Validation API oraz z 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 wszystkie adresy weryfikowane przez usługę będą w pełni wypełnione. 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.