Diese Seite wurde von der Cloud Translation API übersetzt.

Adresse bestätigen

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, das regionCode 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®)¹ 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.

Hinweis: Informationen zu den Unterschieden zwischen address und geocode finden Sie unter Adresse und Geocoding.
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. ↩