API Fonciris

Documentation de l'API REST v1

Quickstart Auth Endpoints Errors

Quickstart

1. Obtenez votre clé API

Souscrivez au plan Business (129€/mois) et générez une clé depuis votre dashboard.

2. Analysez une adresse

Envoyez une requête GET avec l'adresse en paramètre. L'API géocode automatiquement et lance l'analyse complète.

3. Exploitez les données

Score global, risques détaillés, prix DVF, score de négociation, insights actionnables — tout est structuré en JSON.

Testez en une commande :

curl -H "Authorization: Bearer fon_YOUR_API_KEY" \
  "https://fonciris.com/api/v1/score?address=18+Avenue+Pauliani,+Nice"

Authentification

Toutes les requêtes doivent inclure votre clé API dans le header Authorization :

Authorization: Bearer fon_xxxxxxxxxxxxx

Sécurité

Ne partagez jamais votre clé API en frontend ou dans du code source public
Utilisez des variables d'environnement pour stocker vos clés
Révoquez immédiatement une clé compromise depuis votre dashboard

Rate Limiting

Plan	Par minute	Par jour	Crédits / mois
Business	60	1 000	100
Partenaire API	300	10 000	Sur mesure

Chaque réponse inclut des headers de rate limiting :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1708789260

En cas de dépassement, l'API retourne 429 Too Many Requests avec un header Retry-After.

Endpoints

GET/api/v1/analyzeAnalyse complète1 crédit GET/api/v1/scoreScore + risques principaux0.5 crédit GET/api/v1/risksRisques détaillés0.5 crédit GET/api/v1/pricesPrix DVF0.5 crédit GET/api/v1/usageStatistiques d'utilisationgratuit

GET/api/v1/analyze1 crédit

Analyse complète d'une adresse. Retourne le rapport Fonciris en JSON : score, risques, prix DVF, négociation, cadre de vie et insights.

Paramètres

`address`*	string	Adresse complète (ex: 18 Avenue Pauliani, 06000 Nice)
`lat`	number	Latitude (optionnel, sinon géocodée via BAN)
`lng`	number	Longitude (optionnel)
`include`	string	Sections à inclure, séparées par virgule : score, risks, prices, lifestyle, financial, negotiation. Défaut : all

Exemple

curl -X GET "https://fonciris.com/api/v1/analyze?address=18+Avenue+Pauliani,+06000+Nice" \
  -H "Authorization: Bearer fon_YOUR_API_KEY"

Voir un exemple de réponse complète

{
  "status": "success",
  "data": {
    "address": {
      "formatted": "18 Avenue Pauliani, 06000 Nice",
      "latitude": 43.7102,
      "longitude": 7.262,
      "commune": {
        "code": "06088",
        "name": "Nice",
        "department": "06"
      }
    },
    "score": {
      "global": 64,
      "level": "bon",
      "breakdown": {
        "risques_naturels": 45,
        "dynamique_quartier": 72
      }
    },
    "risks": {
      "summary": {
        "critical": 1,
        "warning": 2,
        "info": 3
      },
      "flood_zone": {
        "present": true,
        "level": "Moyen"
      },
      "clay_risk": {
        "present": true,
        "exposure": "Moyen"
      },
      "seismic_zone": {
        "level": 2
      },
      "radon": {
        "zone": 1
      },
      "seveso": {
        "nearby": false,
        "count": 0
      },
      "pollution": {
        "count": 2
      },
      "catnat_count": 83,
      "insurance_surcharge_estimate": {
        "min": 480,
        "max": 960,
        "currency": "EUR",
        "per": "year"
      }
    },
    "prices": {
      "median_per_sqm": 4700,
      "median_price": 265000,
      "trend_1y": -13.2,
      "transactions_count": 47,
      "transactions_nearby": [
        {
          "date": "2025-09-15",
          "price": 265000,
          "surface": 58,
          "price_per_sqm": 4569,
          "type": "Appartement"
        }
      ]
    },
    "negotiation": {
      "score": 67,
      "level": "forte",
      "reference_price": 282000,
      "adjusted_range": {
        "low": 220000,
        "high": 245000
      },
      "factors": [
        {
          "name": "Zone inondable",
          "decote_min": 10,
          "decote_max": 15
        },
        {
          "name": "DPE F",
          "decote_min": 5,
          "decote_max": 12
        }
      ]
    },
    "insights": [
      {
        "type": "critical",
        "title": "Zone inondable : surcoût assurance estimé",
        "message": "Impact financier estimé : +480 à 960€/an d'assurance"
      }
    ],
    "generated_at": "2026-02-25T15:30:00Z",
    "report_url": "https://fonciris.com/dashboard/scans/abc123"
  },
  "credits_used": 1,
  "credits_remaining": 87
}

