API et données publiques : comprendre, récupérer, intégrer

Les données publiques françaises sont parmi les plus riches au monde : adresses, entreprises, transactions immobilières, bornes de recharge, prix des carburants. Tout cela est gratuit et librement accessible. Encore faut-il savoir sous quelle forme y accéder, et ce qu’implique de les intégrer réellement à un site. Cet article fait le tour de la question — et détaille les sources qui alimentent les outils de ce site.

Les exemples de code sont en PHP et JavaScript, mais les principes valent pour n’importe quel langage.

Qu’est-ce qu’une API, concrètement ?

Une API est un guichet. Vous formulez une demande précise, on vous rend une réponse structurée. La différence avec un site web tient à la destination : une page web est écrite pour un œil humain, une API répond à un programme.

Prenons un exemple réel, celui de la Base Adresse Nationale. Cette adresse est une question posée au service :

https://api-adresse.data.gouv.fr/search/?q=8+boulevard+du+Port&limit=1

La réponse n’est pas une page mise en forme, mais un bloc de texte structuré :

{
  "features": [{
    "properties": { "label": "8 Boulevard du Port 80000 Amiens", "postcode": "80000" },
    "geometry": { "coordinates": [2.290084, 49.897442] }
  }]
}

Ce format s’appelle JSON. Il a une propriété décisive : un programme le lit sans ambiguïté. Là où extraire une information d’une page HTML suppose de deviner quelle balise contient quoi — et de tout recommencer à chaque refonte du site —, une API garantit que postcode désignera toujours le code postal.

Trois notions suffisent pour s’y retrouver :

• Le point d’entrée (endpoint) est l’adresse du guichet. Un même service en propose souvent plusieurs : un pour chercher, un pour consulter une fiche précise.
• Les paramètres forment votre question, glissés après le ?. Ici, q porte le texte cherché et limit plafonne le nombre de résultats.
• Le code de retour dit si tout s’est bien passé : 200 pour un succès, 404 si la ressource n’existe pas, 429 si vous avez tapé trop vite, 500 si le serveur d’en face a un problème.

Ces codes ne sont pas décoratifs : toute la gestion d’erreur repose sur eux.

API ou jeu de données : deux mondes différents

L’open data se présente sous deux formes, et les confondre mène droit à des ennuis.

Une API sert des réponses à la demande, fraîches, en petite quantité. Elle convient à une recherche déclenchée par un visiteur : une adresse à géocoder, un SIRET à vérifier, une météo à afficher.

Un jeu de données est un fichier complet à télécharger — parfois plusieurs centaines de mégaoctets. Il ne bouge qu’à chaque publication, mensuelle ou semestrielle. Il s’impose dès qu’il faut croiser, agréger, ou calculer sur l’ensemble.

Le critère de choix est simple : appelez-vous la source pour un élément, ou pour tous ? Afficher le prix du carburant de la station la plus proche suppose de comparer toutes les stations : c’est un jeu de données. Vérifier une entreprise par son SIRET ne concerne qu’une fiche : c’est une API.

Une erreur fréquente consiste à interroger une API en boucle pour reconstituer un jeu de données complet. C’est lent, c’est fragile, et c’est le meilleur moyen de se faire bloquer. Quand le fichier existe en téléchargement, prenez le fichier.

Récupérer les données d’une API

L’appel de base

Côté serveur, en PHP, WordPress fournit tout le nécessaire :

$reponse = wp_remote_get(
    'https://api-adresse.data.gouv.fr/search/?q=' . urlencode($adresse) . '&limit=1',
    array('timeout' => 8)
);

if (is_wp_error($reponse) || wp_remote_retrieve_response_code($reponse) != 200) {
    return null;          // la source est muette : on le dit, on n'invente pas
}

$donnees = json_decode(wp_remote_retrieve_body($reponse), true);

Le timeout n’est pas un détail. Sans lui, une API lente fige votre page jusqu’à ce que PHP abandonne — souvent trente secondes. Huit secondes suffisent largement ; au-delà, mieux vaut renoncer proprement.

