Développeurs

Documentation API

L'API Pourquijevote est publique et gratuite pour les usages non-commerciaux. Tous les endpoints renvoient du JSON (UTF-8). La documentation interactive complète est disponible sur /docs (Swagger UI) et /redoc.

⚖️ Attribution requise

Toute réutilisation de données issues de l'API doit citer « Pourquijevote » et inclure un lien vers https://pourquijevote.com. Pour les exports de jeux de données entiers, la licence ODbL 1.0 s'applique.

URL de base

https://pourquijevote.com/api/v1

Toutes les URLs ci-dessous sont relatives à cette racine. Les réponses sont paginées quand limit / cursor sont disponibles.

Endpoints publics

GET/politicians

Liste paginée des personnalités politiques. Filtres combinables.

Paramètre	Description
`q`opt.	Recherche plein texte sur le nom
`party`opt.	Slug du parti
`sort`opt.	freshness \| name \| updated_at (défaut : name)
`limit`opt.	Nombre de résultats (max 100)

GET/politicians/{slug}

Profil complet d'une personnalité : bio, positions, citations, affiliations, sources.

GET/parties

Liste de tous les partis politiques indexés.

GET/parties/{slug}

Détail d'un parti : description, membres, sources.

GET/search

Recherche transversale (personnalités, partis, contenus, discours).

Paramètre	Description
`q`	Terme recherché

GET/search/semantic

Recherche sémantique par embedding (si FEATURE_SEMANTIC_SEARCH activé). Fallback FTS automatique.

Paramètre	Description
`q`	Requête en langage naturel
`topic`opt.	Filtre thématique
`k`opt.	Nombre de résultats (défaut 20, max 50)

GET/feed

Flux chronologique des faits sourcés : promesses, positions, citations, contenus.

Paramètre	Description
`types`opt.	content,promise,position (virgule-séparé)
`topic`opt.	Thème
`politician`opt.	Slug personnalité
`party`opt.	Slug parti
`cursor`opt.	Token de pagination opaque
`limit`opt.	Résultats par page (max 50)

GET/votes/{scrutin_id}

Détail d'un scrutin (Assemblée nationale ou Sénat) : métadonnées + votes par parti.

Paramètre	Description
`chamber`opt.	AN \| Senat (défaut AN)

GET/export/dataset

Export complet d'un jeu de données en CSV ou Parquet (licence ODbL 1.0).

Paramètre	Description
`entity`	politicians \| parties \| promises \| positions \| quotes \| sources
`format`opt.	csv \| parquet (défaut csv)

GET/audit

Journal public anonymisé des actions de modération (rôle, type d'entité, date — aucun identifiant personnel).

Paramètre	Description
`entity_type`opt.	Filtrer par type d'entité
`limit`opt.	Max 200

Exemples

curl

# Lister les personnalités
curl "https://pourquijevote.com/api/v1/politicians?limit=10"

# Chercher "écologie urbaine"
curl "https://pourquijevote.com/api/v1/search?q=écologie+urbaine"

# Télécharger les promesses en CSV
curl -o promesses.csv "https://pourquijevote.com/api/v1/export/dataset?entity=promises&format=csv"

Python (pandas)

import pandas as pd

# Charger les positions documentées
df = pd.read_csv("https://pourquijevote.com/api/v1/export/dataset?entity=positions&format=csv")
print(df.head())

# Ou directement via requests
import requests
data = requests.get("https://pourquijevote.com/api/v1/politicians/macron-emmanuel").json()
print(data["full_name"], data["current_role"])

JavaScript / TypeScript

// Fil d'actualité — 20 derniers faits
const res = await fetch("https://pourquijevote.com/api/v1/feed?limit=20");
const { items } = await res.json();

// Recherche sémantique
const hits = await fetch(
  "https://pourquijevote.com/api/v1/search/semantic?q=transition+énergétique&k=10"
).then(r => r.json());

Limites de débit

Profil	Requêtes / minute
Anonyme (IP)	60
Authentifié (viewer)	600

En cas de dépassement, l'API renvoie HTTP 429 avec l'en-tête Retry-After.