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

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

• 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 porte sur l'objet result. Pour en savoir plus sur le responseID, consultez Gérer les adresses mises à jour.

Propriété verdict

La propriété verdict récapitule les résultats de la validation d'adresse et doit être la première propriété à évaluer lors de la création de la logique de vérification d'adresse. La propriété peut renvoyer divers champs en fonction de la qualité de l'adresse de sortie. Par exemple, voici 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.

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

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 geocode. La spécificité d'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 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 l'inputGranularity est inférieur au niveau PREMISE ne se traduit généralement pas par un validationGranularity au niveau PREMISE.
• validationGranularity : niveau de précision avec lequel l'API Address Validation peut valider entièrement l'adresse. Dans la plupart des cas, un niveau de précision de PREMISE ou SUB_PREMISE indique une adresse de qualité susceptible d'être livrée.
• geocodeGranularity : décrit le niveau de détail du geocode 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 immeuble. Dans ce cas, validationGranularity correspond à SUB_PREMISE, mais à geocodeGranularityisPREMISE.

Consultez la section Précision dans le guide de référence.

Exhaustivité de l'adresse

Le résultat renvoie la propriété addressComplete en tant que signal pour une adresse de haute qualité, ce qui signifie spécifiquement qu'elle ne comporte aucun composant manquant, non résolu ou inattendu:

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

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

Qualité de l'adresse

Un certain nombre de champs possibles indiquent soit des problèmes avec des composants d'adresse, soit des ajustements qui y sont liés, tels que des composants d'adresse déduits 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 la section Verdict dans le guide de référence.

Propriétés address et addressComponent

La propriété address fournit une mise en forme pour l'adresse traitée fournie dans la requête, ainsi que des résumés au niveau des composants de l'adresse, y compris les parties mal orthographiées de l'adresse, le remplacement des parties incorrectes et les parties manquantes inférées.

Consultez la section 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 traitée par l'API Address Validation. L'API identifie chaque champ de composant en fonction de son nom, de son type et de son niveau de confirmation.

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

Propriété geocode

La propriété geocode indique l'emplacement géocodé associé à l'adresse d'entrée. Cette propriété fournit des informations sur l'établissement lui-même, telles que son ID de lieu.

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

Propriété metadata

Cette propriété peut ne pas être renseignée pour chaque adresse traitée par l'API Address Validation, mais elle indique si l'adresse est de type résidentiel, professionnel ou boîte postale.

Consultez la couverture de l'API Address Validation et la documentation de référence sur 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 que ce champ soit entièrement rempli pour chaque adresse validée par le service. Pour cette raison, vous ne devez pas utiliser cette propriété comme seul moyen de valider les adresses, mais plutôt vérifier verdict et address.

Consultez Gérer les adresses aux États-Unis et la référence concernant UspsData.