Weryfikowanie adresu

Aby zweryfikować adres za pomocą interfejsu Address Validation API, wywołaj metodę validateAddress (REST) lub VerifyAddress (gRPC). Ta dokumentacja używa REST w swoich przykładach, ale podejście jest podobne do gRPC.

Po sprawdzeniu adresu możesz zwrócić Google informacje o wyniku weryfikacji adresu, wywołując metodę provideValidationfeedback lub metodę ProvideValidationReview (gRPC). Więcej informacji i przykłady znajdziesz w sekcji Przesyłanie opinii na temat weryfikacji adresu.

Prośba o weryfikację adresu

Zweryfikuj adres, wysyłając żądanie POST do metody validateAddress:

https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY

Przekaż treść JSON do żądania określającego adres do weryfikacji:

curl -X POST -d '{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  }
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"

Pole address w treści żądania Typ adresu musi zawierać co najmniej jedną pozycję w addressLines.

• Pole regionCode jest opcjonalne. Jeśli zostanie pominięty, interfejs API określa region na podstawie adresu. Aby uzyskać najlepszą skuteczność, zalecamy jednak dodanie klasy regionCode, jeśli ją znasz. Listę obsługiwanych regionów znajdziesz w artykule Obsługiwane regiony.

• Całkowita długość pola address jest ograniczona do 280 znaków.

Opcjonalnie włącz CASSTM podczas weryfikowania adresu

Amerykańska usługa pocztowa (USPS®)¹ obsługuje system kontroli dostępu (CoSSTM), który wspiera i certyfikuje dostawców weryfikacji adresów. Usługa CASS CertifiedTM, np. Address Validation API, została potwierdzona, ponieważ umożliwia wypełnianie informacji brakujących z adresu, standaryzowanie go i aktualizowanie tak, aby podać najnowszy i najdokładniejszy adres.

Tylko w przypadku regionów „US” i „PR” możesz opcjonalnie włączyć przetwarzanie CASS, ustawiając enableUspsCass w treści żądania true.

Aby uzyskać najlepsze wyniki w przypadku CASS, podaj adres, który zawiera ulicę i numer domu, oraz miasto, stan i kod pocztowy:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "administrativeArea": "CA",
    "postalCode": "94043",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  },
  "enableUspsCass": true
}

Możesz też podać pełny adres w 2 ciągach znaków w tablicy addressLines:

{
  "address": {
    "regionCode": "US",
    "addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
  },
  "enableUspsCass": true
}

Odpowiedź dotycząca weryfikacji adresu

Jeśli żądanie zostanie zrealizowane, serwer wysyła kod stanu HTTP 200 OK i treść odpowiedzi z informacjami o zweryfikowanym adresie.

Pole result odpowiedzi zawiera obiekt ValidationResult. Ten obiekt zawiera:

• Pole address typu Adres, które zawiera szczegółowe informacje o adresie.

• Pole geocode typu Geocode, które zawiera informacje geograficzne dotyczące adresu.

• Pole verdict typu Efekt, które zawiera weryfikację adresu i wynik dotyczący przetwarzania danych geograficznych.

• Pole metadata typu AddressMetadata zawierające metadane adresu.

• Pole uspsData typu USPSData, zawierające dane USPS dla adresu. Te dane są dostępne tylko dla adresów w Stanach Zjednoczonych i Portoryko.

Poniższa odpowiedź zawiera addressComplete z ustawieniem true, więc odpowiedź wskazuje, że adres jest w pełni prawidłowy, więc dalsza weryfikacja nie jest wymagana. Jeśli odpowiedź wskazuje, że część adresu jest nieprawidłowa, poproś użytkownika o sprawdzenie i potwierdzenie adresu.

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600",
            "languageCode": "en"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4223878,
        "longitude": -122.0841877
      },
      "plusCode": {
        "globalCode": "849VCWC8+X8"
      },
      "bounds": {
        "low": {
          "latitude": 37.4220699,
          "longitude": -122.084958
        },
        "high": {
          "latitude": 37.4226618,
          "longitude": -122.0829302
        }
      },
      "featureSizeMeters": 116.538734,
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g",
      "placeTypes": [
        "premise"
      ]
    },
    "metadata": {
      "business": false,
      "poBox": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRoute": "C909",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S"
    }
  },
  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

Weryfikowanie zaktualizowanego adresu

W niektórych przypadkach w przypadku jednego adresu konieczne może być wykonanie wielu wywołań interfejsu walidacji adresów. Na przykład użytkownik może zobaczyć lub zmienić swój adres po zobaczeniu wyników pierwszej weryfikacji. Następnie przeprowadź drugą weryfikację zaktualizowanego adresu.

Każde wywołanie API do weryfikacji adresów zwraca niepowtarzalną wartość w polu responseId odpowiedzi. Jeśli adres, który próbujesz zweryfikować, wymaga ponownej weryfikacji, przekaż responseId z pierwszej odpowiedzi w polu previousResponseId dla wszystkich kolejnych żądań do interfejsu Address Validation API.

Jeśli w nowym żądaniu umieścisz pole previousResponseId, pomożesz nam zwiększyć ogólną dokładność interfejsu API.

Na przykład powyższa odpowiedź zawiera pole responseId:

  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"

Następnie musisz ponownie zweryfikować adres, zmieniając numer domu z 1600 na 1500. Podczas ponownego weryfikowania adresu dołącz pole previousResponseId z wartością responseId z pierwszej odpowiedzi:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

W przypadku żądania z użyciem CASS:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
  "enableUspsCass": true

}

Wyniki każdego kolejnego wywołania zwracają nową wartość w polu responseId. Nadal jednak przekazywać wartość responseId z pierwszej odpowiedzi w polu previousResponseId we wszystkich kolejnych wywołaniach tego adresu.

Obsługa błędów

Interfejs Address walidacja zwraca komunikaty o błędach w odpowiedzi na wywołanie metody. Jeśli na przykład pominiesz klucz interfejsu API z żądania, metoda zwróci:

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "status": "PERMISSION_DENIED"
  }
}

Jeśli pominiesz wymagany parametr body, np. addressLines, metoda zwróci:

{
  "error": {
    "code": 400,
    "message": "Address lines missing from request.",
    "status": "INVALID_ARGUMENT"
  }
}

Więcej informacji o błędach i ich obsłudze znajdziesz w sekcji Błędy.