API BUSINESS_SCORE : documentation et exemples

L’endpoint BUSINESS_SCORE de l’API DataRespublica évalue le potentiel d’implantation d’une commune en un seul appel : GET /api/v1/business-score/{code INSEE}, facturé 5 crédits, renvoie un score global sur 100, cinq dimensions notées sur 10 avec leurs indicateurs sources, et, selon le plan, un verdict rédigé, des benchmarks départementaux et des scores verticaux par métier. Cette documentation détaille la méthodologie du score, la structure de la réponse, les niveaux de plan et un exemple d’appel complet.

Le score et ses cinq dimensions

Le score BUSINESS_SCORE est un composite pondéré calculé sur environ 35 000 communes à partir de sources publiques officielles : INSEE pour la démographie et les revenus [1], base SIRENE pour le tissu d’entreprises [2], valeurs foncières DVF pour l’immobilier [3], SITADEL pour la construction [4] et données de finances locales [5]. Chaque commune reçoit une note globale sur 100, décomposée en cinq dimensions notées sur 10 :

Dimension	Poids	Indicateurs sous-jacents
Économie	30 %	revenu médian, taux de chômage, taux de pauvreté
Fiscalité	20 %	taux de taxe foncière bâti, impôts locaux et dette par habitant
Dynamisme immobilier	20 %	prix au m², évolution sur 1 an, logements autorisés
Sécurité	15 %	faits de délinquance pour 1 000 habitants
Éducation	15 %	indice de position sociale (IPS) moyen des collèges, nombre de collèges

Chaque réponse inclut un champ data_completeness (sur 6) qui indique combien de blocs de données sont effectivement disponibles pour la commune : une petite commune rurale peut avoir un score calculé sur des données partielles, et ce champ permet de le savoir avant de décider.

Les quatre zones de lecture

Pour éviter les fausses précisions, le score est traduit en quatre zones qualitatives. Les seuils sont fixes et identiques pour toutes les communes :

Score global	Zone	Lecture
70 et plus	Zone d’opportunité	fondamentaux favorables sur la majorité des dimensions
50 à 69	Zone équilibrée	profil moyen, l’arbitrage se joue sur votre secteur d’activité
35 à 49	Zone à surveiller	au moins une dimension dégradée à examiner de près
moins de 35	Zone à risque	plusieurs signaux défavorables cumulés

Un score de zone équilibrée n’est pas un feu orange : une commune à 55 avec une économie à 8/10 et un dynamisme immobilier à 4/10 peut être excellente pour un service aux actifs et médiocre pour un programme immobilier. La décomposition par dimension compte plus que la note agrégée.

Ce que renvoie l’appel selon votre plan

La réponse JSON est structurée en couches, activées par le plan du compte :

Gratuit : identité du territoire (code, population, département, région), score global avec méthodologie, et les cinq dimensions avec leurs indicateurs bruts.
Pro : ajoute le verdict rédigé (zone, point fort, point de vigilance), les benchmarks chiffrés commune contre moyenne départementale, les signaux faibles détectés, l’économie locale et la vitalité commerciale quand elle est disponible.
Growth : ajoute les scores verticaux par métier (commerce de détail, immobilier, services B2B), les données brutes de finances locales (épargne brute, investissement, fonctionnement par habitant) et un aperçu de la concurrence locale.

Le détail de l’endpoint LOOKUP (ainsi que SEARCH et AUTOCOMPLETE, annoncés dans la grille tarifaire mais encore en préparation) et la logique d’agrégation sont couverts par le guide API de données territoriales France.

Exemple d’appel

L’authentification passe par l’en-tête X-API-Key. L’appel se fait par code INSEE (pas par code postal) :

curl -H "X-API-Key: VOTRE_CLE_API" \
  "https://www.datarespublica.com/api/v1/business-score/31555"

{
  "success": true,
  "data": {
    "territory": { "code": "31555", "name": "Toulouse" },
    "business_score": { "score": 0, "data_completeness": "6/6" },
    "dimensions": { "economie": { "score": 0, "weight": "30%" } }
  },
  "meta": { "unitsCharged": 5, "quotaRemaining": 0 }
}

Les valeurs numériques ci-dessus sont mises à zéro : c’est un gabarit de structure, pas une donnée réelle. La réponse est mise en cache côté serveur pendant 5 minutes (Cache-Control privé), et deux en-têtes de suivi accompagnent chaque appel : X-Credits-Charged (coût débité) et X-Credits-Remaining (solde restant).

Coût, quotas et bonnes pratiques

Un appel BUSINESS_SCORE coûte 5 crédits, quel que soit le plan. Le plan Gratuit (100 crédits par mois) permet donc 20 analyses de test, le plan Pro (39 euros, 20 000 crédits) en permet 4 000 et le plan Growth (99 euros, 120 000 crédits) 24 000. En cas de dépassement de quota ou de limite de débit, l’API renvoie un code 429 avec un délai de nouvelle tentative : prévoyez une gestion de repli plutôt qu’une boucle de réessai immédiate.

Pour scorer une liste de communes candidates plutôt qu’une seule, le workflow batch est documenté dans le guide analyser 50 communes en batch ; la logique métier du score côté implantation commerciale est illustrée sur la page scoring territorial.

Note de méthode

Les poids des dimensions, les seuils de zone, le coût en crédits, la structure de réponse par plan et les en-têtes documentés ici sont extraits du code de production de l’API (gestionnaire v1-business-score et configuration de tarification du dépôt DataRespublica), consultés le 12 juillet 2026. Aucun chiffre d’exemple de cette page n’est une valeur observée : pour une valeur réelle, faites l’appel sur la commune qui vous intéresse.

FAQ : API BUSINESS_SCORE

Combien coûte une analyse BUSINESS_SCORE ?

5 crédits par commune analysée. Au plan Pro (39 euros pour 20 000 crédits mensuels), cela représente 4 000 analyses par mois, soit moins d’un centime par commune.

Quelle différence avec l’endpoint LOOKUP ?

LOOKUP (1 crédit) renvoie la fiche d’indicateurs bruts d’une commune. BUSINESS_SCORE (5 crédits) ajoute la couche de décision : score composite pondéré, zones qualitatives, verdict, benchmarks départementaux et scores verticaux selon le plan.

Que signifie une « zone d’opportunité » ?

Un score global de 70 ou plus sur 100 : la commune est favorable sur la majorité des cinq dimensions pondérées. Cela ne remplace pas l’analyse de votre secteur : vérifiez la dimension la plus importante pour votre activité.

De quand datent les données utilisées par le score ?

Chaque source garde son millésime officiel (recensement et revenus INSEE, DVF semestriel, SITADEL et finances locales annuels). Le champ scores_calculated_at de la réponse date le dernier calcul, et data_completeness indique le nombre de blocs disponibles.