Wenn Sie eine Adresse mit der Address Validation API validieren möchten, rufen Sie die Methode validAddress (REST) oder ValidateAddress (gRPC) auf. In dieser Dokumentation wird REST für Beispiele verwendet, der Ansatz ist jedoch mit gRPC ähnlich.
Nachdem Sie eine Adresse validiert haben, können Sie optional Informationen zum Ergebnis der Adressüberprüfung an Google zurückgeben. Rufen Sie dazu die Methode provideValidationFeedback (REST) oder ProvideValidationFeedback (gRPC) auf. Informationen und Beispiele finden Sie unter Feedback zur Adressüberprüfung geben.
Anfrage zur Adressüberprüfung
Senden Sie eine POST
-Anfrage an die Methode validAddress, um eine Adresse zu validieren:
https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY
Übergeben Sie einen JSON-Text an die Anfrage, in der die zu validierende Adresse 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 nichts angegeben ist, leitet die API die Region von der Adresse ab. Für eine optimale Leistung empfehlen wir jedoch, dasregionCode
-Objekt anzugeben, wenn es Ihnen bekannt ist. Eine Liste der unterstützten Regionen finden Sie unter Unterstützte Regionen.Die Gesamtlänge des Felds
address
ist auf 280 Zeichen begrenzt.
Bei der Validierung einer Adresse optional CASSTM aktivieren
Der United States Postal Service® (USPS®)1 betreibt das Coding Accuracy Support System (CASSTM), um Anbieter von Adressüberprüfungen zu unterstützen und zu zertifizieren. Für einen CASS CertifiedTM-Dienst wie die Address Validation API wurde bestätigt, dass er in einer Adresse fehlende Informationen ergänzen, standardisieren und aktualisieren kann, sodass Sie die aktuelle und genaueste Adresse erhalten.
Nur für die Regionen "US" und "PR" können Sie optional die CASS-Verarbeitung aktivieren. Dazu setzen Sie enableUspsCass
im Anfragetext auf true
.
Die besten Ergebnisse bei der Verwendung von CASS erzielen Sie, wenn Sie eine Adresse angeben, die Straße und Hausnummer sowie Ort, Bundesland und 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 auch als zwei Strings im Array addressLines
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, der Informationen zur validierten Adresse enthält.
Das Feld result
der Antwort enthält das Objekt ValidationResult. Dieses Objekt beinhaltet:
Ein
address
-Feld vom Typ Adresse, das detaillierte Informationen zur Adresse enthält.Ein
geocode
-Feld vom Typ Geocode, das Geocode-Informationen für die Adresse enthält.Ein
verdict
-Feld vom Typ Verdikt, das die Ergebnisse der Adressvalidierung und des Geocodings enthält.Ein
metadata
-Feld vom Typ AddressMetadata, das die Metadaten für die Adresse enthält.Ein
uspsData
-Feld vom Typ USPSData, das die USPS-Daten für die Adresse enthält. Diese Daten sind nur für Adressen in den USA und Puerto Rico verfügbar.
Da in der folgenden Antwort addressComplete
auf true
gesetzt ist, gibt die Antwort an, dass diese Adresse vollständig gültig ist, sodass keine weitere Validierung erforderlich ist. Wenn in der Antwort ein Teil der Adresse ungültig ist, bitten Sie den Nutzer, seinen Adresseintrag 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. Anschließend führen Sie eine zweite Validierung der aktualisierten Adresse durch.
Jeder Aufruf der Address Validation API gibt einen eindeutigen Wert im Feld responseId
der Antwort zurück. Wenn eine Adresse, die Sie validieren möchten, noch einmal validiert werden muss, übergeben Sie den 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 oben gezeigte Antwort enthält beispielsweise das Feld responseId
:
"responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
Anschließend möchten Sie die Adresse noch einmal validieren, indem Sie die Hausnummer von 1600 in 1500 ändern. 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" }
Für eine 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 im Feld responseId
einen neuen Wert zurück. Übergeben Sie jedoch weiterhin den Wert von responseId
aus der ersten Antwort im Feld previousResponseId
bei allen nachfolgenden Aufrufen für Aktualisierungen an die Adresse.
Fehlerbehandlung
Die Address Validation API gibt Fehlermeldungen als Teil der Antwort auf einen Methodenaufruf zurück. Wenn Sie beispielsweise den API-Schlüssel in der Anfrage weglassen, gibt die Methode Folgendes zurück:
{ "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.
-
Die Google Maps Platform ist ein nicht-exklusiver Lizenznehmer von 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. ↩