Aller au contenu
Pour
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.

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.

Recevez chaque mois les nouveaux permis de votre commune

Le lendemain de chaque publication de l’État, une fois par mois, avec l’entreprise qui porte le projet quand c’en est une. Gratuit.

Un e-mail de confirmation part d’abord : rien ne vous est envoyé sans votre clic. Chaque e-mail permet d’arrêter en un clic.

Votre adresse sert seulement à cet envoi, elle n’est ni vendue ni prêtée. Vos données

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.

Les nouveaux permis de votre zone, chaque mois

Un e-mail le lendemain de chaque publication de l’État. Gratuit, sans compte.

Un e-mail de confirmation part d’abord : rien ne vous est envoyé sans votre clic. Chaque e-mail permet d’arrêter en un clic.

Votre adresse sert seulement à cet envoi, elle n’est ni vendue ni prêtée. Vos données

Regardez les permis de votre secteur.

Un département au choix, les nouveaux permis des 2 derniers mois, sans carte bancaire. Une question ? Écrivez à Evan : evan@permisapi.fr

Lire la documentation

Autres tutoriels