Trois façons d’utiliser PermisAPI selon votre profil. Toutes partent de la même clé d’API gratuite. Choisissez celle qui vous parle ; les autres sections restent accessibles plus bas.
Premiers pas selon votre profil
Sans coder
Votre espace, sans coder
Cherchez les permis dans une page faite pour ça : une boîte de recherche, des filtres qui disent combien de permis ils donnent, la carte et la fiche de chaque permis. Aucune ligne de code.
Connectez-vous à votre espace avec votre clé d’accès : la page Permis s’ouvre sur les permis les plus récents de votre département
Tapez une commune, un code postal, une adresse ou un numéro de permis, puis cochez des filtres : leurs nombres et la carte ne comptent pas dans vos requêtes
Affichez la liste (1 requête par permis), dépliez un permis pour voir son aperçu, puis ouvrez sa fiche
Gardez un permis avec l’étoile (Ma sélection), ou enregistrez la recherche pour la reprendre plus tard (Alertes)
Demandez en français à votre assistant IA ; il appelle les bonnes fonctions PermisAPI pour vous. Fonctionne avec Claude, ChatGPT, Claude Desktop, Cursor et Windsurf. Inclus dans toutes les formules.
Installez le connecteur en une commande : pip install permisapi-mcp
Renseignez votre clé d’API dans la configuration de votre assistant (Claude Desktop, Cursor, Windsurf)
Redémarrez l’application
Demandez en français : « trouve les permis de logement à Bordeaux ce mois avec un score d’opportunité > 70 »
Intégrez PermisAPI dans votre application ou votre chaîne de données. SDK Python officiel, ou appels HTTP directs (curl, fetch, requests…) dans n’importe quel langage.
Récupérez votre clé d’API dans votre espace, rubrique « Pour les développeurs »
Vous pouvez combiner les trois chemins. Par exemple : créer une alerte sur webhook depuis votre espace (Pour les développeurs), recevoir les notifications dans Make ou Zapier, et utiliser le SDK Python dans un script qui enrichit votre CRM.
Essayez l’API en 5 minutes depuis Postman
Collection officielle PermisAPI prête à l’emploi : 34 requêtes organisées en 7 dossiers (Démarrage, Parcourir, Analyser, Investiguer, Entreprises, Statistiques, Automations). 3 permis d’exemple à Paris, Saint-Denis et Nice, vérifiés en production le 9 octobre 2026. Les données avancées demandent la formule Régional ou plus, l’export et la recherche par polygone la formule Business.
Récupérez votre clé d’API dans votre espace (formule Gratuit : 500 requêtes par mois, sans carte bancaire)
Cliquez sur « Tester dans Postman » ci-dessous, ou téléchargez la collection JSON
Collez votre clé dans la variable de collection API_KEY
Lancez « Health check » puis « Mon compte » pour valider, puis explorez les 7 dossiers
Aucun compte Postman requis pour télécharger la collection. Importez le fichier .json dans n’importe quel client d’API : Postman, Insomnia, Bruno, Hoppscotch…
Référence des endpoints (pour développeurs)
Tous les endpoints avec exemples curl, Python et JavaScript prêts à copier. Pour la référence complète avec schémas et codes d’erreur, voyez Swagger UI.
1
Obtenir une clé
Créez votre accès gratuit : votre clé au format pk_live_... s’affiche aussitôt. Elle est aussi enregistrée dans ce navigateur pour votre espace.
Aucune carte bancaire pour la formule Gratuit (500 requêtes par mois).
2
Avec Claude, ChatGPT ou Cursor (MCP)
Pour utiliser PermisAPI dans Claude Desktop, Cursor ou Windsurf en langage naturel, sans coder : pip install permisapi-mcp, puis configurez votre client MCP. Guide complet sur permisapi.fr/mcp. 18 outils en lecture seule, inclus dans toutes les formules (ou, sans installation, connexion au serveur hébergé depuis Claude ou ChatGPT).
3
Votre premier appel
Tous les endpoints exigent l’en-tête X-API-Key. Exemple minimal :
Python : SDK officiel disponible sur PyPI, pip install permisapi-client. Client synchrone et asynchrone, exceptions par type d’erreur, alertes webhook, parcours de toutes les pages avec iter_all (version 0.8.1 et suivantes). Voir pypi.org/project/permisapi-client.
La réponse contient votre formule, votre quota mensuel et la date de remise à zéro du quota.
4
Endpoints principaux
GET/v1/permitsToutes les formules
Lister les permis
14 filtres combinables : département, commune, localité, code postal, type, état, année de dépôt, dates d’autorisation (début et fin), superficie minimale, SIREN du demandeur, permis géolocalisés seulement et, à partir de Régional, note minimale et risque maximal. 50 résultats par page par défaut, 200 au plus. La réponse contient data (les permis) et pagination (page, limit, total, has_next, next_url). Chaque permis renvoyé compte pour une requête de votre quota. En Gratuit, seuls les nouveaux permis des 2 dernières publications Sitadel sont renvoyés, quelle que soit leur date d’autorisation (en-tête X-PermisAPI-Publications) ; en Découverte (180 jours) et Explorateur (365 jours), les permis autorisés depuis la date de l’en-tête X-PermisAPI-History-From, plus ceux de ces 2 publications, même sans date_from.
Les permis géolocalisés dans un rayon autour d’un point GPS (500 m par défaut, de 10 m à 50 km), du plus proche au plus loin, avec la distance en mètres (distance_m). La réponse est une liste, sans pagination : 50 permis par défaut, 200 au plus. Chaque permis renvoyé compte pour une requête.
Nombre total de permis (total_permits), comptes par état (autorisés et toujours valables, annulés, travaux commencés, travaux terminés), répartition par type (top_permit_types), permis des 12 derniers mois et évolution sur un an en % (trend_yoy_pct), superficie moyenne. Pour Paris, Lyon et Marseille, le code de la ville (75056, 69123, 13055) donne la ville entière, et un code d’arrondissement (75101 à 75120, 69381 à 69389, 13201 à 13216) donne les permis de l’arrondissement seul : Sitadel les publie sous le code de la ville, PermisAPI les rattache à l’arrondissement par le numéro du permis (Paris, Lyon) ou par le code postal du terrain et, à défaut, le point géocodé (Marseille). Le champ plm_mapping le signale.
POST/v1/alertsToutes les formules (1 alerte en Gratuit)
Créer une alerte webhook
PermisAPI envoie un JSON signé (HMAC SHA-256) à votre URL, en HTTPS, à chaque nouveau permis qui correspond à vos critères : centre et rayon (5 km par défaut, 200 km au plus), types de permis, superficie minimale, état. Seuls les permis de votre périmètre partent : départements de votre formule et sa fenêtre d’historique (Gratuit : nouveaux permis des 2 dernières publications Sitadel ; Découverte : 6 derniers mois ; Explorateur : 12 derniers mois) ; une zone qui ne touche aucun de vos départements est refusée (403). Si votre formule change, une alerte qui sort du nouveau périmètre ou dépasse son nombre d’alertes passe en pause (champ pause_reason) et reprend si la formule la couvre de nouveau ; rien n’est envoyé pour un compte désactivé. La réponse de création contient le webhook_secret, renvoyé une seule fois.
Fiche de l’entreprise qui a déposé le permis (base SIRENE de l’INSEE, via l’API Recherche d’entreprises) : raison sociale, SIREN, SIRET du siège, code APE, forme juridique, date de création, entreprise active ou non. Si le demandeur n’est pas identifié (particulier, nom absent), les champs de match valent null.
Tous les permis (PC, PA, PD, DP) déclarés sur une parcelle : section et numéro cadastraux, avec le code commune (comm_code) pour ne pas mélanger les communes, car une même section existe dans des milliers de communes. À Paris, Lyon et Marseille, le code commune Sitadel est celui de la ville (75056, 69123, 13055). La réponse est une liste.
Jusqu’à 5 ventes immobilières voisines (3 par défaut), choisies parmi les ventes DVF de 2021 à 2025 et classées par pertinence (distance, date, type de bien), avec le prix médian au m² quand il est calculable. Un permis récent peut n’en avoir aucune.
Note de 0 à 100 et niveau (low, medium, high, premium) qui estime si un permis est une opportunité pour un marchand de biens. Heuristique pondérée sur 11 signaux (version v0.3) ; le détail signal par signal, avec une explication en français, est sur /v1/permits/{num_pa}/score/explain.
Réponse réelle de l’API au 9 octobre 2026, pour la requête ci-dessus ; les valeurs évoluent avec les données.
JSON
{
"num_pa": "07510523V0020",
"permit_id": 882974,
"score": 66,
"tier": "high",
"components": {
"type": 40, "surface": 100, "dvf_value": 95, "dep_activity": 100,
"demandeur": 50, "dvf_coherence": 40, "density": 80, "plu": 50,
"risk": 60, "sirene": 50, "building_density": 50
},
"weights": {
"type": 0.14, "surface": 0.09, "dvf_value": 0.16, "dep_activity": 0.08,
"demandeur": 0.1, "dvf_coherence": 0.08, "density": 0.05, "plu": 0.11,
"risk": 0.08, "sirene": 0.03, "building_density": 0.08
},
"version": "v0.3",
"method": "heuristique pondérée (11 signaux v0.3)",
"dvf_matches_used": 5,
"dvf_median_price_per_m2": 9583.33,
"dvf_median_sample_size": 4,
"dvf_median_basis": "Médiane de 4 ventes (surface bâtie de 10 à 1 000 m²) parmi 5 ventes voisines retenues (au moins 1 000 €, une par mutation) ; même valeur partout, quel que soit le nombre de ventes affichées.",
"density_class": 1
}
GET/v1/permits/{num_pa}/pluRégional et plus
Zonage urbanisme PLU
Zone urbaine, à urbaniser, agricole ou naturelle, et verdict constructible. Source en direct : Géoportail de l’Urbanisme via apicarto.ign.fr. has_plu vaut false si la commune n’a pas publié son PLU sur le Géoportail.
Risques recensés pour la commune selon la nomenclature GASPAR (inondation, mouvement de terrain, séisme, risque industriel, transport de marchandises dangereuses...), sites Seveso à moins de 2 km du permis, score de 0 à 100 et niveau, avec les raisons du niveau (risk_reasons : d’où viennent les points). Ce sont les risques de la commune entière, pas ceux de l’adresse. Source : API Géorisques.
Réponse réelle de l’API au 9 octobre 2026, pour la requête ci-dessus ; les valeurs évoluent avec les données.
JSON
{
"num_pa": "07510523V0020",
"comm_code": "75056",
"risk_score": 35,
"risk_tier": "moderate",
"risk_tier_label": "modéré",
"risk_summary": "Niveau modéré (35 sur 100) : 2 risques recensés pour la commune par l’État (base GASPAR de Géorisques), 1 site Seveso à moins de 2 km du permis. Ce sont les risques de la commune entière, pas ceux de l’adresse ; 1 risque recensé a un plan de prévention opposable, ses points comptent x1,5 (GASPAR, fichier du 05/10/2026). Niveaux : faible sous 25, modéré de 25 à 54, élevé de 55 à 74, critique à partir de 75.",
"risk_reasons": [
"Inondation : risque recensé pour la commune, plan de prévention opposable, +15 points",
"1 site Seveso à moins de 2 km du permis (TRIADIS SERVICES, 339 m), +15 points",
"Transport de marchandises dangereuses : risque recensé pour la commune, +5 points"
],
"risks": [
{
"code": "INONDATION",
"label": "Inondation",
"has_ppr": true,
"ppr_type": "PPRN-I",
"ppr_nom": "PPRi de Paris - Révision",
"ppr_lu_le": "2026-10-05"
},
{
"code": "TMD",
"label": "Transport de marchandises dangereuses",
"has_ppr": false,
"ppr_type": null,
"ppr_nom": null,
"ppr_lu_le": "2026-10-05"
}
],
"icpe_proches": [
{
"nom": "TRIADIS SERVICES",
"regime": "Seveso seuil bas",
"distance_m": 339,
"activite": "38"
}
],
"fetch_errors": [],
"source": "Georisques (BRGM + Ministere Transition Ecologique)",
"fetched_at": "2026-10-09T05:00:18.767623+00:00",
"disclaimer": "Les risques retournés sont ceux de la commune et le score est heuristique. icpe_proches liste les sites Seveso à moins de 2 km du permis (distance_m en mètres) ; un permis non géocodé n'en a aucun et n'a donc pas de bonus Seveso. Pour une analyse juridique, consulter le DDRM (Dossier Départemental des Risques Majeurs) et le notaire.",
"method": "cache (commune_risks)"
}
GET/v1/permits/exportBusiness et Entreprise
Export CSV en masse (streaming)
Export CSV en flux, UTF-8, séparateur virgule, 15 colonnes fixes (num_pa, dep_code, comm_code, adr_localite_ter, adr_codpost_ter, permit_type, etat_pa, an_depot, date_reelle_autorisation, superficie_terrain, siren_dem, denom_dem, lat, lng, geocoding_score). Plafond : 100 000 lignes en Business, 1 million en Entreprise. Filtres dep_code, comm_code, permit_type, date_from, date_to, etat_pa, max_rows.
Gratuit et Découverte : 1 département ; Explorateur et Régional : jusqu’à 5. Choix définitif ; passer à une formule supérieure permet un nouveau choix.
Chaque webhook arrive avec l’en-tête X-PermisAPI-Signature: sha256=<hex>. Vérifiez-le en temps constant avec hmac.compare_digest.
curl
# Le webhook arrive avec le header X-PermisAPI-Signature
# Format : sha256=<hex>
# Calculez le hex localement avec openssl :
echo -n "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"
# Comparez-le à l'en-tête reçu en temps constant (compare_digest)
6
Codes d’erreur
Code
Champs de la réponse
Cause
400
detail
num_pa mal formé (variable non remplacée, valeur collée deux fois, longueur incorrecte)
401
detail
en-tête X-API-Key absent, mal formé ou clé inconnue
402
detail, upgrade
donnée avancée non incluse dans votre formule (ventes, note, PLU, risques, parcelle...) : la réponse indique la formule qui la débloque
403
detail
département hors de votre périmètre (recherche ou zone d’une alerte), fiche d’un permis hors de la fenêtre d’historique de votre formule (la réponse indique la formule la moins chère qui le montre), fonction non incluse (export, recherche par parcelle), limite d’alertes atteinte, compte désactivé ou adresse IP non autorisée
404
detail
permis ou territoire introuvable (ou hors de votre périmètre)
422
"error": "validation_error"
paramètre invalide (type, borne, valeur non prévue)
429
detail
quota mensuel atteint, ou coupe-circuit de 600 requêtes par minute (en-tête Retry-After)
500
"error": "internal_error"
erreur côté serveur (journalisée)
503
"error": "database_error" (ou detail)
service momentanément indisponible (base de données, paiement Stripe, cadastre)
7
Limites par formule
Formule
Requêtes par mois
Alertes
Prix par mois
Gratuit
500
1
0 €
Découverte
2 000
10
19 €
Explorateur
5 000
10
49 €
Régional
10 000
50
99 €
Pro
50 000
50
199 €
Business
500 000
200
499 €
Entreprise
jusqu’à 100 millions
10 000
sur devis
Le prix affiché est le prix payé. Les formules payantes sont réservées aux professionnels (conditions générales).
Seul le quota mensuel est une limite de formule. Un coupe-circuit de sécurité, le même pour toutes les formules, répond 429 au-delà de 600 requêtes par minute.
Certaines routes comptent plus d’une requête : les recherches (liste, rayon, parcelle) comptent une requête par permis renvoyé, les routes composées plusieurs (par exemple 6 pour la vue complète d’un permis). Ainsi GET /v1/permits?dep_code=75&limit=50 consomme 50 requêtes s’il renvoie 50 permis, et 1 s’il n’en renvoie aucun. L’en-tête X-RateLimit-Cost donne le coût de chaque appel ; les appels en erreur et les routes /v1/alerts ne comptent pas.
Historique : en Gratuit, toutes les recherches (liste, rayon, recherche par texte) et les fiches ne portent que sur les nouveaux permis des 2 dernières publications Sitadel, quelle que soit leur date d’autorisation. L’en-tête X-PermisAPI-Publications donne les dates de ces publications (ISO, séparées par des virgules, de la plus ancienne à la plus récente). En Gratuit, date_from et date_to filtrent ces permis et ne sont jamais refusées.
En Découverte (180 jours) et en Explorateur (365 jours), les recherches et les fiches portent sur les permis autorisés depuis la date donnée par l’en-tête X-PermisAPI-History-From, plus ceux de ces 2 publications, même sans date_from. Une date_from ou une date_to antérieure n’est pas refusée : elle filtre cette fenêtre (les permis plus anciens de ces 2 publications y restent). Dans toutes les formules à fenêtre, la fiche d’un permis hors fenêtre renvoie 403 avec la formule la moins chère qui le montre. L’historique complet (depuis 2013) commence avec Régional.
GET /v1/me décrit votre fenêtre dans fenetre_historique : type (publications, jours ou complet), jours, debut et publications. La route publique GET /v1/public/departements-volumes donne, par département, le nombre de permis visibles en Gratuit (gratuit) et, dans publications, les dates de ces publications.