Mettre en cache, systématiquement

C’est la règle qui sépare une intégration qui tient d’une intégration qui casse. Si dix visiteurs cherchent la même adresse, il n’y a aucune raison d’interroger dix fois la source :

$cle = 'geo_' . md5($adresse);
$cache = get_transient($cle);
if (is_array($cache)) { return $cache; }

// … appel réseau …

set_transient($cle, $resultat, 30 * DAY_IN_SECONDS);

Trente jours pour un géocodage : les rues ne déménagent pas. Une heure pour une météo. Quelques minutes pour un prix de carburant. La durée du cache se déduit de la vitesse à laquelle la donnée devient fausse.

Respecter la source

Les services publics gratuits fonctionnent parce que chacun se tient bien. Nominatim, le géocodeur d’OpenStreetMap, exige un appel par seconde au maximum et un en-tête identifiant votre application. Ce n’est pas une formalité : les contrevenants sont bloqués par adresse IP.

Un quota dépassé se manifeste par un code 429. La bonne réaction n’est pas de réessayer aussitôt, mais d’attendre — en doublant le délai à chaque nouvel échec.

Prévoir la panne

Une API extérieure tombera. Pas peut-être : un jour. La seule question est de savoir ce que voit alors votre visiteur. Un message clair vaut mieux qu’une page blanche, et un résultat approché vaut mieux qu’un message. Sur ce site, le géocodage bascule automatiquement d’un service à l’autre en cas d’échec, plutôt que d’abandonner.

Importer un gros jeu de données

C’est là que les choses se corsent, et c’est le sujet le plus souvent escamoté.

Un fichier de valeurs foncières décompressé pèse environ 600 Mo pour 3,7 millions de lignes. Le réflexe naturel — ouvrir le fichier, le parcourir, insérer en base — échoue de trois façons différentes.

Les trois murs

• La mémoire. Charger un fichier entier dans un tableau demande plusieurs fois sa taille en mémoire vive. La limite d’un hébergement mutualisé est franchie bien avant la fin.
• Le temps d’exécution. PHP s’interrompt au bout de trente secondes par défaut. Insérer trois millions de lignes en prend beaucoup plus.
• La limite d’envoi. Passer par l’interface d’administration de la base bute sur le plafond d’upload, souvent quelques mégaoctets.

Traiter hors production

Les gros calculs n’ont rien à faire sur le serveur qui sert vos pages. Un environnement Python avec pandas, sur votre machine, lit le fichier par morceaux et produit un résultat compact. Six cents mégaoctets de transactions brutes deviennent quelques mégaoctets d’agrégats — et ce sont eux, et eux seuls, qui partent en base.

Importer par lots

Le fichier est déposé par FTP, hors de tout formulaire, ce qui neutralise d’emblée la limite d’envoi. Un script le lit ensuite par tranches de quelques milliers de lignes, en mémorisant sa position :

$fh = fopen($fichier, 'r');
fseek($fh, $position);          // on reprend où le lot précédent s'est arrêté

while ($lus < 4000 && ($ligne = fgetcsv($fh, 0, ';')) !== false) {
    $lus++;
    // … validation, puis accumulation …
}

$position = ftell($fh);         // on note où reprendre

Chaque lot est une requête distincte, déclenchée par le navigateur, qui affiche une barre de progression. Aucune ne dépasse le temps limite. Un fichier de 200 000 lignes s’importe ainsi en une cinquantaine d’allers-retours, sans qu’aucun réglage serveur n’ait à bouger.

Dernier point souvent négligé : groupez les insertions. Trois mille requêtes INSERT séparées sont d’une lenteur redoutable ; une requête portant cinq cents lignes d’un coup est plusieurs dizaines de fois plus rapide.

Nettoyer avant d’insérer

Les données publiques sont fiables, mais brutes. Le travail réel se situe là :

