# Référence & Guides de l'API REST

L'API de CLAIR est un serveur Fastify (`apps/api`) qui lit la base PostgreSQL par Prisma et met ses réponses en cache dans Redis. Elle est **publique, gratuite, sans authentification et en lecture seule** : l'ingestion écrit dans la base directement, pas par l'API.

---

## 🌐 Adresses

| | Production | Local |
| :--- | :--- | :--- |
| Base | `https://api.clair.vote` | `http://localhost:3001` |
| Explorateur (Zudoku) | [docs.clair.vote/api](/api) | `http://localhost:3002/api` |
| Swagger UI | [api.clair.vote/docs](https://api.clair.vote/docs) | `http://localhost:3001/docs` |
| Spécification OpenAPI | [api.clair.vote/docs/json](https://api.clair.vote/docs/json) | `http://localhost:3001/docs/json` |

Toutes les routes métier sont sous le préfixe `/api/v1`. La spécification OpenAPI est générée par l'API à partir des schémas de ses routes : c'est elle qui détaille les paramètres et les réponses de chaque route, et l'explorateur de cette documentation la lit telle quelle. L'API est aussi référencée sur data.gouv.fr : [API CLAIR, transparence politique](https://www.data.gouv.fr/dataservices/api-clair-transparence-politique).

---

## 📑 Guides

<FeatureGrid cols={3}>
  <FeatureCard
    icon="🛡️"
    title="Limites et cache"
    description="Niveaux d'accès (10 requêtes par minute en direct), règle de User-Agent, blocage temporaire et durées de cache."
    href="/guide/api-reference/authentification-et-limites"
  />
  <FeatureCard
    icon="👥"
    title="Parlementaires"
    description="Députés et sénateurs : listes, filtres, fiches, votes, amendements et prises de parole."
    href="/guide/api-reference/parlementaires"
  />
  <FeatureCard
    icon="🗳️"
    title="Scrutins et votes"
    description="Scrutins publics des deux chambres, votes nominatifs et débats qui les ont précédés."
    href="/guide/api-reference/scrutins-et-votes"
  />
  <FeatureCard
    icon="📜"
    title="Dossiers et amendements"
    description="Dossiers législatifs, amendements et sous-amendements, sujets regroupant les deux chambres."
    href="/guide/api-reference/dossiers-et-amendements"
  />
  <FeatureCard
    icon="🏢"
    title="Lobbying HATVP"
    description="Représentants d'intérêts, secteurs et actions déclarées."
    href="/guide/api-reference/lobbying-hatvp"
  />
  <FeatureCard
    icon="💻"
    title="Exemples d'intégration"
    description="Appels prêts à l'emploi en cURL, TypeScript, Python et Go."
    href="/guide/api-reference/exemples-integration"
  />
</FeatureGrid>

---

## 🧭 Routes

| Préfixe | Routes |
| :--- | :--- |
| `/parlementaires`, `/deputes`, `/senateurs` | `/`, `/groupes`, `/legislatures`, `/sessions`, `/historique-carriere`, `/compare`, `/:slug`, `/:slug/stats`, `/:slug/rank`, `/:slug/votes`, `/:slug/amendements`, `/:slug/interventions`. Mêmes routes sur les trois préfixes : `/deputes` et `/senateurs` sont restreints à une chambre. Pour une personne passée par les deux chambres, `/:slug/votes`, `/:slug/amendements` et `/:slug/interventions` acceptent `?chambre=assemblee` ou `senat` |
| `/groupes` | `/`, `/:chambre/:slug`, `/:chambre/:slug/stats`, `/:chambre/:slug/votes`, `/:chambre/:slug/alliances`, `/:chambre/:slug/thematiques`, `/:chambre/matrice-alliances` |
| `/scrutins` | `/`, `/tags`, `/annees`, `/periodes`, `/importants`, `/:numero`, `/:numero/votes`, `/:numero/interventions`, `/interventions/:id` |
| `/dossiers` | `/`, `/filters`, `/trending`, `/:uid`, `/:uid/chronologie`, `/:uid/scrutins`, `/:uid/amendements` |
| `/sujets` | `/`, `/featured`, `/categories`, `/:slug`, `/:slug/archive`, `/:slug/documents-lies`, `/:slug/dossiers`, `/:slug/chronologie`, `/:slug/scrutins`, `/:slug/presse`, `/:slug/stats` |
| `/commissions` | `/`, `/:slug`, `/:slug/reunions`, `/:slug/dossiers` |
| `/gouvernements` | `/` (les gouvernements depuis 2007, le plus récent d'abord, avec `nbMembres`, `nbFemmes` et `bilan`, le nombre de recours au 49.3 et de motions de censure), `/:slug` (postes dans l'ordre protocolaire, avec les dates de chaque titulaire et leur `domaine`, et `domaines`, la liste ordonnée des domaines avec leurs libellés ; `bilan` : projets de loi déposés avec leur nature, leur stade et leur ministre chef de file, recours au 49.3 avec le texte visé et les motions qu'ils ont suscitées, motions de censure avec leurs voix et la majorité requise), `/membres/:slug` (une personne qui a été membre du Gouvernement, fiche parlementaire ou non : ses postes et, pour chacun, les projets signés, les réponses en séance par chambre, et pour un Premier ministre ses 49.3 et les motions votées contre son gouvernement). Le domaine d'un portefeuille est un classement de CLAIR, la source n'en donne pas : `null` pour un intitulé que la table ne connaît pas encore. Le bilan commence en juin 2017 (15e législature) : avant, `bilan` vaut `null` et `couverture` `avant_2017`, faute de données, et non zéro. Les ratifications d'ordonnances et les conventions sont comptées à part des textes portés (`portes`). Identifiants de la source : `PO…` (gouvernement, présidence), `PM…` (poste), `PA…` (personne) |
| `/agenda` | `/`, `/evenements`, `/:uid`, `/:uid/debat` |
| `/lobbying` | `/`, `/secteurs`, `/stats`, `/actions`, `/actions/recent`, `/:id`, `/:id/actions` |
| `/senatoriales` | `/2026`, `/2026/sortants`, `/2026/candidats`, `/2026/resultats`, `/2026/resultats/:departement`, `/2026/elus`, `/2026/elus/:slug` |
| `/search` | `/`, `/suggest` |
| `/analytics` | `/stats`, `/groupes`, `/voting-trends`, `/top-deputes`, `/lobbying-sectors`, `/scrutins`, `/dissidents`, `/themes`, `/controverses`, `/lobbying-top` |
| `/homepage` | `GET /` ; `POST /warm` (réservé au trafic interne de CLAIR, voir [Limites & Cache](/guide/api-reference/authentification-et-limites)) |
| `/sitemap` | `/` (données du sitemap du site) |
| `/feedback` | `POST /` : retour anonyme depuis le site |

Hors préfixe : `/health`, `/health/ready`, `/health/live`, `/docs`, et `/robots.txt` (qui interdit l'indexation du domaine de l'API).

La recherche (`/search`) passe par des requêtes PostgreSQL (`contains`, insensible à la casse), puis un classement par similarité Jaro-Winkler : il n'y a pas de moteur de recherche dédié.

---

## ✍️ La seule écriture publique

`POST /api/v1/feedback` enregistre un retour anonyme envoyé depuis le site, dans la table `feedbacks`. Champs : `type` obligatoire (`bug`, `idee` ou `autre`) ; `sentiment` (`positif`, `neutre`, `negatif`), `message` (2 000 caractères au plus), `email` et `page`, facultatifs. Si `FEEDBACK_DISCORD_WEBHOOK_URL` est défini, le retour est aussi notifié à l'équipe sur Discord.

---

## ⚙️ Autres comportements

- **Compression** gzip ou deflate des réponses de plus de 1 Ko (`@fastify/compress`).
- **En-têtes de sécurité** avec `@fastify/helmet` (politique CSP en production).
- **CORS** : en production, seules les origines listées dans `CORS_ORIGIN` sont autorisées ; en développement, toutes.
- **Nom des groupes** : l'API renvoie dans `nom` le libellé d'usage (`nom_court`) quand il existe, plutôt que le sigle figé de la source (voir [Modèle Prisma](/donnees/modele-prisma)).
- **Données non exposées** : quelques tables et colonnes ne sortent par aucune route (texte des articles, cosignataires d'un amendement, colonnes techniques, dates de naissance des candidats…). La liste exacte est sur la page [Modèle Prisma](/donnees/modele-prisma).

---

## 📈 Mesure d'usage

En production, l'API mesure son usage avec l'instance Plausible de CLAIR, comme le site (Plausible ne dépose pas de cookie). Chaque réponse, sauf `/health` et les requêtes `OPTIONS` et `HEAD`, envoie un événement après coup, sans retarder la réponse. L'événement contient :

- le **motif** de la route (`/api/v1/deputes/:slug`), jamais le chemin réel ni les paramètres de requête (recherches, filtres) ;
- le canal : `direct` (appel à `api.clair.vote`), `site` (visiteur relayé par le site) ou `interne` (rendu serveur, ingestion) ;
- le code de statut HTTP ;
- le nom court du client tiré de son User-Agent (`curl/8.5.0` donne `curl/8.5.0`, tout navigateur donne `navigateur`) ;
- le référent (`Referer`), quand la requête en porte un.

L'adresse IP du client est transmise à Plausible, qui s'en sert pour compter les visiteurs uniques et situer leur pays. La mesure ne s'active que si `PLAUSIBLE_EVENTS_URL` est défini ; elle est inactive en local et dans les tests.
