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.

Szczegółowość adresu

Granularność adresu odnosi się do poziomu szczegółowości użytego do określenia precyzyjności adresu lub geokodu. Szczegółowość adresu w odpowiedzi validationGranularityjest 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 Address Validation 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 poziom 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 wskazuje na 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 budynków. W takim przypadku validationGranularity to SUB_PREMISE, a geocodeGranularity to PREMISE.

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.

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
}

Możliwe następne działanie

Pole possibleNextAction verdict zawiera interpretacyjne podsumowanie 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.

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 Address Validation in Maps JavaScript API. Interfejs API identyfikuje każde pole komponentu według nazwy, typu i poziomu potwierdzenia.

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.

Usługa metadata

Ten atrybut może nie być wypełniony w przypadku każdego adresu przetwarzanego przez interfejs Address Validation w Mapach Google JavaScript API, ale wskazuje, czy adres jest typu mieszkalnego, biznesowego czy jest skrytką pocztową.

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 on w pełni wypełniony. 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.