Les noms de famille, calculés.Des résultats — pas la donnée brute.

Authentification

Créez une clé dans l’espace client : elle commence par sk_souche_ et n’est affichée qu’une fois — seule son empreinte est conservée chez nous. Envoyez-la dans l’en-tête Authorization (ou, à défaut, X-Api-Key). Une clé révoquée cesse de fonctionner immédiatement.

export SOUCHE_CLE="sk_souche_…"
curl -H "Authorization: Bearer $SOUCHE_CLE" https://arborescence.studio/souche-api/v1/nom/martin
# ou bien
curl -H "X-Api-Key: $SOUCHE_CLE" https://arborescence.studio/souche-api/v1/nom/martin

Chaque réponse porte source (producteur, jeux de données, licence, millésime, mention à reproduire) et calcule_par. Un effectif de moins de 5 personnes est rendu "< 5" (chaîne), et ce qu’on pourrait en déduire (part, rapport) vaut null.

GET/souche-api/v1/nom/{nom}

Fiche résumée. La saisie est normalisée (majuscules, sans accents) ; si le nom n’est pas trouvé tel quel, on essaie sans particule, tirets remplacés, espaces retirées — note_recherche le dit. Nom absent des deux fichiers : 404 nom_absent.

{
  "nom": "DUPONT", "nom_affiche": "Dupont",
  "rarete": { "classe": "très courant", "pour_100000_naissances": 94.22, "une_naissance_sur": 1061 },
  "departements_principaux": [
    { "code": "59", "nom": "Nord", "effectif": 9734, "part": 0.1409, "rapport": 2.33, "intervalle_95": [2.288, 2.374] },
    { "code": "62", "nom": "Pas-de-Calais", "effectif": 5694, "part": 0.0824, "rapport": 2.37, "intervalle_95": [2.312, 2.43] },
    …
  ],
  "foyer_probable": {
    "lat": 48.031, "lon": 2.056, "departement_proche": { "code": "45", "nom": "Loiret", "distance_km": 25.2 },
    "demi_rayon_km": 274.2, "concentration_H": 0.838, "lecture_H": "diffus", "confiance": "bonne"
  },
  "variantes": [ { "nom": "DUPON", "similarite": 0.9667, "meme_son": true }, … ],
  "type_et_etymologie": { "lexique": {
    "type": "lieu-dit", "sens": "« du pont » : nom d'habitation urbaine près d'un pont ; …", "certitude": "attesté",
    "source": "Dauzat 1925, p. 89 (l. 4168) : « … surtout à elle que se rattachent Dupont … » ; Larchey 1880, p. 124 …" },
    "dauzat_1925_cite": { "pages": [89] }, "larchey_1880": null, "moisy_1875": null },
  "source": { … }, "calcule_par": "SOUCHE — Arborescence"
}

GET/souche-api/v1/nom/{nom}/carte?epoque=1891-1940

Tous les départements où le nom est né sur la période, triés par effectif. La période est arrondie aux décennies de l’INSEE (1891-1900 … 1991-2000). Sans epoque : 1891-2000, et un second témoin, temoin_deces, tiré du département de naissance des personnes décédées.

{
  "nom": "DUPONT", "epoque": "1891-1940",
  "departements": [ { "code": "59", "nom": "Nord", "effectif": 3543, "part": 0.143, "rapport": 2.621, "intervalle_95": [2.542, 2.701] }, … ],
  "effectif_localise": 24769, "sans_departement": 23,
  "indice_de_concentration": { "H": 0.823, "lecture": "diffus", "H_national": 0.9405 }
}

GET/souche-api/v1/nom/{nom}/evolution

Séries par décennie. Attention à la lecture des décès : ce sont les personnes décédées entre 1970 et 2026, classées par décennie de naissance — pas un nombre de décès par décennie.

{
  "naissances": [ { "decennie": "1891-1900", "naissances": 3398, "naissances_france": 3285631, "pour_100000": 103.42 }, … ],
  "tendance": { "sens": "stable", "pourcentage_par_an": -0.194, "r2": 0.7563 },
  "personnes_decedees_par_decennie_de_naissance": [ { "decennie_de_naissance": "1890-1899", "personnes": 2481 }, … ],
  "deces": { "total": 26680, "hommes": 13776, "femmes": 12904, "age_moyen_au_deces": 74.2 }
}

GET/souche-api/v1/recherche?q=dupond&flou=1

Jusqu’à 20 noms candidats. Sans flou : noms qui commencent par la saisie, puis par la saisie sans particule. Avec flou=1 : s’y ajoutent les noms de même clé phonétique française et ceux dont la similarité de Jaro-Winkler atteint 0,88. Le nom exact, s’il existe, vient en tête ; les autres sont triés par score.

{
  "requete_normalisee": "DUPOND", "cle_phonetique": "DUP3",
  "candidats": [
    { "nom": "DUPOND", "score": 1, "correspondance": "exact", "meme_son": true, "naissances": 1027 },
    { "nom": "DUPON", "score": 0.9667, "correspondance": "phonetique", "meme_son": true, "naissances": 720 },
    { "nom": "DUPONT", "score": 0.9333, "correspondance": "phonetique", "meme_son": true, "naissances": 69221 },
    …
  ]
}

GET/souche-api/v1/departement/{code}/noms?top=50

Codes 01 à 95, 2A, 2B, 971 à 974. top entre 1 et 200 (50 par défaut). « Plus caractéristiques » : rapport de vraisemblance classé sur la borne basse de l’intervalle à 95 %, noms d’au moins 30 naissances dans le département. Le tout premier appel peut prendre une dizaine de secondes (index construit une fois par millésime).

{
  "code": "29", "nom": "Finistère",
  "plus_portes": [ { "rang": 1, "nom": "LE GALL", "naissances": 13629, "pour_1000_naissances_du_departement": 11.71 }, … ],
  "plus_caracteristiques": [ { "rang": 1, "nom": "LANNUZEL", "naissances": 1249, "rapport": 50.914 }, … ]
}

GET/souche-api/v1/statut

Sans clé, sans décompte : etat, version, millesime des données, seuils appliqués. /souche-api/v1/offres rend de même les offres et leurs prix.

Quotas et erreurs

Deux limites par clé : un quota mensuel, et une rafale par minute qui protège le service. Chaque réponse authentifiée porte X-Quota-Limite, X-Quota-Restant, X-Quota-Periode (AAAA-MM), X-Rafale-Limite et X-Offre.

{ "erreur": "quota_mensuel_atteint",
  "message": "Quota mensuel de 100 requêtes atteint pour l’offre « Essai ». Il se renouvelle le 1er du mois ; une offre supérieure se demande dans l’espace client." }

Attribution : une obligation, pas une option

Les données sources sont publiées par l’INSEE sous Licence Ouverte 2.0. Toute diffusion d’un résultat de l’API — à l’écran, sur papier, dans un rapport — doit citer la source et sa date :

Vie privée : des agrégats, jamais une personne

L’API ne rend que des comptes de personnes regroupées par nom, décennie et département. Aucune ligne individuelle, aucune date de naissance ou de décès, aucun prénom ni commune de naissance (l’application en affiche quelques-uns ; l’API, non : croisés avec un nom rare, ils désigneraient presque une famille). Aucune donnée ne porte sur une personne vivante identifiable. Les mêmes seuils que l’application s’appliquent :

Il est interdit de croiser les résultats avec des données sur des personnes vivantes, et d’interroger l’API systématiquement pour reconstituer les fichiers sources : voir les conditions générales de l’API.