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.
- Découvrir les jeux et leurs colonnes : appelez `GET /api/v1/jeux` pour lister tous les jeux servis, ou
GET /api/v1/jeux/{jeu}/schemapour obtenir le schéma détaillé d'un seul jeu (colonnes filtrables, indexées, groupables, mesurables, clé de tri et fraîcheur). - Lire des lignes filtrées : appelez `GET /api/v1/jeux/{jeu}` avec vos filtres, vos colonnes choisies (
champs) et la pagination par curseur. - 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.
| Opérateur | Sens | Exemple |
|---|---|---|
eq | Égal à la valeur. | filtre[code_insee][eq]=76540 |
in | Dans une liste de valeurs séparées par des virgules (1 000 au plus). | filtre[departement][in]=75,92,93 |
lt | Strictement inférieur. | filtre[prix_m2][lt]=3500 |
lte | Inférieur ou égal. | filtre[prix_m2][lte]=3500 |
gt | Strictement supérieur. | filtre[pop_totale][gt]=10000 |
gte | Supérieur ou égal. | filtre[annee][gte]=2024 |
entre | Entre deux bornes comprises, séparées par une virgule. | filtre[annee][entre]=2023,2025 |
prefixe | Commence par la chaîne (colonnes texte). | filtre[code_postal][prefixe]=76 |
nul | Vrai si la colonne est vide, faux si elle est remplie. | filtre[prix_m2][nul]=false |
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_bpour 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 danscurseur_suivantvia le paramètrecurseurjusqu'à obtenirnull. - 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).
| Fonction | Alias | Syntaxe |
|---|---|---|
nombre | count | nombre:prix_m2 |
somme | sum | somme:valeur_fonciere |
moyenne | avg | moyenne:prix_m2 |
mediane | median | mediane:prix_m2 |
quantile | Aucun | quantile:prix_m2:0.9 |
min | Aucun | min:prix_m2 |
max | Aucun | max:prix_m2 |
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
| Cas d'usage | Facturation |
|---|---|
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é. |
- 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