Créer votre logique de validation

Ce document décrit un processus permettant de créer un système de vérification des adresses pour gérer diverses réponses de l'API Address Validation. Il explique comment créer votre logique pour utiliser correctement la réponse, examiner d'autres signaux de l'API, et quand et comment demander à vos clients des informations supplémentaires.

En général, la réponse de l'API détermine les méthodes suivantes que votre système doit utiliser pour gérer une adresse:

• Correction : l'adresse est de mauvaise qualité. Vous devez demander plus d'informations.
• Confirmer : l'adresse est de haute qualité, mais elle diffère de l'adresse saisie. Vous pouvez demander une confirmation.
• Accepter : l'adresse est de haute qualité. Vous pouvez accepter l'adresse indiquée.

Objectif principal

Ce document vous aide à modifier votre système pour analyser au mieux la réponse de l'API et déterminer les prochaines actions à effectuer avec les adresses fournies. Le pseudocode suivant illustre un flux possible.

if (the API response indicates significant problems in the address)
    FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
    CONFIRM - confirm with the user that the address is correct
else
    ACCEPT - continue with the address returned by the API.

La logique exacte dépend de votre situation. Pour en savoir plus, consultez les conseils d'implémentation. Vous pouvez également utiliser notre implémentation Open Source de cette logique, qui se trouve dans la bibliothèque de composants étendue.

Présentation du workflow

Le tableau ci-dessous récapitule deux actions pour votre système:

1. Le workflow à utiliser en fonction du comportement de correction, de confirmation et d'acceptation.
2. Les premiers signaux à vérifier dans la réponse. Les signaux décrits ici proviennent de la propriété verdict et ne sont pas les seuls signaux à vérifier, mais ils fournissent un indicateur initial de la qualité de l'adresse. Chaque type de comportement correspond à une section de ce document décrivant d'autres signaux que vous devrez peut-être également examiner.

Comportement de votre système
Corriger l'adresse	La réponse de verdict indique des informations importantes manquantes qui doivent être fournies. L'adresse renvoyée par l'API Address Validation n'est pas forcément de qualité. Workflow Examinez les composants de l'adresse, si nécessaire. Demandez au client de corriger les problèmes d'adresse. Demandez la validation de l'adresse mise à jour. (Facultatif) Envoyez une requête au point de terminaison des commentaires de l'API. Consultez Gérer les adresses mises à jour. Procédez avec l'adresse. Signaux d'évaluation L'une des conditions suivantes s'applique: La valeur de validationGranularity est OTHER. Consultez les valeurs de granularité. addressComplete est false.
Confirmer l'adresse	La réponse de verdict indique une adresse de livraison, mais a apporté des modifications à l'entrée d'origine: inférence de données corrigées ou pouvant être confirmées. Workflow Corrections nécessaires : Examinez les composants de l'adresse si nécessaire. Demandez la validation de l'adresse mise à jour. (Facultatif) Envoyez une requête au point de terminaison des commentaires de l'API. Consultez Gérer les adresses mises à jour. Procédez avec l'adresse. Aucune correction n'est nécessaire: (Facultatif) Envoyez une requête au point de terminaison des commentaires de l'API. Consultez Gérer les adresses mises à jour. Procédez avec l'adresse. Signaux d'évaluation Toutes les conditions suivantes s'appliquent: validationGranularity contient ROUTE ou une version ultérieure. Consultez les valeurs de granularité. addressComplete est true. Le champ hasInferredComponents correspond à true. OU Le champ hasReplacedComponents correspond à true.
Accepter l'adresse	La réponse de l'API Address Validation indique que l'adresse est d'excellente qualité. Workflow Continuer avec l'adresse de retour. Signaux d'évaluation Toutes les conditions suivantes s'appliquent: validationGranularity contient PREMISE ou une version ultérieure. Consultez les valeurs de granularité. addressComplete est true. Aucun composant inféré ou remplacé.

Instructions relatives à la mise en œuvre

Lorsque vous concevez la façon dont votre système répond aux signaux de l'API Address Validation, les recommandations suivantes peuvent vous aider à créer un modèle de réponse plus efficace. Toutefois, il ne s'agit que de recommandations. N'oubliez pas que votre implémentation doit correspondre à votre modèle commercial.

	Conseils	Détails
Niveau de risque	Tenez compte du niveau de tolérance dans votre situation pour trouver le juste équilibre entre demander des corrections et accepter l'adresse telle qu'elle a été saisie.	L'API Address Validation renvoie divers signaux que vous pouvez intégrer à votre niveau de risque pour optimiser votre processus de validation. Par exemple, si le numéro de rue d'une adresse n'est pas confirmé, vous pouvez quand même l'accepter. En revanche, si votre activité nécessite une adresse plus précise, vous pouvez inviter l'utilisateur à la fournir. Pour un exemple pouvant relever de l'une ou l'autre catégorie, consultez Numéro de rue non confirmé en dehors des États-Unis dans Accepter l'adresse : exemples.
Accepter les adresses	Il est recommandé d'autoriser votre système à accepter la saisie d'origine si le client ne répond pas aux invites.	Dans ce cas, le client a peut-être saisi une adresse qui ne figure pas dans le système, par exemple pour une nouvelle construction.
Envoyer des commentaires	Lorsque vous renvoyez une demande de validation d'adresse, vous pouvez également envoyer une requête au point de terminaison provideValidationFeedback.	Cela permet à Google de savoir comment vous avez finalement géré la réponse finale. Consultez Gérer les adresses mises à jour.

Essayez la démo. Le reste de ce document utilise différents exemples pour vous aider à comprendre le processus de correction, de confirmation et d'acceptation décrit ci-dessus. Vous pouvez explorer les résultats de ces exemples en les saisissant dans la démo de l'API Address Validation.

