API données territoriales France : endpoints, coûts et cas d'usage

Une API de données territoriales France sert à interroger, par le code (JSON), les indicateurs d'une commune ou d'un ensemble de communes sans recoller soi-même les portails open data. La donnée existe déjà en source ouverte (INSEE, finances locales, valeurs foncières, entreprises), mais elle est dispersée dans des formats et des référentiels différents : l'API de DataRespublica agrège ces sources officielles, les normalise sur le référentiel communal INSEE et les expose avec scores et benchmarks. Ce guide détaille les endpoints, le modèle de coût en crédits, les plans et les cas d'usage.

Les endpoints et le modèle de crédits

L'API expose deux endpoints facturés à l'usage via un système de crédits mensuels (un appel consomme un nombre de crédits fixe, documenté sur la page /docs/api), complétés par un endpoint public de lot (jusqu'à 50 communes par appel). Deux endpoints supplémentaires figurent déjà dans la grille tarifaire mais sont en préparation et ne sont pas encore exposés :

Endpoint	Rôle	Coût en crédits
LOOKUP	Fiche complète d'une commune par code INSEE	1 crédit
SEARCH (en préparation)	Recherche multi-communes (filtres département, population, indicateur) : tarif annoncé, endpoint non encore exposé	1 crédit + 0,1 par résultat, plafonné à 5
AUTOCOMPLETE (en préparation)	Suggestion de communes pour un champ de saisie : tarif annoncé, endpoint non encore exposé	0,05 crédit
BUSINESS_SCORE	Score d'implantation d'une commune (5 dimensions pondérées)	5 crédits

Ce modèle rend le coût prévisible : une analyse d'implantation coûte 5 crédits, quel que soit le plan. Pour travailler sur un lot, l'endpoint public de batch accepte jusqu'à 50 codes INSEE par appel (au-delà, l'API renvoie une erreur 400). L'authentification se fait par clé API, et un environnement de démonstration gratuit est accessible sur /api/demo pour tester un code INSEE sans inscription complète.

Dans une application réelle, les briques disponibles s'enchaînent naturellement : LOOKUP récupère la fiche synthétique dès qu'une commune est identifiée, l'endpoint public de batch rapatrie jusqu'à 50 communes en un appel, et BUSINESS_SCORE analyse chaque commune candidate pour la classer. À terme, AUTOCOMPLETE (0,05 crédit annoncé) alimentera un champ de saisie et SEARCH constituera des listes filtrées côté API ; en attendant leur mise en service, la constitution de listes passe par les classements publics du site ou par vos propres référentiels de codes INSEE.

Pourquoi une API agrégée plutôt que les portails bruts

Toutes les données sous-jacentes sont publiques et accessibles séparément : les populations et indicateurs communaux via les API de l'INSEE et le découpage administratif [1], les jeux de données ouverts de data.gouv.fr [2], les valeurs foncières (DVF) publiées depuis le décret du 28 décembre 2018 [3], la base SIRENE des entreprises et établissements [4], et les finances locales de l'OFGL [5]. Rien n'empêche un développeur de les intégrer une par une.

Le problème est le coût d'intégration : chaque source a son format, son référentiel géographique, sa fréquence de mise à jour et ses pièges (communes fusionnées, codes INSEE vs codes postaux, millésimes). Reconstituer une fiche commune complète suppose de joindre une demi-douzaine de fichiers volumineux, puis de les tenir à jour. L'API de DataRespublica fait ce travail une fois : elle aligne les sources sur le référentiel communal INSEE, filtre les valeurs aberrantes, calcule des rangs et des comparaisons départementales, et renvoie le tout en un appel JSON. Le développeur paie une intégration au lieu de six, et récupère des indicateurs déjà scorés plutôt que de la donnée brute à retraiter.

Ce que contient une réponse LOOKUP

Un appel LOOKUP renvoie, pour une commune, un objet JSON compact, normalisé sur le référentiel INSEE. Les champs effectivement exposés :

Identité et hiérarchie : code pays, code INSEE, nom, population et code du territoire parent (département).
Géographie : centroïde (latitude/longitude) et superficie en km².
Marché et fiscalité : prix moyen au mètre carré issu des valeurs foncières (DVF) [3] et taux de fiscalité locale.
Versionnage : un champ de version du payload pour suivre les évolutions de schéma.

Les indicateurs enrichis (finances locales OFGL [5], socio-économique, construction SITADEL, scores par dimension avec verdict de zone et comparaisons) ne font pas partie de LOOKUP : ils sont renvoyés par l'endpoint BUSINESS_SCORE, par blocs selon le plan souscrit ; voir la documentation de l'API BUSINESS_SCORE. C'est la complémentarité des deux appels qui distingue l'API d'un simple proxy vers les données brutes : LOOKUP pour l'identification rapide, BUSINESS_SCORE pour la lecture comparative prête à décider.

Fraîcheur et référentiel des données

Les données s'appuient sur le Code officiel géographique (COG) de l'INSEE, dont la version courante intègre les communes fusionnées et les évolutions de périmètre, et sur le dernier recensement disponible par commune [1]. Chaque source garde son propre millésime : les valeurs foncières DVF sont publiées semestriellement [3], les finances locales de l'OFGL annuellement [5], la base SIRENE est mise à jour en continu [4]. L'API expose la valeur et l'année de chaque indicateur, ce qui évite de comparer par erreur des millésimes différents.