GET/api/v1/score0.5 crédit

Version allégée : retourne uniquement le score global, le niveau et les risques principaux. Idéal pour un affichage compact ou un tri.

Paramètres

`address`*	string	Adresse complète
`lat`	number	Latitude (optionnel)
`lng`	number	Longitude (optionnel)

Exemple

curl "https://fonciris.com/api/v1/score?address=18+Avenue+Pauliani,+Nice" \
  -H "Authorization: Bearer fon_YOUR_API_KEY"

Réponse

{
  "status": "success",
  "data": {
    "address": "18 Avenue Pauliani, 06000 Nice",
    "score": 64,
    "level": "bon",
    "risks_count": {
      "critical": 1,
      "warning": 2
    },
    "top_risk": "Zone inondable — aléa moyen",
    "price_trend_1y": -13.2
  }
}

GET/api/v1/risks0.5 crédit

Détail complet des risques naturels et technologiques : inondation, argile, sismique, Seveso, radon, pollution, CatNat, et estimation du surcoût d'assurance.

`address`*	string	Adresse complète
`lat`	number	Latitude (optionnel)
`lng`	number	Longitude (optionnel)

GET/api/v1/prices0.5 crédit

Prix DVF et transactions immobilières récentes autour de l'adresse. Inclut le prix médian au m², l'évolution sur 1 an, et jusqu'à 20 transactions détaillées.

`address`*	string	Adresse complète
`lat`	number	Latitude (optionnel)
`lng`	number	Longitude (optionnel)

GET/api/v1/usagegratuit

Statistiques d'utilisation de votre clé API : crédits restants, appels aujourd'hui et ce mois, historique par jour sur 30 jours, détail par endpoint.

Codes d'erreur

Code	Signification	Action
400	Bad Request	Vérifiez le paramètre 'address'
401	Unauthorized	Vérifiez votre clé API dans le header Authorization
402	Payment Required	Crédits insuffisants. Achetez des crédits supplémentaires
403	Forbidden	Plan Business requis pour l'accès API
429	Too Many Requests	Attendez le délai indiqué dans le header Retry-After
500	Internal Error	Réessayez. Si persistant, contactez le support
503	Service Unavailable	Service temporairement indisponible. Réessayez dans quelques minutes

Format d'erreur

{
  "status": "error",
  "error": {
    "message": "Invalid API key",
    "code": 401
  }
}

Champs de la réponse /analyze

address

`formatted`	string	Adresse formatée
`latitude`	number	Latitude WGS84
`longitude`	number	Longitude WGS84
`commune.code`	string	Code INSEE de la commune
`commune.name`	string	Nom de la commune
`commune.department`	string	Code département

score

`global`	number	Score Fonciris sur 100
`level`	string	Niveau qualitatif (excellent, bon, correct, etc.)
`breakdown`	object	Scores par catégorie (risques, marché, cadre de vie, etc.)

risks

`flood_zone.present`	boolean	Bien situé en zone inondable (PPRI)
`flood_zone.level`	string	Niveau d'aléa : Faible, Moyen, Fort, Très fort
`clay_risk.exposure`	string	Exposition argile : Nul, Faible, Moyen, Fort
`seismic_zone.level`	number	Zone sismique 1-5 (décret 2010-1255)
`catnat_count`	number	Nombre d'arrêtés CatNat communaux
`insurance_surcharge_estimate`	object	Surcoût assurance estimé (min/max en EUR/an)

prices

`median_per_sqm`	number	Prix médian au m2 (source DVF/DGFiP)
`trend_1y`	number	Évolution des prix sur 1 an en %
`transactions_count`	number	Nombre de transactions dans la zone
`transactions_nearby`	array	Jusqu'a 20 transactions DVF detaillees

negotiation

`score`	number	Score de negociabilite 0-100
`level`	string	Niveau : faible, moderee, forte, tres_forte
`reference_price`	number	Prix de reference calcule (DVF)
`adjusted_range`	object	Fourchette de prix ajustee (low/high)
`factors`	array	Facteurs de decote avec % min/max

Prêt à intégrer Fonciris ?

Plan Business : 129€/mois · 100 analyses/mois · Support prioritaire

Obtenir une clé API Partenariat API

Base URL : https://fonciris.com · API version 1 · Données sources : Géorisques, DVF/DGFiP, INSEE, BAN, ADEME