Documentation de l'API

Démarrage

1. 1. Créer un compte gratuit Inscrivez-vous en ligne avec votre e-mail : vous recevez votre clé d'API et 1 000 crédits offerts à la création, puis 500 chaque mois. Sans clé, l'API ne sert qu'à la démonstration, quelques adresses par jour.
2. 2. Envoyer une adresse En texte libre (adresse) ou en lignes (lignes), avec votre clé dans l'en-tête X-API-Key.
3. 3. Lire le statut Utilisez les lignes de sortie, et décidez selon le statut : accepter, faire confirmer ou faire ressaisir.

curl -X POST https://api.nubelo.fr/v1/adresses/normalisation \
  -H "X-API-Key: VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"ref": "client-1043", "adresse": "15 qu des chartrons bdx"}'

// Côté serveur (Node.js 18 ou plus) : la clé ne doit pas être envoyée au navigateur.
const reponse = await fetch("https://api.nubelo.fr/v1/adresses/normalisation", {
  method: "POST",
  headers: { "X-API-Key": process.env.ADRALIS_CLE, "Content-Type": "application/json" },
  body: JSON.stringify({ ref: "client-1043", adresse: "15 qu des chartrons bdx" }),
});
const resultat = await reponse.json();
console.log(resultat.statut, resultat.sortie);

import os
import requests

reponse = requests.post(
    "https://api.nubelo.fr/v1/adresses/normalisation",
    headers={"X-API-Key": os.environ["ADRALIS_CLE"]},
    json={"ref": "client-1043", "adresse": "15 qu des chartrons bdx"},
    timeout=10,
)
reponse.raise_for_status()
resultat = reponse.json()
print(resultat["statut"], resultat["sortie"])

<?php
$ch = curl_init("https://api.nubelo.fr/v1/adresses/normalisation");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("ADRALIS_CLE"), "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["ref" => "client-1043", "adresse" => "15 qu des chartrons bdx"]),
]);
$resultat = json_decode(curl_exec($ch), true);
echo $resultat["statut"], " ", implode(" / ", array_filter($resultat["sortie"]));

Réponse (extrait)

{
  "ref": "client-1043",
  "statut": "CORRIGEE",
  "indice_confiance": 94,
  "sortie": ["", "", "", "15 QUAI DES CHARTRONS", "", "33000 BORDEAUX", ""],
  "codes": [
    { "code": "TYPE_VOIE_NORMALISE", "ligne": 4, "libelle": "Type de voie normalisé", "gravite": "correction" },
    { "code": "CP_COMPLETE", "ligne": 6, "libelle": "Code postal complété : 33000", "gravite": "correction" },
    { "code": "ACHEMINEMENT_CORRIGE", "ligne": 6, "libelle": "Libellé d'acheminement corrigé : BDX → BORDEAUX", "gravite": "correction" }
  ],
  "correspondance": {
    "precision": "numero", "code_insee": "33063", "code_postal": "33000",
    "voie": "QUAI DES CHARTRONS", "id_ban": "33063_2000_00015", "lat": 44.849567, "lon": -0.570466
  }
}

La clé donne accès à vos crédits : gardez-la côté serveur, jamais dans du code exécuté par le navigateur. Pour plusieurs adresses, utilisez POST /v1/adresses/normalisation/lot (jusqu'à 1 000 par appel).

Lire la réponse

Une adresse traitée répond toujours 200, même rejetée : c'est le statut qui donne le verdict.

Indice de confiance

indice_confiance part de 100 % et perd des points à chaque correction ou doute, selon sa nature et la ligne concernée ; detail_indice_confiance donne le détail. Vous pouvez fixer votre propre seuil, par exemple : accepter automatiquement une adresse corrigée au-dessus d'un certain indice, et faire vérifier les autres.

Les lignes de l'adresse

entree et sortie contiennent toujours 7 lignes, celles de la norme AFNOR NF Z10-011. En sortie, chaque ligne fait 38 caractères au plus, en majuscules, sans accents : elles sont prêtes à imprimer.

Codes retour

Chaque constat ou modification est décrit dans codes : un identifiant stable (code), la ligne, un libellé lisible et une gravité (info, correction, alerte, erreur). Basez vos traitements sur code, pas sur le libellé. La liste complète : GET /v1/adresses/codes.

Saisie assistée

Pour qu'une adresse soit juste dès la saisie, proposez communes et voies pendant la frappe. Ces routes ne demandent pas de clé et ne consomment pas de crédits : elles peuvent être appelées depuis le navigateur.

1. 1. Commune GET /v1/adresses/suggestions/communes?q=leog pendant la frappe du code postal ou de la ville ; gardez le code_insee choisi.
2. 2. Voie GET /v1/adresses/suggestions/voies?insee=33238&q=12 av de gra pendant la frappe du numéro et de la voie.
3. 3. Vérification POST /v1/adresses/normalisation à l'enregistrement, côté serveur, pour valider l'adresse complète.

Erreurs et limites

Une erreur répond avec un code HTTP et un objet {"erreur": "…"} qui l'explique en français.

Limites

Référence

Toutes les routes, avec leurs paramètres, des réponses réelles pour chaque statut et les erreurs possibles. Authorize enregistre votre clé ; Try it out envoie un vrai appel. Fichier OpenAPI : openapi.json.