matchID Logo
Traitements d'identités numériques

Fiabilisation, recherche et appariements jusqu'à 100 millions d'identités

Intégrer l'API décès

Développeurs, Datascientists, intégrez l'API décès au sein de vos applications

Intégrer l'API décès

Développeurs, Datascientists, intégrez l'API décès au sein de vos applications

Quelle API pour quel usage

L'API décès possède deux principales fonctions:

  • la recherche unitaire
  • l'appariement (liste de personnes à rechercher)

La première sera utile dans un contexte utilisateur (un formulaire dte données de données d'État civil, où l'appel API servira à vérifier la vitalité d'une personne).

La seconde est utile pour compléter le statut vital d'une base de donnée clients au sein d'un système d'information, de plusieurs milliers à environ un million de personnes

La documentation de l'API est réalisée au format OpenApi Specification (OAS3, Swagger).

Elle décrit de façon détaillée les champs et leur format.

openapi

Intégration d'un formulaire

Le cas d'usage basique est l'utilisation, de la recherche simple (q=Pompidou...) depuis la valeur d'un formulaire (input).

API search

Le code suivantci-contre est l'implémentation de cas en Svelte.js. Cliquez sur "output" pour voir le résultat, ou rendez-vous sur ce REPL.

L'exemple utilise l'API search en mode GET, documentée ici. Sa transposition en POST est simple et préférable pour la robustesse d'un code de production.

Intégration de l'API d'appariement à un backend

L'API unitaire est limité à une requête par seconde. Pour les appariement en masse, une API search/csv permette le traitement de 50 à 100 requêtes par seconde.

Cette API de soumettre un CSV contenant jusqu'à 1 millions d'identité (100Mo), qui sera complété d'éventuelles détections des données de décès en cas de correspondance celle-ci étant qualifiée par un score de confiance.

API search

Ces données peuvent être retraitées à l'issue pour être injectées dans votre base de donnée.

L'exemple minimaliste suivant est réalisé en Python est dispnible sur ce REPL.

Appariement sur deces.matchid.io, explications

L'appariement requiert de trois étapes:

  1. l'indexation des données de décès dans l'API
  2. la recherche de chaque identité du CSV auprès de l'index
  3. le scoring de confiance de chaque identité retrouvée

Seules les deux dernières étapes sont réalisées au moment de l'utilisation de l'API search/csv

Recherche des identités

La requête est composée d'un bloc de critères obligatoires (blocking), les autres éléments de la requête étant optionnels. Les critères obligatoires sont ceux-ci:

  • "nom prénom" = "nom prénoms" INSEE
    modulo normalisation et tokenization : "olivier martin" = "martin olivier" =~ "jean olivier martin".
    Ce match tolère le flou : "oliver martin" = "olivier martin"
  • si une date de naissance est une plage (e.g 01/01/1930-01/01/1940), elle devient obligatoire
  • si une date lastSeenAliveDate est spécifiée, elle devient obligatoire

Note 1: si l'un des champs nom ou prénom manquent, tous les champs disponibles deviennent obligatoires, avec une tolérance floue.
Note 2: les données INSEE utilisent le nom de naissance. Le nom d'usage génère du silence (manqués), notamment sur la popuation des femme mariées.
Note 3: le code source des requêtes est sur GitHub.

Scoring

Le scoring est composé de trois composantes relatives aux données de l'identité pivot: nom & prénom, sexe, date et lieu de naissance.

Les champs textuels (nom prénom, libellés de commune et pays) sont traités en normalisation et tokenization, puis comparés avec la distance de Levenshtein, et sont pénalisés en cas de différence de sonorité (soundex-fr).

Le lieu de naissance prend en compte les trois paramètres éventuels (commune, département, pays) et effectue un traitement différencié en cas de naissance à l'étranger.

Les scores (nom+prénom, sexe, date, lieu) sont ensuite multipliés, et un coefficient de puissance est affecté selon le nombre de paramètres de match (moins il y a de champs soumis à requête, plus une erreur unitaire est pénalisante). Lorsque l'une des données n'est pas fournie, une faible pénalité est soumise (entre 50% et 100% selon le champ).

Le code source du scoring est également sur GitHub.

Intégration d'une UI de validation

Nous vous recommandons dans un premier temps de passer par le service en ligne pour tester la validité du fichier et du choix des colonnes à apparier avant d'attaquer le code d'appariement. Vous pourrez, en particulier, vérifier avec l'aide de l'UI de validation.

Dans le cas d'un service métier intégré dans un système d'information, pour des appariement réguliers, nous recommandons d'intégrer une UI de validation telle que celle proposée.En effet, l'UI proposée permet de diviser en moyenne par 10 le temps de validation d'une paire d'identité par rapport à un affichage en colonnes classiques sous un tableur.

Pour traiter un fichie de 100000 lignes, si 10% de personnes sont décédées, environ 9000 seront avec de très bon scores (peu utiles à valider à la main, sauf cas métier nécessitant une assurance complète), et 1000 seront à regarder plus précisément. Ces 1000 cas peuvent prendre moins de 30 minutes avec une UI adaptée, contre une demie jourée sur un tableur.

A ce stade, nous n'avons pas mis à disposition de composant réutilisable pour cette fonction. Néanmoins nos deux implémentations d'interface de validation peuvent vous inspirer: en Svelte.js ou en Vue.js.

valider l'appariement

Les composants développés implémentent une mise en exergue des différences champs par champ (nom, prénom, ...) entre la donnée cherchée et la donnée de référence INSEE. Cette facilitation visuelle est la source d'accélération de la validation. Nos implémentations reposent sur la librairie diff.js.

Pour continuer