Ce point est important pour un usage en production : plutôt que de suivre soi-même les calendriers de publication de cinq administrations, l'intégration se fait une fois, et les mises à jour de source sont répercutées côté API. Le développeur travaille sur un référentiel commun et daté, pas sur une mosaïque de fichiers aux fréquences hétérogènes.

Plans et coût par analyse

La facturation repose sur des crédits mensuels, avec trois plans (facturation annuelle remisée de 20 %) :

Plan	Prix mensuel	Crédits par mois	Analyses BUSINESS_SCORE incluses
Gratuit	0 €	100	20
Pro	39 €	20 000	4 000
Growth	99 €	120 000	24 000

Le nombre d'analyses se déduit du coût de l'endpoint : une analyse BUSINESS_SCORE coûtant 5 crédits, le plan Pro (20 000 crédits) permet 4 000 analyses par mois, soit moins de 0,01 euro par commune analysée. Le plan gratuit (100 crédits) suffit à tester l'intégration ; il donne 100 LOOKUP ou 20 analyses BUSINESS_SCORE mensuelles.

Cas d'usage concrets

Enrichir un CRM ou un back-office : appeler LOOKUP sur le code INSEE d'un prospect ou d'un bien pour rapatrier population, revenu médian, fiscalité et dynamisme, et afficher ces indicateurs directement dans la fiche.
Étude d'implantation commerciale : passer un lot de communes en BUSINESS_SCORE pour classer des zones candidates, use case détaillé sur le scoring territorial et l'analyse de zone de chalandise.
Analyse immobilière : croiser prix, fiscalité et construction pour repérer des signaux de marché, à rapprocher des pages rentabilité locative.
Data journalisme et recherche : rapatrier un lot de communes via l'endpoint public de batch (jusqu'à 50 codes INSEE par appel) pour construire des comparaisons départementales sans télécharger les bases complètes.

Démarrer en trois étapes

Créer un compte et générer une clé API gratuite (100 crédits/mois) depuis la page API.
Tester un premier appel LOOKUP avec un code INSEE connu (par exemple 75056 pour Paris) ; l'environnement de démonstration permet de voir la réponse avant d'intégrer.
Consulter la documentation pour l'authentification et le format des réponses, puis passer au plan Pro pour monter en volume.

Exemple d'appel

Un appel LOOKUP se fait en HTTP, authentifié par l'en-tête X-API-Key, en passant le pays et le slug de la commune (code INSEE et nom) dans le chemin. La réponse est un objet JSON prêt à consommer :

curl -H "X-API-Key: VOTRE_CLE_API" \
  "https://www.datarespublica.com/api/v1/territory/fr/75056-paris"

{
  "country_code": "FR",
  "locality_code": "75056",
  "name": "Paris",
  "population": 2113705,
  "parent_code": "75",
  "centroid": { "lat": 48.85, "lon": 2.35 },
  "avg_price_m2": 0,
  "local_tax_rate": 0,
  "area_km2": 0,
  "payload_version": 1
}

Les champs exacts et les codes d'erreur figurent dans la documentation. Les valeurs ci-dessus sont un aperçu de structure, pas des chiffres à jour.

Pour la logique métier du score d'implantation, voir aussi le guide documentation de l'API BUSINESS_SCORE.

FAQ : API données territoriales

Quelles données l'API expose-t-elle ?

LOOKUP expose la fiche synthétique d'une commune : identité, population, hiérarchie administrative, centroïde, superficie, prix moyen au mètre carré (DVF) et taux de fiscalité locale [1][3]. Les indicateurs enrichis (finances locales OFGL, socio-économique, construction, scores par dimension) sont renvoyés par BUSINESS_SCORE selon le plan, sur environ 35 000 communes [2][5].

En quoi diffère-t-elle des API open data officielles ?

Les API officielles (INSEE, data.gouv.fr, DVF) exposent chaque source séparément et en données brutes [1][3]. L'API DataRespublica les agrège sur un référentiel unique, les normalise et renvoie des indicateurs scorés et comparés en un seul appel.

Combien coûte une analyse de commune ?

Une analyse BUSINESS_SCORE coûte 5 crédits. Au plan Pro (39 euros pour 20 000 crédits), cela représente 4 000 analyses par mois, soit moins de 0,01 euro par commune.

Peut-on tester gratuitement ?

Oui : le plan gratuit offre 100 crédits par mois et un environnement de démonstration est accessible sur /api/demo pour voir une réponse JSON avant toute intégration.

Sous quel format sont renvoyées les données ?

En JSON, via des endpoints REST authentifiés par clé API : LOOKUP (fiche d'une commune), BUSINESS_SCORE (score d'implantation d'une commune) et un endpoint public de lot (jusqu'à 50 codes INSEE par appel). SEARCH et AUTOCOMPLETE, annoncés dans la grille tarifaire, sont en préparation.

Comment sont gérés les quotas et la consommation ?

Chaque plan ouvre un quota de crédits mensuel (100 en gratuit, 20 000 en Pro, 120 000 en Growth), décompté à chaque appel selon le coût de l'endpoint. La consommation restante est visible sur l'espace compte, et le passage à un plan supérieur relève le quota sans changer l'intégration.