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"
}

Usługa 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 w przypadku tego żądania zwraca te pola:

"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.

Więcej informacji znajdziesz w sekcji Werdykt w przewodniku.

Szczegółowość adresu

Granularność adresu odnosi się do poziomu szczegółowości użytego do określenia precyzji adresu lub kodu geograficznego. Szczegółowość adresu w odpowiedzi validationGranularity jest kluczowym sygnałem wskazującym, czy adres jest prawidłowy.

Usługa verdict zwraca te sygnały o różnym poziomie szczegółowości:

  • inputGranularity – opisuje 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 weryfikacyjnej. Na przykład adres z poziomem inputGranularity poniżej PREMISE poniżej zwykle nie powoduje zmiany na poziom validationGranularity do PREMISE.
  • validationGranularity – poziom szczegółowości, do którego interfejs 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 oznacza adres o wysokiej jakości, który prawdopodobnie jest prawidłowy.
  • geocodeGranularity – opisuje poziom szczegółowości kodu geograficznego powiązanego z adresem. Na przykład w zapisach Google może być podany numer mieszkania, ale nie jego dokładna lokalizacja w dużym kompleksie mieszkaniowym. W takim przypadku validationGranularity to SUB_PREMISE, a geocodeGranularity to PREMISE.
Więcej informacji znajdziesz w sekcji Granularity w przewodniku.

Kompletność adresu

Wynik zwraca właściwość addressComplete jako sygnał adresu wysokiej jakości, co oznacza, że nie ma on brakujących, nierozwiązanych 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 jest ustawione na false.

Więcej informacji znajdziesz w sekcjach addressComplete w werdykcie i adresie w przewodniku.

Jakość adresu

Liczba możliwych pól wskazuje problemy z komponentami adresu lub ich korekty, takie jak wywnioskowane lub brakujące komponenty 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 znajdziesz w sekcji Werdykt w przewodniku.

Możliwe następne działanie

Pole possibleNextAction verdict zawiera interpretacyjne podsumowanie odpowiedzi interfejsu API, które ma pomóc w określeniu potencjalnych dalszych działań. To pole jest wyliczane na podstawie innych pól w odpowiedzi interfejsu API i nie należy go traktować jako gwarancji 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 komponentów, w tym błędnie napisanymi częściami adresu, zastąpionymi nieprawidłowymi częściami i wywnioskowanymi brakującymi częściami.

Więcej informacji znajdziesz w 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 Mapach JavaScript API. Interfejs API identyfikuje każde pole komponentu według nazwy, typu i poziomu potwierdzenia.

Więcej informacji znajdziesz w addressComponent w przewodniku.

Usługa geocode

Właściwość geocode wskazuje lokalizację geokodowaną powiązaną z adresem wejściowym. Ta właściwość zawiera szczegółowe informacje o lokalizacji, takie jak identyfikator miejsca.

Więcej informacji znajdziesz w Geocode w przewodniku.

Usługa metadata

Ta właściwość może nie być wypełniona w przypadku każdego adresu przetwarzanego przez interfejs Weryfikacja adresów w Maps JavaScript API, ale wskazuje, czy adres jest typu mieszkalnego, biznesowego czy jest skrytką pocztową.

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

Usługa uspsData

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

Zobacz Obsługa adresów w Stanach Zjednoczonych i informacje o USPSData.