Envoyer une requête de validation d'adresse

Pour valider une adresse à l'aide de l'API Address Validation, appelez la méthode validateAddress (REST) ou ValidateAddress (gRPC). Cette documentation utilise REST pour ses exemples, mais l'approche est similaire avec gRPC.

Après avoir validé une adresse, vous pouvez éventuellement renvoyer des informations à Google sur le résultat de la validation de l'adresse en appelant la méthode provideValidationFeedback (REST) ou ProvideValidationFeedback (gRPC). Pour en savoir plus et obtenir des exemples, consultez Envoyer des commentaires sur la validation d'adresse.

Traiter la demande de validation

Pour valider une adresse, envoyez une requête POST à la méthode validateAddress:

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

Transmettez un corps JSON à la requête définissant l'adresse à valider:

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"

Le champ address du corps de la requête, de type PostalAddress, doit contenir au moins une entrée dans addressLines.

• Le champ regionCode est facultatif. Si cette valeur est omise, l'API déduit la région de l'adresse. Toutefois, pour des performances optimales, nous vous recommandons d'inclure l'élément regionCode si vous le connaissez. Pour obtenir la liste des régions concernées, consultez la section Régions acceptées.

• La longueur totale du champ address est limitée à 280 caractères.

Si vous le souhaitez, vous pouvez activer CASSTM lors de la validation d'une adresse.

Le service postal américain (USPS®)¹ gère le système CASSTM (Coding Accuracy Support System) afin d'aider et de certifier les fournisseurs de validation d'adresse. Il a été confirmé qu'un service CASS CertifiedTM, tel que l'API Address Validation, peut renseigner des informations manquantes dans une adresse, les standardiser et les mettre à jour pour vous fournir l'adresse la plus récente et la plus précise.

Pour les régions "US" et "PR" uniquement, vous pouvez éventuellement activer le traitement CASS en définissant enableUspsCass sur true dans le corps de la requête.

Pour de meilleurs résultats lorsque vous utilisez CASS, fournissez une adresse incluant la rue et le numéro de rue, ainsi que la ville, l'État et le code postal:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "administrativeArea": "CA",
    "postalCode": "94043",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  },
  "enableUspsCass": true
}

Vous pouvez également spécifier l'adresse complète sous la forme de deux chaînes dans le tableau addressLines:

{
  "address": {
    "regionCode": "US",
    "addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
  },
  "enableUspsCass": true
}

Réponse de validation de l'adresse

Si la requête aboutit, le serveur répond avec un code d'état HTTP 200 OK et un corps de réponse contenant des informations sur l'adresse validée.

Le champ result de la réponse contient un objet ValidationResult. Cet objet comprend :

• Un champ address, de type Address (Adresse), contenant des informations détaillées sur l'adresse.

• Un champ geocode, de type Geocode, contenant des informations géocodées pour l'adresse.

• Un champ verdict, de type Verdict, contenant la validation de l'adresse et le résultat du geocoding

• Un champ metadata, de type AddressMetadata, contenant les métadonnées de l'adresse

• Un champ uspsData, de type USPSData, contenant les données USPS pour l'adresse. Ces données ne sont disponibles que pour les adresses aux États-Unis et à Porto Rico.

Étant donné que la réponse suivante contient la valeur addressComplete définie sur true, la réponse indique que cette adresse est entièrement valide. Aucune autre validation n'est donc nécessaire. Si la réponse indique qu'une partie de l'adresse n'est pas valide, invitez l'utilisateur à vérifier et confirmer qu'il a saisi son adresse.

{
  "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"
}

Valider une adresse mise à jour

Dans certains cas, vous devrez peut-être effectuer plusieurs appels à l'API Address Validation pour une même adresse. Par exemple, l'utilisateur peut apporter des modifications ou des corrections à son adresse après avoir vu les résultats de la première validation. Vous effectuez ensuite une deuxième validation sur l'adresse mise à jour.

Chaque appel de l'API Address Validation renvoie une valeur unique dans le champ responseId de la réponse. Si une adresse que vous essayez de valider doit être de nouveau validée, transmettez l'responseId de la première réponse de validation dans le champ previousResponseId pour toutes les requêtes de suivi à l'API Address Validation.

En incluant le champ previousResponseId dans la nouvelle requête, vous pouvez nous aider à améliorer la précision globale de l'API.

Par exemple, la réponse ci-dessus inclut le champ responseId:

  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"

Vous souhaitez ensuite valider à nouveau l'adresse en modifiant le numéro de rue de 1600 à 1500. Lorsque vous revalidez l'adresse, incluez le champ previousResponseId avec la valeur de responseId de la première réponse:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

Pour une requête utilisant CASS:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
  "enableUspsCass": true

}

Les résultats de chaque appel ultérieur renvoient une nouvelle valeur dans le champ responseId. Toutefois, continuez à transmettre la valeur de responseId à partir de la première réponse dans le champ previousResponseId lors de tous les appels de mise à jour suivants de l'adresse.

Gestion des exceptions

L'API Address Validation renvoie des messages d'erreur dans la réponse à un appel de méthode. Par exemple, si vous omettez la clé API de la requête, la méthode renvoie:

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "status": "PERMISSION_DENIED"
  }
}

Si vous omettez un paramètre de corps obligatoire, tel que addressLines, la méthode renvoie:

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

Pour en savoir plus sur les erreurs et leur gestion, consultez la page Erreurs.