Corriger une adresse

Corrigez une adresse lorsque les résultats indiquent clairement qu'elle n'est pas livrable. Votre système peut ensuite inviter le client à fournir les informations nécessaires, après quoi vous réémettez votre workflow pour obtenir une adresse de livraison.

Remarque :Lorsque vous répétez des requêtes à l'API Address Validation pour la même adresse, vous pouvez appeler provideValidationFeedback pour indiquer le résultat. Consultez la section Gérer les adresses aux États-Unis.

Corriger les signaux

L'API Address Validation fournit un certain nombre de signaux pour vous indiquer si une adresse doit être corrigée.

1. Granularité de la validation et composants manquants

Ces deux signaux sont les plus fiables pour indiquer une adresse problématique:

• Chaque fois que le champ validationGranularity est OTHER, votre système doit examiner les signaux des composants d'adresse pour en savoir plus sur l'emplacement de l'erreur et sur la façon de la corriger.
• Chaque fois que l'objet address post-traité renvoie un champ missingComponentTypes, votre système doit rechercher ce composant. Les composants manquants rendent également l'adresse incomplète et non livrable.

2. Autres signaux

L'API Address Validation fournit également d'autres signaux pour vous aider à diagnostiquer des problèmes spécifiques:

Composants suspects	Lorsque l'énumération du niveau de confirmation d'un composant est UNCOMFIRMED_AND_SUSPICIOUS, il est probable que le composant soit incorrect.
Composant non résolu	Un unresolvedToken est une partie de la saisie qui n'est pas reconnue comme faisant partie d'une adresse valide.

3. Signaux d'adresse aux États-Unis

Certains champs applicables uniquement aux adresses aux États-Unis fournissent un signal utile indiquant que l'adresse n'est pas livrable et doit être corrigée. Pour une adresse qui doit être corrigée, le message suivant s'affiche:

dpvConfirmation	N, D ou vide.

Pour en savoir plus sur dpvConfirmation, consultez la section Gérer les adresses aux États-Unis.

Corriger les exemples d'adresses

Confirmer une adresse

Vous confirmez une adresse lorsque l'évaluation indique que l'API Address Validation a inféré ou modifié des composants d'adresse afin de générer une adresse validée. Dans ce cas, vous disposez d'une adresse de livraison, mais vous préférez avoir plus de certitude que l'adresse obtenue est celle souhaitée par le client.

Pour fournir au client l'invite appropriée, votre logique identifie les composants signalés par le service afin de déterminer l'action ou l'indicateur que l'API a appliqué au composant, par exemple inferred, replaced ou spellCorrected. Consultez AddressComponent dans la documentation de référence.

Remarque :Tenez compte de votre niveau de risque pour décider de confirmer l'adresse auprès du client ou de l'accepter comme valide. En outre, si vous renvoyez des requêtes à l'API Address Validation, vous pouvez appeler provideValidationFeedback pour indiquer le résultat. Consultez Gérer les adresses mises à jour.

Confirmer les signaux

L'API Address Validation fournit un certain nombre de signaux pour vous indiquer si une adresse doit être confirmée.

1. Précision de la validation

Un validationGranularity de ROUTE ou plus est acceptable, mais PREMISE ou SUBPREMISE fournit un signal plus fort de distribution.

2. Autres signaux

Lorsque vous décidez de confirmer l'adresse avec le client, le résultat fournit également les informations suivantes pour déterminer les composants à examiner:

Données inférées	Lorsque le champ hasInferredComponents est true, vous savez que l'API a renseigné les informations qu'elle a recueillies à partir d'autres composants d'adresse.
Données remplacées	Lorsque le champ hasReplacedComponents est true, l'API a remplacé les données saisies par celles qu'elle a jugées nécessaires pour rendre l'adresse valide.

3. Signaux d'adresse aux États-Unis

Certains champs applicables uniquement aux adresses aux États-Unis indiquent que votre logique doit confirmer les informations auprès du client. L'une des conditions suivantes s'applique:

dpvConfirmation	S Pour en savoir plus sur dpvConfirmation, consultez la section Gérer les adresses aux États-Unis.
Réponse à l'adresse	Contient le champ missingComponentType avec la valeur subpremise. Remarque: Si le champ contient des types autres que subpremise, l'action appartient à la catégorie "Corriger l'adresse". Consultez la liste complète des types d'adresses dans la documentation sur le géocodage.

Confirmer des exemples d'adresses

Accepter une adresse

Vous acceptez une adresse lorsque l'évaluation indique avec un degré de confiance élevé qu'elle peut être livrée et utilisée sans autre interaction avec le client dans le processus en aval.

Accepter les signaux

L'API Address Validation fournit un certain nombre de signaux pour vous indiquer si une adresse doit être confirmée.

1. Précision de la validation

Un validationGranularity de PREMISE ou supérieur est acceptable, mais dans certains cas, ROUTE indique toujours une adresse livrable.

2. Autres signaux

Un avis sur une adresse de haute qualité doit également fournir les informations suivantes:

• Aucune donnée remplacée Dans le cas présent : hasReplacedComponents: FALSE.
• Aucun composant inféré. Dans le cas présent : hasInferredComponents: FALSE.

3. Signaux d'adresse aux États-Unis

Certains champs applicables uniquement aux adresses aux États-Unis indiquent une adresse de haute qualité pouvant être livrée. Pour une adresse aux États-Unis acceptable, vous devriez voir ce qui suit:

dpvConfirmation	Y Pour en savoir plus sur dpvConfirmation, consultez la section Gérer les adresses aux États-Unis.

Exemples d'adresses acceptées