Aller au contenu

Documentation

Interroger les jeux de données

Lister les jeux disponibles, lire leur schéma, filtrer sans SQL et obtenir des agrégats côté serveur.

Trois opérations, sans SQL

En plus des endpoints métier (communes, adresses, annonces, estimation), l'API expose 56 jeux structurés interrogeables par filtres typés et agrégats côté serveur, sans requête SQL libre. L'ensemble des opérations vit dans le domaine Accès structuré aux jeux.

  1. Découvrir les jeux et leurs colonnes : appelez `GET /api/v1/jeux` pour lister tous les jeux servis, ou GET /api/v1/jeux/{jeu}/schema pour obtenir le schéma détaillé d'un seul jeu (colonnes filtrables, indexées, groupables, mesurables, clé de tri et fraîcheur).
  2. Lire des lignes filtrées : appelez `GET /api/v1/jeux/{jeu}` avec vos filtres, vos colonnes choisies (champs) et la pagination par curseur.
  3. Agréger côté serveur : appelez `GET /api/v1/jeux/{jeu}/agregats` pour regrouper les lignes et calculer des moyennes, médianes, quantiles ou sommes sans télécharger toute la table.

Filtrer les lignes

En HTTP, chaque filtre s'écrit en notation à crochets : filtre[colonne][operateur]=valeur (en MCP, un objet JSON { "colonne": { "operateur": valeur } }). Jusqu'à 12 conditions peuvent se combiner par « et ». Sur un jeu volumineux (filtre_indexe_requis: true dans le schéma), au moins une condition doit porter sur une colonne indexée.

eq
Sens : Égal à la valeur.
Exemple : filtre[code_insee][eq]=76540
in
Sens : Dans une liste de valeurs séparées par des virgules (1 000 au plus).
Exemple : filtre[departement][in]=75,92,93
lt
Sens : Strictement inférieur.
Exemple : filtre[prix_m2][lt]=3500
lte
Sens : Inférieur ou égal.
Exemple : filtre[prix_m2][lte]=3500
gt
Sens : Strictement supérieur.
Exemple : filtre[pop_totale][gt]=10000
gte
Sens : Supérieur ou égal.
Exemple : filtre[annee][gte]=2024
entre
Sens : Entre deux bornes comprises, séparées par une virgule.
Exemple : filtre[annee][entre]=2023,2025
prefixe
Sens : Commence par la chaîne (colonnes texte).
Exemple : filtre[code_postal][prefixe]=76
nul
Sens : Vrai si la colonne est vide, faux si elle est remplie.
Exemple : filtre[prix_m2][nul]=false

Exemple de lecture sur le jeu communes (valide dans le bac à sable avec une clé pk_test_) :

curl -g "https://pillr.fr/api/v1/jeux/communes?filtre[code_insee][eq]=76540&champs=code_insee,commune,prix_m2,loyer_m2,pop_totale" \
  -H "Authorization: Bearer $PILLR_CLE"

Choisir ses colonnes et paginer

  • Réduire la réponse : passez champs=colonne_a,colonne_b pour ne recevoir que les colonnes utiles. Les colonnes de la clé de tri (cle_tri) restent toujours présentes car elles portent le curseur.
  • Paginer de manière stable : passez limite (jusqu'à 1 000 lignes par page selon le jeu), puis renvoyez la valeur reçue dans curseur_suivant via le paramètre curseur jusqu'à obtenir null.
  • Ordre garanti : les lignes sont toujours triées par la clé de tri du jeu en ordre croissant ; aucun tri arbitraire n'est proposé afin de garantir des temps de réponse prévisibles.

Agrégats côté serveur

L'opération `GET /api/v1/jeux/{jeu}/agregats` accepte les mêmes filtres que la lecture, avec en plus grouper (jusqu'à 3 colonnes groupables séparées par des virgules), mesures (jusqu'à 10 mesures au format fonction:colonne) et limite_groupes (jusqu'à 1 000 groupes, les plus nombreux d'abord).

nombre
Alias : count
Syntaxe : nombre:prix_m2
somme
Alias : sum
Syntaxe : somme:valeur_fonciere
moyenne
Alias : avg
Syntaxe : moyenne:prix_m2
mediane
Alias : median
Syntaxe : mediane:prix_m2
quantile
Alias : Aucun
Syntaxe : quantile:prix_m2:0.9
min
Alias : Aucun
Syntaxe : min:prix_m2
max
Alias : Aucun
Syntaxe : max:prix_m2

Le nombre d'observations n est toujours rendu pour chaque groupe. Sous 5 lignes, le groupe reste servi avec le drapeau peu_d_observations dans drapeaux.

Exemple d'agrégat sur le jeu mutations (valide dans le bac à sable avec une clé pk_test_) :

curl -g "https://pillr.fr/api/v1/jeux/mutations/agregats?grouper=type_bien&mesures=mediane:prix_m2,moyenne:valeur_fonciere&filtre[code_insee][eq]=76540" \
  -H "Authorization: Bearer $PILLR_CLE"

Tarification et bac à sable

Catalogue et schémas (GET /jeux)
0 crédit par appel réussi (gratuit avec une clé).
Lecture de jeux DVF et DPE bruts
0 crédit, gratuit avec une clé.
Lecture des autres jeux publics bruts
1 crédit par tranche entamée de 10 lignes rendues.
Lecture des jeux calculés et croisés par Pillr
1 crédit par ligne rendue.
Agrégats (GET /jeux/{jeu}/agregats)
5 crédits par appel réussi, quel que soit le volume agrégé.

L'accès structuré aux jeux reste ouvert en continu, sans coupure horaire. En bac à sable (pk_test_), tout jeu doté d'une colonne de code INSEE répond sans débit lorsqu'il est filtré sur une commune du bac à sable.

Guide suivant : Crédits et facturation

    Interroger les jeux de données | Pillr Data