Comprendre une réponse de validation d'adresse de base

L'API Address Validation fournit un corps de réponse sous la forme d'un objet JSON contenant deux propriétés de premier niveau :

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

Ce document se concentre sur l'objet result. Pour en savoir plus sur responseID, consultez Gérer les adresses mises à jour.

Propriété verdict

La propriété verdict résume les résultats de la validation de l'adresse. Il s'agit de la première propriété à évaluer lors de la création d'une logique de vérification d'adresse. La propriété peut renvoyer différents champs, en fonction de la qualité de l'adresse de sortie. Par exemple, l'extrait suivant montre la propriété verdict d'une adresse de bonne qualité, qui renvoie quatre champs pour cette requête spécifique :

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true,
  "possibleNextAction": "ACCEPT"
}

Les sections suivantes récapitulent tous les champs de la propriété verdict.

Consultez Verdict dans le guide de référence.

Action suivante possible

La propriété possibleNextAction propose un résumé interprétatif du reste de la réponse de l'API. L'objectif est de vous aider à déterminer si vous devez ou non inviter votre client à vérifier ou modifier son adresse. Pour en savoir plus, consultez Créer votre logique de validation.

Précision de l'adresse

La précision d'une adresse fait référence au niveau de détail utilisé pour déterminer la spécificité d'une adresse ou d'un géocode. La spécificité de l'adresse dans la réponse validationGranularity est un signal clé pour déterminer si une adresse est distribuable ou non.

La propriété verdict renvoie les signaux de précision suivants :

  • inputGranularity : décrit le niveau de détail capturé à partir de l'adresse envoyée à l'API Address Validation. Le niveau de détail de l'adresse dans la requête influence le niveau de détail de l'adresse dans la réponse de validation. Par exemple, une adresse dont le niveau inputGranularity est inférieur à PREMISE ne génère généralement pas de validationGranularity au niveau PREMISE.
  • validationGranularity : niveau de précision auquel l'API Address Validation peut valider complètement l'adresse. Dans la plupart des cas, un niveau de précision PREMISE ou SUB_PREMISE indique une adresse de qualité qui est probablement distribuable.
  • geocodeGranularity : décrit le niveau de détail du géocode associé à l'adresse. Par exemple, les enregistrements Google peuvent indiquer l'existence d'un numéro d'appartement, mais pas l'emplacement précis de cet appartement dans un grand complexe résidentiel. Dans ce cas, validationGranularity est SUB_PREMISE, mais geocodeGranularityisPREMISE.
Consultez Granularité dans le guide de référence.

Exhaustivité de l'adresse

Le verdict renvoie la propriété addressComplete comme signal d'une adresse de haute qualité, ce qui signifie plus précisément qu'elle ne comporte aucun composant manquant, non résolu ou inattendu :

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true,
    "possibleNextAction": "ACCEPT"
}

Lorsque l'adresse comporte des composants manquants, non résolus ou inattendus, le champ est défini sur false.

Consultez addressComplete sous Verdict et Address dans le guide de référence.

Qualité de l'adresse

Un certain nombre de champs possibles indiquent des problèmes avec les composants d'adresse ou des ajustements apportés à ceux-ci, tels que des composants d'adresse inférés ou manquants. Par exemple, la propriété verdict suivante indique une adresse avec des composants non confirmés et un champ addressComplete manquant :

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
Consultez Verdict dans le guide de référence.

Propriétés address et addressComponent

La propriété address fournit la mise en forme de l'adresse traitée fournie dans la requête, ainsi que des récapitulatifs au niveau des composants de l'adresse, y compris les parties mal orthographiées, les parties incorrectes remplacées et les parties manquantes déduites.

Consultez Address dans le guide de référence.

La propriété addressComponent est un sous-composant de address qui fournit une liste détaillée des éléments (ou composants) de l'adresse que l'API Address Validation a traitée. L'API identifie chaque champ de composant fourni par son nom, son type et son niveau de confirmation.

Consultez addressComponent dans le guide de référence.

Propriété geocode

La propriété geocode indique le lieu géocodé associé à l'adresse saisie. Cette propriété fournit des informations sur le lieu lui-même, comme son ID de lieu.

Consultez Geocode dans le guide de référence.

Propriété metadata

Cette propriété n'est pas renseignée pour toutes les adresses traitées par l'API Address Validation, mais elle indique si l'adresse est de type résidentiel, professionnel ou s'il s'agit d'une boîte postale.

Consultez la couverture de l'API Address Validation et la documentation de référence pour Address metadata.

Propriété uspsData

Cette propriété fournit des informations utiles pour les adresses postales aux États-Unis. Toutefois, il n'est pas garanti qu'il soit entièrement renseigné pour chaque adresse validée par le service. Pour cette raison, vous ne devez pas vous fier à cette propriété comme seul moyen de valider les adresses, mais vérifier également verdict et address.

Consultez Gérer les adresses aux États-Unis et la documentation de référence pour UspsData.
Précédent
Envoyer une requête de validation d'adresse
Suivant
Créer votre logique de validation