Startup PropTech : intégrer PermisAPI dans une application Next.js
Pour qui : développeur PropTech seul ou petite équipe, Next.js et TypeScript côté serveur.
Temps : 1 à 2 heures pour l’intégration initiale.
Budget : 0 € pour commencer (accès gratuit de PermisAPI), puis selon le volume.
Cas d’usage
Votre produit PropTech :
- affiche les permis autour d’un bien immobilier ;
- calcule un indicateur « dynamisme du quartier » à partir du volume de permis sur 12 mois ;
- prévient l’utilisateur quand un nouveau permis apparaît près de chez lui.
Architecture
PermisAPI <---> Votre serveur (Next.js) <---> Votre cache <---> Votre interface
^
|
Votre route webhook (reçoit les alertes)
Étape 1. Dépendances
npm install axios zod
Étape 2. Un client TypeScript typé
lib/permisapi.ts :
import axios, { AxiosInstance } from "axios";
import { z } from "zod";
// Champs de /v1/permits/near (liste triée par distance croissante)
const PermitNearSchema = z.object({
num_pa: z.string(),
dep_code: z.string().nullable(),
comm_code: z.string().nullable(),
adr_localite_ter: z.string().nullable(),
full_address: z.string().nullable(),
lat: z.number().nullable(),
lng: z.number().nullable(),
etat_pa: z.number().nullable(), // 2 autorisé, 4 annulé, 5 travaux commencés, 6 terminés
an_depot: z.number().nullable(),
date_reelle_autorisation: z.string().nullable(),
permit_type: z.string().nullable(),
superficie_terrain: z.number().nullable(),
denom_dem: z.string().nullable(),
distance_m: z.number(),
});
export type PermitNear = z.infer<typeof PermitNearSchema>;
const CommuneStatsSchema = z.object({
code: z.string(),
libelle: z.string().nullable(),
total_permits: z.number(),
last_12_months_count: z.number(),
trend_yoy_pct: z.number().nullable(),
top_permit_types: z.record(z.number()),
});
export type CommuneStats = z.infer<typeof CommuneStatsSchema>;
export class PermisAPIClient {
private http: AxiosInstance;
constructor(apiKey: string) {
this.http = axios.create({
baseURL: "https://api.permisapi.fr",
headers: { "X-API-Key": apiKey },
timeout: 10_000,
});
}
async permitsNear(lat: number, lng: number, radiusM = 1000, limit = 50): Promise<PermitNear[]> {
const resp = await this.http.get("/v1/permits/near", {
params: { lat, lng, radius_m: radiusM, limit },
});
return z.array(PermitNearSchema).parse(resp.data); // liste nue, sans enveloppe
}
async statsCommune(code: string): Promise<CommuneStats> {
const resp = await this.http.get(`/v1/stats/commune/${code}`);
return CommuneStatsSchema.parse(resp.data);
}
}
À noter : /v1/permits (la recherche par filtres) renvoie, lui, une enveloppe
{"data": [...], "pagination": {"page", "limit", "total", "has_next", "next_url"}}.
Étape 3. Un cache côté serveur (important)
Chaque permis renvoyé compte pour une requête : un appel /near avec limit=50 peut en
consommer 50. L’accès gratuit en compte 500 par mois. Mettez donc les réponses en cache, par
exemple une heure, sur une clé arrondie :
// lib/cachedPermisapi.ts
import { PermisAPIClient, type PermitNear } from "./permisapi";
import { cache } from "./cache"; // votre cache (Redis, base, mémoire) : get / set avec durée
const api = new PermisAPIClient(process.env.PERMISAPI_KEY!);
export async function permitsNearCached(lat: number, lng: number, radiusM = 1000): Promise<PermitNear[]> {
// 3 décimales, soit environ 100 m : les recherches voisines partagent la même entrée.
const key = `permits:${lat.toFixed(3)}:${lng.toFixed(3)}:${radiusM}`;
const cached = await cache.get(key);
if (cached) return JSON.parse(cached);
const fresh = await api.permitsNear(lat, lng, radiusM);
await cache.set(key, JSON.stringify(fresh), 3600);
return fresh;
}
Les données changent peu : la source officielle (Sitadel) est publiée une fois par mois.
Étape 4. Une route Next.js pour votre interface
app/api/permits-near/route.ts :
import { NextRequest, NextResponse } from "next/server";
import { permitsNearCached } from "@/lib/cachedPermisapi";
export async function GET(req: NextRequest) {
const sp = req.nextUrl.searchParams;
const lat = Number(sp.get("lat"));
const lng = Number(sp.get("lng"));
if (!Number.isFinite(lat) || !Number.isFinite(lng)) {
return NextResponse.json({ error: "lat et lng obligatoires" }, { status: 400 });
}
const permits = await permitsNearCached(lat, lng);
return NextResponse.json({ permits });
}
Important : n’exposez jamais votre clé PermisAPI au navigateur. Toutes les requêtes passent par votre serveur.
Étape 5. Un indicateur de dynamisme du quartier
import { PermisAPIClient } from "@/lib/permisapi";
const api = new PermisAPIClient(process.env.PERMISAPI_KEY!);
export async function dynamisme(commCode: string) {
const s = await api.statsCommune(commCode);
// Formule d'exemple, à ajuster à votre produit
const volume = Math.min(s.last_12_months_count / 100, 1); // 0 à 1
const tendance = Math.max(Math.min((s.trend_yoy_pct ?? 0) / 50, 1), -1); // -1 à 1
return {
score: Math.round((volume * 0.6 + ((tendance + 1) / 2) * 0.4) * 100),
volume,
tendance,
brut: s,
};
}
Étape 6. Recevoir les alertes
Une alerte (POST /v1/alerts : un centre, un rayon, des types de permis, une surface
minimale) envoie une fois par jour, à votre adresse HTTPS, chaque nouveau permis géolocalisé
qui y correspond. Chaque envoi est signé : l’en-tête X-PermisAPI-Signature vaut sha256=
suivi du HMAC SHA-256 du corps, calculé avec le secret donné à la création de l’alerte.
// app/api/permisapi-webhook/route.ts
import crypto from "crypto";
import { NextRequest, NextResponse } from "next/server";
export async function POST(req: NextRequest) {
const body = await req.text();
const recu = req.headers.get("x-permisapi-signature") ?? "";
const attendu =
"sha256=" +
crypto.createHmac("sha256", process.env.PERMISAPI_WEBHOOK_SECRET!).update(body).digest("hex");
const ok =
recu.length === attendu.length &&
crypto.timingSafeEqual(Buffer.from(recu), Buffer.from(attendu));
if (!ok) {
return NextResponse.json({ error: "signature invalide" }, { status: 401 });
}
const event = JSON.parse(body);
// event = { event: "permit.matched", alert: { id, name }, permit: { num_pa, permit_type,
// etat_pa, date_reelle_autorisation, adr_libvoie_ter, adr_localite_ter, adr_codpost_ter,
// lat, lng, superficie_terrain, denom_dem, siren_dem }, delivered_at }
await enregistrerPermis(event.permit); // vos fonctions
await prevenirUtilisateur(event.permit);
return NextResponse.json({ ok: true });
}
Répondez par un code 2xx : sinon l’envoi est noté en échec (visible dans
GET /v1/alerts/{id}) et ne repart qu’après POST /v1/alerts/{id}/replay.
Étape 7. Mise en production
Variables d’environnement à définir sur votre hébergement :
PERMISAPI_KEY=pk_live_...
PERMISAPI_WEBHOOK_SECRET=...
Budget
- PermisAPI, accès gratuit : 0 € (1 département, 6 mois d’historique, 500 requêtes par mois, 1 alerte).
- Votre hébergement et votre cache : selon votre fournisseur.
Quand passer à une formule payante ?
- Plus de volume ou plusieurs départements : Explorer (49 € par mois, 5 départements au choix, 5 000 requêtes, 10 alertes).
- Historique complet depuis 2013 et données avancées (entreprise du demandeur, prix des ventes voisines, parcelle, zonage, risques, note d’opportunité) : Régional (99 € par mois, 5 départements, 10 000 requêtes).
- France entière : Pro (199 € par mois, 50 000 requêtes).
Étapes suivantes
- Ajouter le prix des ventes voisines (
GET /v1/permits/{num_pa}/dvf, dès Régional). - Ajouter la note d’opportunité (
GET /v1/permits/{num_pa}/score, dès Régional). - Le SDK Python officiel :
pip install permisapi-client.