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 weryfikacji 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 wyjściowego. Na przykład poniżej znajduje się właściwość verdict adresu o dobrej jakości, która zwraca te pola dla tego konkretnego żądania:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

W sekcjach poniżej znajdziesz podsumowanie wszystkich pól we właściwości verdict.

Zobacz Werdykt w przewodniku.

Szczegółowość adresu

Szczegółowość adresu odnosi się do poziomu szczegółowości używanego do określania specyfiki adresu lub kodu geograficznego. Dokładność adresu w odpowiedzi validationGranularity jest kluczowym sygnałem, czy adres jest możliwy do dostarczenia.

Właściwość verdict zwraca te sygnały ziarnistości:

  • inputGranularity – określa poziom szczegółowości danych uzyskanych z adresu wysłanego do interfejsu Weryfikacja adresów w Maps JavaScript API. Poziom szczegółowości adresu w żądaniu wpływa na poziom szczegółowości adresu w odpowiedzi na żądanie weryfikacji. Na przykład adres z inputGranularity poniżej PREMISE poniżej poziomu zwykle nie powoduje validationGranularity do poziomu PREMISE.
  • validationGranularity – poziom szczegółowości, do którego usługa Address Validation w 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 na adres wysokiej jakości, który prawdopodobnie jest możliwy do dostarczenia.
  • geocodeGranularity – opisuje poziom szczegółowości kodu geograficznego powiązanego z adresem. Na przykład w rejestrach Google może znajdować się numer mieszkania, ale nie dokładna lokalizacja tego mieszkania w dużym kompleksie mieszkalnym. W takim przypadku validationGranularity to SUB_PREMISE, ale geocodeGranularity to PREMISE.
Więcej informacji znajdziesz w sekcji Granularity (Szczegółowość) w przewodniku.

kompletność adresu,

Werdykt zwraca właściwość addressComplete jako sygnał, że adres jest wysokiej jakości, co oznacza, że nie brakuje w nim żadnych komponentów, nie ma w nim nierozpoznanych ani nieoczekiwanych komponentów:

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

Jeśli w adresie brakuje komponentów, są one nierozwiązane lub nieoczekiwane, pole ma wartość false.

Zobacz addressComplete w sekcjach Werdykt i Adres w przewodniku.

Jakość adresu

Wiele możliwych pól wskazuje na problemy z komponentami adresu lub ich korektami, np. wnioskowanymi lub brakującymi komponentami 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 Werdykt w przewodniku.

Możliwe następne działanie

Pole possibleNextAction zawiera podsumowanie odpowiedzi interfejsu API, które ma pomóc w określeniu potencjalnych dalszych działań. To pole jest generowane na podstawie innych pól w odpowiedzi interfejsu API i nie powinno być traktowane jako gwarancja dokładności adresu ani możliwości dostarczenia przesyłki.

Właściwości address i addressComponent

Właściwość address zapewnia formatowanie przetworzonego adresu podanego w żądaniu wraz z podsumowaniami adresu na poziomie komponentu, w tym błędnie wpisanymi częściami adresu, zastąpionymi nieprawidłowymi częściami i wywnioskowanymi brakującymi częściami.

Zobacz Address w przewodniku.

Właściwość addressComponent jest podkomponentem właściwości address, który zawiera szczegółową listę elementów lub komponentów adresu przetworzonych przez interfejs Weryfikacja adresów w Maps JavaScript API. Interfejs API identyfikuje każde pole komponentu na podstawie jego nazwy, typu i poziomu potwierdzenia.

Zobacz addressComponent w przewodniku.

Właściwość geocode

Właściwość geocode wskazuje lokalizację z kodem geograficznym powiązaną z adresem wejściowym. Ta właściwość zawiera szczegółowe informacje o samej lokalizacji, np. jej identyfikator miejsca.

Zobacz Geocode w przewodniku.

Właściwość metadata

Ta właściwość może nie być wypełniona w przypadku każdego adresu przetwarzanego przez Address Validation w Maps JavaScript API, ale wskazuje, czy adres jest adresem domowym, firmowym czy skrytką pocztową.

Zobacz Zasięg Address Validation API i dokumentację Address metadata.

Właściwość uspsData

Ta właściwość zawiera przydatne informacje o adresach pocztowych w Stanach Zjednoczonych. Nie ma jednak gwarancji, że będzie on w pełni wypełniony w przypadku każdego adresu zweryfikowanego przez usługę. Z tego powodu nie należy polegać na tej właściwości jako jedynym sposobie sprawdzania poprawności adresów, ale należy też sprawdzić verdict i address.

Zobacz Obsługa adresów w Stanach Zjednoczonych i dokumentację USPSData.