Rufen Sie zum Validieren einer Adresse mit der Address Validation API die Methode validateAddress (REST) oder die Methode ValidateAddress (gRPC) auf. In dieser Dokumentation wird für die Beispiele REST verwendet, der Ansatz ähnelt jedoch gRPC.
Nachdem Sie eine Adresse validiert haben, können Sie optional Informationen zum Ergebnis der Adressüberprüfung an Google zurückgeben. Dazu rufen Sie die Methode ProvideValidationFeedback (REST) oder ProvideValidationFeedback (gRPC) auf. Weitere Informationen und Beispiele finden Sie unter Feedback zur Adressüberprüfung geben.
Anfrage zur Adressüberprüfung
Prüfen Sie eine Adresse, indem Sie eine POST
-Anfrage an die Methode validateAddress senden:
https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY
Übergeben Sie einen JSON-Text an die Anfrage, mit der die Adresse für die Validierung definiert wird:
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"
Das Feld address
im Anfragetext vom Typ PostalAddress muss mindestens einen Eintrag in addressLines
enthalten.
Das Feld
regionCode
ist optional. Wenn keine Angabe gemacht wird, leitet die API die Region aus der Adresse ab. Für eine optimale Leistung empfehlen wir jedoch, dasregionCode
anzugeben, sofern Sie es kennen. Eine Liste der unterstützten Regionen finden Sie unter Unterstützte Regionen.Das Feld „
address
“ darf maximal 280 Zeichen lang sein.
CASSTM bei der Validierung einer Adresse optional aktivieren
Der United States Postal Service® (USPS®)1 unterhält das Coding Accuracy Support System (CASSTM) zur Unterstützung und Zertifizierung von Anbietern für die Adressüberprüfung. Ein CASS CertifiedTM-Dienst wie die Address Validation API wurde bestätigt, weil er Informationen aus einer Adresse hinzufügen, standardisieren und aktualisieren kann, damit Sie die aktuelle und genaueste Adresse erhalten.
Nur für die Regionen „US“ und „PR“ können Sie die CASS-Verarbeitung aktivieren. Setzen Sie dazu enableUspsCass
im Anfragetext auf true
.
Für optimale Ergebnisse bei der Verwendung von CASS geben Sie eine Adresse an, die die Straßen- und Hausnummer, die Stadt, das Bundesland und die Postleitzahl enthält:
{
"address": {
"regionCode": "US",
"locality": "Mountain View",
"administrativeArea": "CA",
"postalCode": "94043",
"addressLines": ["1600 Amphitheatre Pkwy"]
},
"enableUspsCass": true
}
Sie können die vollständige Adresse im addressLines
-Array auch als zwei Strings angeben:
{
"address": {
"regionCode": "US",
"addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
},
"enableUspsCass": true
}
Antwort zur Adressüberprüfung
Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK
und einem Antworttext mit Informationen zur validierten Adresse.
Das Feld result
der Antwort enthält ein ValidationResult-Objekt. Dieses Objekt beinhaltet:
Ein
address
-Feld des Typs Adresse, das detaillierte Informationen zur Adresse enthält.Ein
geocode
-Feld des Typs Geocode, das Geocoding-Informationen für die Adresse enthält.Das Feld
verdict
vom Typ Verdikt, das das Ergebnis der Adressenvalidierung und das Geocoding enthält.Ein
metadata
-Feld vom Typ AddressMetadata, das die Metadaten für die Adresse enthält.Ein
uspsData
-Feld vom Typ USPSData mit den USPS-Daten für die Adresse. Diese Daten sind nur für Adressen in den USA und Puerto Rico verfügbar.
Da die folgende Antwort addressComplete
auf true
enthält, gibt die Antwort an, dass diese Adresse vollständig gültig ist. Daher ist keine weitere Validierung erforderlich. Wenn die Antwort angibt, dass ein Teil der Adresse ungültig ist, bitten Sie den Nutzer, die Adresseingabe zu prüfen und zu bestätigen.
{
"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"
}
Aktualisierte Adresse bestätigen
In einigen Fällen müssen Sie für eine einzelne Adresse möglicherweise mehrere Aufrufe an die Address Validation API senden. Beispielsweise kann der Nutzer Änderungen oder Korrekturen an seiner Adresse vornehmen, nachdem er die Ergebnisse der ersten Validierung gesehen hat. Dann führen Sie eine zweite Validierung für die aktualisierte Adresse durch.
Jeder Address Validation API-Aufruf gibt im Feld responseId
der Antwort einen eindeutigen Wert zurück. Wenn eine Adresse, die Sie überprüfen möchten, noch einmal validiert werden muss, übergeben Sie responseId
aus der ersten Validierungsantwort im Feld previousResponseId
für alle Folgeanfragen an die Address Validation API.
Wenn Sie das Feld previousResponseId
in die neue Anfrage aufnehmen, können Sie die Genauigkeit der API insgesamt verbessern.
Die obige Antwort enthält beispielsweise das Feld responseId
:
"responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
Sie möchten dann die Adresse mit einer Änderung der Hausnummer von 1600 bis 1500 neu validieren. Wenn Sie die Adresse noch einmal validieren, fügen Sie das Feld previousResponseId
mit dem Wert von responseId
aus der ersten Antwort ein:
{ "address": { "regionCode" : "US", "locality" : "Mountain View", "addressLines" : ["1500 Amphitheatre Pkwy"] }, "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a" }
Bei einer Anfrage mit CASS:
{ "address": { "regionCode" : "US", "locality" : "Mountain View", "addressLines" : ["1500 Amphitheatre Pkwy"] }, "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a", "enableUspsCass": true }
Die Ergebnisse jedes nachfolgenden Aufrufs geben einen neuen Wert im Feld responseId
zurück. Bei allen nachfolgenden Aufrufen von Aktualisierungen der Adresse muss jedoch weiterhin der Wert von responseId
aus der ersten Antwort im Feld previousResponseId
übergeben werden.
Fehlerbehandlung
Die Address Validation API gibt im Rahmen der Antwort auf einen Methodenaufruf Fehlermeldungen aus. Wenn Sie den API-Schlüssel beispielsweise in der Anfrage weglassen, wird die Methode zurückgegeben:
{ "error": { "code": 403, "message": "The request is missing a valid API key.", "status": "PERMISSION_DENIED" } }
Wenn Sie einen erforderlichen Textparameter wie addressLines
weglassen, gibt die Methode Folgendes zurück:
{ "error": { "code": 400, "message": "Address lines missing from request.", "status": "INVALID_ARGUMENT" } }
Weitere Informationen zu Fehlern und Fehlerbehandlung finden Sie unter Fehler.
-
Google Maps Platform ist ein nicht ausschließlicher Lizenznehmer des United States Postal Service®. Die folgenden Marken sind Eigentum des United States Postal Service® und werden mit Genehmigung verwendet: United States Postal Service®, CASSTM, CASS CertifiedTM. ↩