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 przedstawiono właściwość verdict adresu o dobrej jakości, która w przypadku tego konkretnego żą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żywanego do określania precyzyjności adresu lub kodu geograficznego. Szczegółowość adresu w odpowiedzi validationGranularity jest kluczowym sygnałem wskazującym, czy adres jest prawidłowy.

Właściwość verdict zwraca te sygnały dotyczące 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 inputGranularity poniżej PREMISE poniżej poziomu zwykle nie powoduje przejścia z validationGranularity na PREMISE.
  • validationGranularity – poziom szczegółowości, na którym 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 wysokiej jakości, który prawdopodobnie jest prawidłowy.
  • geocodeGranularity – opisuje poziom szczegółowości geokodu powiązanego z adresem. Na przykład w dokumentach Google może być podany numer mieszkania, ale nie jego dokładna lokalizacja w dużym kompleksie mieszkaniowym. W tym 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 o 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

Szereg możliwych pól wskazuje problemy ze składnikami adresu lub ich korekty, takie jak wywnioskowane lub brakujące składniki 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 podsumowanie interpretacyjne odpowiedzi interfejsu API, które ma pomóc w określeniu potencjalnych działań do podjęcia w dalszej kolejności. 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 zawiera formatowanie przetworzonego adresu podanego w żądaniu, a także podsumowania adresu na poziomie komponentów, w tym błędnie napisane części adresu, zastąpione nieprawidłowe części i wywnioskowane brakujące części.

Więcej informacji znajdziesz w sekcji 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 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.

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, np. jej identyfikator.

Więcej informacji znajdziesz w sekcji Geocode w przewodniku.

Usługa metadata

Ten atrybut może nie być wypełniony w przypadku każdego adresu przetwarzanego przez interfejs Weryfikacja adresów w Maps JavaScript API, ale wskazuje, czy adres jest typu mieszkalnego, biznesowego czy skrytki pocztowej.

Zapoznaj się z zakresem 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ę wszystkie pola będą wypełnione. 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.

Zapoznaj się z artykułem Obsługa adresów w Stanach Zjednoczonych i informacjami o USPSData.