Jeux de données

2 opérations servies.

/

Lecture structurée d'un jeu de données

GET/api/v1/jeux/{jeu}

Les lignes d'un jeu de données, sans SQL : filtre[colonne][operateur]=valeur sur les colonnes filtrables du jeu (eq, in, lt, lte, gt, gte, entre, prefixe, nul ; combinés par « et »), colonnes choisies par champs, pagination par curseur. Un jeu volumineux exige au moins un filtre sur une colonne indexée (schéma du jeu : GET /jeux/{jeu}/schema). Les lignes sont triées par la clé de tri du jeu, en ordre croissant ; aucun autre tri n'est offert. Toute ligne passe le retrait des particuliers : les professionnels sont nommés, un particulier jamais. Un jeu marqué creneau_lourd n'est pas lu de 20h30 à minuit (heure de Paris) ; une lecture trop large pour le délai de la base répond 503 : resserrez les filtres.

Coût: 1 crédit par tranche de 10 lignes rendues ; 1 crédit par élément rendu pour un jeu calculé par Pillr
Accès: À l'usage ou avec l'abonnement Data
Portée: jeux
Outil MCP: lire_jeu
Bac à sable: Oui, sans débit, sur un jeu figé
Mémoire: 1 h
Délai: 8 s

Essayer en direct

Paramètres

jeutexteobligatoire
Nom du jeu, tel que GET /jeux le liste.
Valeurs : annonces, evenements_prix, diffusions, communes, prix_iris, loyers, mutations, indice_travaux, adresses, dvf, dvf_ancien, ban, dpe_existant, dpe_neuf, dpe_tertiaire, dpe_ancien, audits, coproprietes, permis_logements, permis_locaux, permis_demolir, permis_amenager, bodacc, lovac, plu, signaux_communes, marche_commune, agences_commune, sirene_immobilier, annonces_archives, biens
filtreobjet
Filtres : filtre[colonne][operateur]=valeur, 12 au plus, combinés par « et ». Opérateurs : eq, in, lt, lte, gt, gte, entre, prefixe, nul. Les colonnes filtrables et leurs opérateurs sont dans le schéma du jeu ; un jeu volumineux exige au moins un filtre sur une colonne indexée.
champsvaleur
Colonnes rendues, séparées par des virgules ; toutes si absent. Les colonnes de la clé de tri sont toujours rendues (elles portent le curseur).
limiteentier
Nombre d'éléments par page (1000 au plus).
de 1 à 1 000 ; par défaut 100
curseurtexte
Curseur opaque rendu par la page précédente (curseur_suivant), à repasser tel quel.
de 1 à 1 024 caractères

Exemple d'appel

curl https://pillr.fr/api/v1/jeux/{jeu} \
  -H "Authorization: Bearer $PILLR_CLE"

Réponse

jeutexte
titretexte
basetexte
Valeurs : servie, lac
naturetexte
Valeurs : calcule_pillr, public_brut
colonnesliste d'objets
Les colonnes rendues, dans l'ordre du schéma du jeu, avec leur type Postgres.
Afficher les 2 champsMasquer
- nomtexte
- typetexte
cle_triliste de textes
lignesliste d'objets
Les lignes, triées par la clé du jeu, en ordre croissant (une valeur vide en dernier).
Afficher les 13 champsMasquer
- vendeur_nomvaleurfacultatif
- vendeur_enseignevaleurfacultatif
- vendeur_sirenvaleurfacultatif
- vendeur_telephonevaleurfacultatif
- vendeur_emailvaleurfacultatif
- vendeur_identifiant_portailvaleurfacultatif
- publisher_typevaleurfacultatif
- annonce_publishervaleurfacultatif
- annonce_empreinte_publishervaleurfacultatif
- prenomvaleurfacultatif
- titrevaleurfacultatif
- titlevaleurfacultatif
- descriptionvaleurfacultatif
nentier
Lignes rendues dans cette page.
0 au moins
volume_jeunombre ou null
Nombre de lignes du jeu entier, estimé à sa déclaration ; ce n'est pas le nombre de lignes filtrées.
donnees_dutexte ou null
Date des données : dernier chargement de la source publique, ou date la plus récente des lignes servies ; null si inconnue.
retrait_particulierstexte
qualiteobjet
Ce qui permet de juger la valeur : nombre, provenance, incertitude, drapeaux, date et source.
Afficher les 7 champsMasquer
- nentier ou null
  Nombre d'observations derrière la valeur ; null si sans objet.
  0 au moins
