Anfrage zur Adressbestätigung senden

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