• Le séparateur varie : virgule, point-virgule, tabulation. Détectez-le sur la première ligne plutôt que de le supposer.
• L’encodage aussi. Un fichier en Latin-1 lu comme de l’UTF-8 produit des accents illisibles.
• Les colonnes changent de nom d’un millésime à l’autre. Repérez-les par leur intitulé, jamais par leur position.
• Les valeurs aberrantes existent partout : un bien à un euro, une surface de trois mètres carrés. Un filtre de bon sens vaut mieux qu’une moyenne absurde.
• Les doublons enfin. Une vente immobilière portant sur trois lots apparaît sur trois lignes ; la compter trois fois fausse tout le calcul.

La question qu’on oublie : la licence

Public ne veut pas dire libre de tout usage. La plupart des jeux de données français relèvent de la Licence Ouverte, très permissive, qui demande seulement de citer la source. Mais certaines sources ajoutent leurs propres conditions, et celles-là s’imposent.

Les données de valeurs foncières en offrent l’exemple le plus net. Leur réutilisation est soumise à deux règles : ne pas permettre de ré-identifier un vendeur, et ne pas laisser les données être indexées par les moteurs de recherche. La première impose de n’afficher que des agrégats, au-dessus d’un seuil minimum de ventes par zone. La seconde interdit d’écrire ces chiffres dans le HTML servi aux robots.

Ces contraintes ne sont pas des formalités administratives : elles dictent l’architecture. Un outil qui les respecte se conçoit différemment dès la première ligne. À vérifier avant de commencer, donc : la licence, les conditions particulières, l’obligation de citation, et la fréquence de mise à jour.

Ce qui tourne sur ce site

Voici l’inventaire complet des sources publiques utilisées, et les outils qu’elles alimentent.

API interrogées en direct

Source	Ce qu’elle fournit	Outil
Base Adresse Nationale	Adresse → coordonnées GPS	Géolocalisation, annuaires talents et recruteurs
Géoplateforme IGN	Géocodage d’adresses et de communes	Petites annonces, Location entre particuliers
Découpage administratif	Communes, codes postaux, départements	Médecins, Petites annonces
Recherche d’entreprises	SIREN, SIRET, dirigeants, code NAF	Vérification d’entreprise
Open-Meteo	Prévisions météo, sans clé d’accès	Météo
Nominatim (OpenStreetMap)	Géocodage de secours	Repli automatique des précédents
Annuaire Santé (Assurance Maladie, via OpenDataSoft)	Praticiens, spécialité, secteur de convention, coordonnées	Médecins
Radio France	Flux audio en direct	Radio

Jeux de données importés en base

Source	Volume	Rythme	Outil
Valeurs foncières géolocalisées (DGFiP)	3,7 M lignes par année	Semestriel	Avis de valeur immobilière
Bornes de recharge électrique	~100 000 points	Mensuel	Géolocalisation
Prix des carburants	~10 000 stations	Quotidien	Géolocalisation
Distributeurs de billets (OpenStreetMap, via OpenDataSoft)	~50 000 points	Mensuel	Géolocalisation
Toilettes publiques	~5 000 points	Trimestriel	Géolocalisation
Base GeoIP	2 Mo compressés	Trimestriel	Détection du pays du visiteur

L’annuaire des médecins illustre un cas mixte qui se rencontre souvent. La consultation s’appuie entièrement sur l’API : recherche, spécialité, secteur de convention, tout vient de la source publique. Mais un praticien peut aussi soumettre sa propre fiche, et là aucune API ne peut trancher — son numéro RPPS est vérifié manuellement avant publication. Une source publique répond à la question « ce praticien existe-t-il ? », pas à la question « la personne qui remplit ce formulaire est-elle bien ce praticien ? ».

En résumé

• Une API répond à une question précise ; un jeu de données se travaille en bloc.
• La première exige un cache, un timeout et une gestion de panne.
• Le second exige un traitement hors production et un import par lots.
• Le travail sérieux n’est pas la récupération, mais le nettoyage et la validation.
• La licence se lit avant d’écrire la première ligne : elle dicte l’architecture.

Tous les outils cités sont gratuits et sans inscription. Ils sont regroupés dans le catalogue des outils.