Valider une 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 semblable à celle de 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 la section Envoyer des commentaires sur la validation des adresses.

Demande de validation de l'adresse

Validez une adresse en envoyant 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"

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

  • Le champ regionCode est facultatif. En cas d'omission, l'API déduit la région de l'adresse. Toutefois, pour optimiser les performances, nous vous recommandons d'inclure l'élément regionCode si vous le connaissez. Pour obtenir la liste des régions acceptées, consultez Régions acceptées.

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

Facultatif : activez CASSTM lors de la validation d'une adresse

Le service postal USUS®1 (US Postal Service) assure la gestion du système de précision de codage (CASSTM) pour accompagner et certifier les fournisseurs de validation d'adresses. Un service CASS CertifiedTM, tel que l'API Address Validation, a pu vérifier qu'il est capable de remplir les informations manquantes à partir d'une adresse, de la standardiser et de la mettre à jour pour que vous puissiez disposer d'une adresse à jour plus précise.

Pour les régions "US" et "PR", 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 lors de l'utilisation de CASS, fournissez une adresse qui inclut le numéro et le numéro de la 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 renvoie 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, contenant des informations détaillées sur l'adresse.

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

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

  • 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.

Comme la réponse suivante contient addressComplete défini sur true, la réponse indique que cette adresse est entièrement valide. Aucune autre validation n'est donc requise. Si la réponse indique qu'une partie de l'adresse n'est pas valide, invitez l'utilisateur à vérifier et à confirmer son entrée.

{
  "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 modifier ou corriger 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 affiche une valeur unique dans le champ responseId de la réponse. Si une adresse que vous essayez de valider doit être à nouveau validée, transmettez le responseId de la première réponse de validation dans le champ previousResponseId pour toutes les requêtes de suivi envoyées à 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 devez ensuite valider de nouveau l'adresse en remplaçant le numéro de rue de 1600 à 1500. Lorsque vous validez à nouveau 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 avec 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. Cependant, continuez à transmettre la valeur de responseId à partir de la première réponse du champ previousResponseId pour tous les appels de mise à jour ultérieurs vers l'adresse.

Gestion des exceptions

L'API Address Validation affiche 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 traitement, consultez Erreurs.

  1. Google Maps Platform est un licencié non exclusif du service postal® des États-Unis. Les marques suivantes appartiennent au United States Postal Service®, et sont utilisées avec l'autorisation de ce dernier: United States Postal Service®, CASSTM ou CASS CertifiedTM. ↩