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

La réponse de l'API Address Validation contient les propriétés de premier niveau suivantes :

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // 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"
}

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 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'exemple suivant montre la propriété verdict d'une adresse de bonne qualité, qui renvoie les champs suivants pour cette requête particulière :

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

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

Consultez la section Verdict du guide de référence.

Granularité de l'adresse

La granularité de l'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 granularité suivants :

  • inputGranularity : décrit le niveau de détail capturé à partir de l'adresse envoyée à Address Validation dans l'API Maps JavaScript. Le niveau de détail de l'adresse dans la requête influe sur le niveau de détail de l'adresse dans la réponse de validation. Par exemple, une adresse dont la valeur inputGranularity est inférieure au niveau PREMISE n'entraîne généralement pas une valeur validationGranularity au niveau PREMISE.
  • validationGranularity : niveau de granularité auquel Address Validation dans l'API Maps JavaScript peut valider complètement l'adresse. Dans la plupart des cas, un niveau de granularité 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 d'appartements. Dans ce cas, la valeur validationGranularity est SUB_PREMISE, mais la valeur geocodeGranularity est PREMISE.
Consultez la section Granularité du 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 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 la section addressComplete sous Verdict et Adresse 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 à leur apporter, 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 du guide de référence.

Action suivante possible

Le champ de verdict possibleNextAction offre un résumé interprétatif de la réponse de l'API, destiné à vous aider à déterminer une action ultérieure potentielle à entreprendre. Ce champ est dérivé d'autres champs de la réponse de l'API et ne doit pas être considéré comme une garantie de l'exactitude ou de la distribualité de l'adresse.

Propriétés address et addressComponent

La propriété address fournit la mise en forme de l'adresse traitée dans la requête, ainsi que des résumés 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 la section Address du 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' Address Validation dans l'API Maps JavaScript a traités. L'API identifie chaque champ de composant fourni par son nom, son type et son niveau de confirmation.

Consultez la section addressComponent du 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'emplacement lui-même, telles que son identifiant de lieu.

Consultez la section Geocode du guide de référence.

Propriété metadata

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

Consultez la section 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'elle soit entièrement renseignée 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 également vérifier les propriétés verdict et address.

Consultez la section Gérer les adresses aux États-Unis et la documentation de référence pour USPSData.