Adresse bestätigen

Wenn Sie eine Adresse mithilfe der Address Validation API validieren möchten, rufen Sie die Methode validAddress (REST) oder ValidateAddress (gRPC) auf. In dieser Dokumentation wird REST als Beispiel verwendet, der Ansatz ähnelt aber gRPC.

Nachdem Sie eine Adresse validiert haben, können Sie optional Informationen zum Ergebnis der Adressbestätigung an Google zurückgeben, indem Sie die Methode ProvideValidationFeedback (REST) oder ProvideValidationFeedback (gRPC) aufrufen. Weitere Informationen und Beispiele finden Sie unter Feedback zur Adressüberprüfung bereitstellen.

Anfrage zur Adressbestätigung

Prüfen Sie die Adresse. Dazu senden Sie eine POST-Anfrage an die Methode validAddress:

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

Übergeben Sie einen JSON-Textkörper 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 muss den Typ PostalAddress haben und muss mindestens einen Eintrag in addressLines enthalten.

• Das Feld regionCode ist optional. Wenn keine Angabe erfolgt, leitet die API die Region aus der Adresse ab. Für eine optimale Leistung empfehlen wir jedoch, regionCode anzugeben, wenn Sie es kennen. Eine Liste der unterstützten Regionen finden Sie unter Unterstützte Regionen.

• Das Feld address darf maximal 280 Zeichen lang sein.

Optional die CASSTM-Funktion bei der Validierung einer Adresse aktivieren

Der United States Postal Service® (USPS®)¹ verfügt über das Coding Accuracy Support System (CASSTM), um Anbieter von Adressbestätigungen zu unterstützen und zu zertifizieren. Ein CASS-zertifizierterTM Dienst, z. B. die Address Validation API, wurde bestätigt, weil er Informationen aus einer Adresse eintragen, standardisieren und aktualisieren kann, damit Sie die aktuelle und genaueste Adresse erhalten.

Für die Regionen „US“ und „PR“ können Sie optional die CASS-Verarbeitung aktivieren. Legen Sie dazu im Anfragetext enableUspsCass auf true fest.

Die besten Ergebnisse bei der Verwendung von CASS erhältst du, wenn du eine Adresse mit Straße und Hausnummer sowie Ort, Bundesland und Postleitzahl eingibst:

{
  "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 Adressbestätigung

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:

• Das Feld address vom Typ Adresse mit ausführlichen Informationen zur Adresse.

• Das Feld geocode vom Typ Geocode mit Geocode-Informationen für die Adresse.

• Das Feld verdict vom Typ Verdict, das die Adresse und das Geocode-Ergebnis enthält.

• Das Feld metadata 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 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 die Antwort darauf hinweist, 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 validieren

In einigen Fällen müssen Sie mehrere Anfragen an die Address Validation API für eine einzelne Adresse 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 Address Validation API-Aufruf gibt im Feld responseId der Antwort einen eindeutigen Wert zurück. Wenn eine Adresse, die Sie prüfen möchten, noch einmal validiert werden muss, übergeben Sie die 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 einbeziehen, 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 sollten dann die Adresse noch einmal validieren, indem Sie die Hausnummer von 1600 bis 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"
}

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. Übergeben Sie aber bei allen nachfolgenden Aufrufen der Adresse den Wert von responseId aus der ersten Antwort im Feld previousResponseId.

Fehlerbehandlung

Die Address Validation API gibt im Rahmen der Antwort auf einen Methodenaufruf Fehlermeldungen 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 ein erforderlicher Textparameter fehlt, z. B. addressLines, gibt die Methode Folgendes zurück:

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

Weitere Informationen zu Fehlern und zur Fehlerbehandlung finden Sie unter Fehler.