- provenancetexte ou null
  mesure : observé sur la donnée ; estime : modèle, barème ou imputation ; null : sans objet.
  Valeurs : mesure, estime
- incertitudeobjet ou null
  Incertitude de la valeur : fourchette et demi-largeur.
  Afficher les 3 champsMasquer
  - demi_largeur_pctnombre ou null
    Demi-largeur de la fourchette, en % de la valeur.
  - basnombre ou null
  - hautnombre ou null
- drapeauxliste de textes
  Ce qui doit faire lire la valeur avec prudence ; vide si rien.
  Valeurs : prix_atypique, surface_atypique, vente_en_bloc, doublon_probable, date_estimee, peu_d_observations, valeur_imputee, rattachement_incertain, donnee_ancienne
- methodetexte ou null
  Méthode de calcul ou de rattachement, en clair.
- donnees_dutexte ou null
  Date de la donnée (AAAA-MM-JJ ou horodatage ISO 8601).
- sourcetexte
  Source publique ou moteur Pillr, en clair.
curseur_suivanttexte ou null
Curseur de la page suivante, à repasser dans curseur ; null sur la dernière page.
creditsobjet
Crédits débités par cet appel (réservés, pour une tâche en cours), et crédits encore utilisables ce mois avant la coupure : crédits offerts, crédits inclus du mois et crédits facturables sous le plafond de dépense (null si inconnus ou en bac à sable).
Afficher les 2 champsMasquer
- debitesentier
  0 au moins
- restantsentier ou null

Erreurs possibles

400parametres_invalidesUn paramètre manque ou ne passe pas son contrôle ; le détail est donné champ par champ
401cle_absenteL'en-tête Authorization manque
401cle_invalideLa clé est inconnue, révoquée ou expirée
403organisation_suspendueL'organisation de la clé n'est pas active
403portee_insuffisanteLa clé ou l'accès de l'organisation n'ouvre pas cette opération
403hors_bac_a_sableUne clé pk_test_ demande une entrée hors du jeu figé de l'opération
402credits_insuffisantsLes crédits ne suffisent plus pour cet appel
429plafond_cleLe plafond mensuel de crédits de la clé est atteint
429quota_minuteLe débit par minute de l'organisation est atteint
503charge_globaleL'API est momentanément surchargée, tous clients confondus ; rien n'est débité
504delai_depasseLe calcul dépasse le délai de l'opération ; rien n'est débité
503service_indisponibleL'API est momentanément indisponible
500erreur_interneUne erreur de notre côté ; rien n'est servi ni débité

Une ressource absente répond par un code de la famille des ressources absentes, propre à l'opération, sans débit.

Agrégats sur un jeu de données

GET/api/v1/jeux/{jeu}/agregats

Des agrégats sur un jeu, avec les filtres de lire_jeu : le nombre de lignes de chaque groupe (n, toujours rendu) et des mesures sur les colonnes mesurables (nombre, somme, moyenne, médiane, quantile, minimum, maximum ; médiane et quantiles continus), groupées par 3 colonnes groupables au plus. Les groupes les plus nombreux d'abord, 1000 au plus. Aucun seuil ne masque un groupe : un petit groupe est servi avec son n et le drapeau peu_d_observations. Servi depuis la mémoire seulement de 20h30 à minuit (heure de Paris).

Coût: 5 crédits par appel réussi
Accès: À l'usage ou avec l'abonnement Data
Portée: jeux
Outil MCP: agreger_jeu
Bac à sable: Oui, sans débit, sur un jeu figé
Mémoire: 6 h
Délai: 20 s