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

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

• result, un objet de type ValidationResult
• responseID

{
  "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 et doit être la première propriété à évaluer lors de la création de la logique de vérification des adresses. La propriété peut renvoyer différents champs, en fonction de la qualité de l'adresse de sortie. Par exemple, l'exemple suivant montre la propriété verdict d'une adresse de bonne qualité, qui renvoie quatre champs pour cette requête particulière :

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

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

Précision de l'adresse

La précision des adresses 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 livrable ou non.

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

• inputGranularity : décrit le niveau de détail capturé à partir de la 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 avec un inputGranularity inférieur à PREMISE au niveau inférieur ne donne généralement pas lieu à un 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 granularité de PREMISE ou SUB_PREMISE indique une adresse de qualité susceptible d'être livrée.
• geocodeGranularity : décrit le niveau de détail du géocode associé à l'adresse. Par exemple, les enregistrements Google peuvent indiquer de l'existence d'un numéro d'appartement, mais pas de l'emplacement précis un appartement en particulier au sein d'un grand complexe. Dans ce cas, validationGranularity correspond à SUB_PREMISE, mais à geocodeGranularityisPREMISE.

Exhaustivité de l'adresse

Le verdict renvoie la propriété addressComplete en tant que signal pour une de haute qualité, c'est-à-dire qu'il ne manque aucune adresse manquante, des composants non résolus ou inattendus:

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

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

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
}

Propriétés address et addressComponent

La propriété address permet de mettre en forme l'adresse traitée fournie dans la demande, ainsi que des résumés au niveau des composants de l'adresse, y compris fautes d'orthographe dans l'adresse, remplacement des parties incorrectes et déduction des éléments manquants de l'infrastructure.

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és. L'API identifie chaque composant indique par son nom, son type et son niveau de confirmation.

Propriété geocode

La propriété geocode indique l'emplacement géocodé associé à l'entrée. adresse e-mail. Cette propriété fournit des informations sur l'établissement lui-même, par exemple : son identifiant de lieu.

Propriété metadata

Il est possible que cette propriété ne soit pas renseignée pour toutes les adresses traitées par la l'API Address Validation, mais elle indique si l'adresse est de type résidentiel, entreprise ou une boîte postale.

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.