Ce site utilise des cookies pour l'analyse de trafic et l'affichage des boutons des réseaux sociaux. Pour de plus amples informations rendez-vous sur cette page.

Concepts généraux

Il existe un certain nombre de concepts au coeur de la plateforme :

Dataset (ou Jeu de données)

Un Dataset est un regroupement logique de données (Records): il est comparable plus simplement par exemple à une feuille Excel (dont chaque ligne serait un Record) ou à une table de base de donnée (dont chaque entrée serait un Record). Un Dataset possède également des "metadatas", qui sont des attributs décrivant le Dataset (par exemple sa date de première publication, son créateur, sa description ou ses mots clés).

Un Dataset contient également la liste des Fields (champs) qui constituent les Records qu'il contient.

Record (ou Enregistrement)

Un Record est une donnée unitaire, comparable à une ligne d'un tableau Excel. Il est constitué de Fields (champs) avec les valeurs associés (comparable aux colonnes d'un tableau Excel).

Domaine

Un Domaine est un espace regroupant des utilisateurs, des données (Datasets), et les services permettant de créer, d'accéder et d'exploiter ces données (par exemple les API de recherche ou l'application Explore).

Un Domaine peut exposer ses services (et ses données) à tous anonymement, ou les restreindre à ses propres utilisateurs. Un Domaine peut également choisir d'inclure dans ses services tous les Datasets publics de la plateforme, ou de se restreindre à ses propres données.

Accès et Authentification

L'accès aux API d'un Domaine peut-être accessible à tous de façon anonyme, ou protégé et restreint aux utilisateurs authentifiés du Domaine. Dans le cas d'un Domaine protégé, l'authentification peut se faire de deux façons:

  • HTTP Basic Authentication en utilisant le login et le mot de passe de l'utilisateur.
  • Une clé d'API, à l'aide du paramètre apikey. Pour générer une clé d'API, il suffit d'ouvrir la page de préférences une fois connecté à la console.
    http://<DOMAIN>/api/datasets/1.0/search/?apikey=<APIKEY>

L'accès aux API peut se faire en HTTP ou HTTPS. Cependant, dans le cas d'un appel authentifié par Basic Auth, il est recommandé d'employer HTTPS, à la fois pour protéger les informations d'authentification, mais également les données renvoyées. Dans le cas d'un appel JSONP depuis un navigateur, faites également attention à d'éventuelles restrictions (par exemple JSONP HTTP depuis une page HTTPS).

Services sur les Datasets

/api/datasets/1.0/search/
Description

Ce service permet de consommer le catalogue de Datasets par des fonctionnalités de recherche, telle la recherche dite "full-text", ou la navigation par Facettes. Il est ainsi possible de proposer aux utilisateurs des possibilités de recherche à la fois simples et intuitives (recherche textuelle "à la Google", mais également d'affiner facilement et précisément les résultats (facettes).

Dans le cas d'une utilisation sans paramètre de recherche, tous les Datasets sont restituées.

Mode de consommation

Ce service se consomme en GET. Le POST est également supporté mais non recommandé pour des raisons de standards.

Les formats de sortie supportés sont JSON et JSONP (en spécifiant un callback).

Paramètres
q

Requête textuelle "full-text". Par défaut, pas de requête, tous les résultats sont renvoyés. Documentation détaillée.

lang

Langage de la requête utilisateur (paramètre q), permettant l'activation de fonctions linguistiques sur la requête. Le langage est un code ISO 639-1 (code à 2 lettres tel que "fr").

facet

Active une Facette pour qu'elle soit incluse dans les résultats (voir Annexe pour la liste des Facettes disponibles); ce paramètre peut-être utilisé plusieurs fois pour activer plusieurs Facettes. Par défaut aucune Facette n'est activée.

facet=modified

refine.<FACET>

Limite les résultats à ceux inclus dans le chemin (path) spécifié pour cette Facette; peut-être utilisé plusieurs fois, pour une même Facette ou pour plusieurs

refine.modified=2012/02

exclude.<FACET>

Exclut les résultats inclus dans le chemin (path) spécifié pour cette Facette; peut-être utilisé plusieurs fois, pour une même Facette ou pour plusieurs

exclude.modified=2011

sort

Trie les valeurs selon le champ spécifié (voir Annexe pour les champs disponibles au tri); par défaut le tri est descendant, mais si précédé d'un '-', le tri est ascendant.

sort=-issued

rows

Nombre de résultats maximum à retourner; -1 pour retourner tous les résultats. Par défaut 10

start

Index du premier résultat à retourner (commence à 0); à combiner avec rows pour implémenter une pagination

pretty_print

Si true, formatte la réponse pour être lisible par un humain (indentation, retours à la ligne)

format

Format de la réponse : JSON (défaut), JSONP

callback

Nom de la fonction JavaScript renvoyé dans le cas d'un format JSONP

Récupération Unitaire (lookup)

/api/dataset/1.0/<DATASETID>/
Description

Ce service permet d'obtenir les informations sur un Dataset donné.

Mode de consommation

Ce service se consomme en GET. Le POST est également supporté mais non recommandé pour des raisons de standards.

Les formats de sortie supportés sont JSON et JSONP (en spécifiant un callback).

Paramètres
datasetid

Dans l'URL, obligatoire : Identifiant du Dataset, mentionné par exemple dans chaque résultat de Record

http://<DOMAIN_ID>/api/dataset/1.0/arbresremarquablesparis2011/?...

pretty_print

Si true, formatte la réponse pour être lisible par un humain (indentation, retours à la ligne)

format

Format de la réponse : JSON (défaut), JSONP

callback

Nom de la fonction JavaScript renvoyé dans le cas d'un format JSONP

Services sur les Records

/api/records/1.0/search
Description

Ce service permet d'effectuer une recherche sur l'ensemble des données d'un Dataset, à travers l'utilisation de fonctionnalités intuitives de recherche telles que la recherche textuelle et la recherche géographique; il permet également la navigation par Facettes pour offrir à l'utilisateur un moyen d'obtenir facilement et précisément les données souhaitées.

Dans le cas d'une utilisation sans paramètre de recherche, toutes les données du Dataset sont restituées.

Mode de consommation

Ce service se consomme en GET. Le POST est également supporté mais non recommandé pour des raisons de standards.

Les formats de sortie supportés sont JSON (ou JSONP en spécifiant un callback) et GeoJSON (callback également possible).

Paramètres
dataset

Obligatoire : Identifiant(s) du Dataset (datasetid) où la recherche a lieu. Plusieurs Datasets peuvent être recherchés, en utilisant plusieurs fois ce paramètre.

q

Requête textuelle "full-text". Documentation détaillée.

lang

Langage de la requête utilisateur (paramètre q), permettant l'activation de fonctions linguistiques sur la requête. Le langage est un code ISO 639-1 (code à 2 lettres tel que "fr").

geofilter.distance

Restreint les résultats à une distance maximale (en mètres) donnée d'un point WGS84 donné : latitude,longitude,distance

geofilter.distance=48.8520930694,2.34738897685,1000

geofilter.polygon

Restreint les résultats à une zone géographique donnée, déterminée par un polygone constitué de points WGS84 : (lat1,lon1),(lat2,lon2),(lat3,lon3)

geofilter.polygon=(48.883086,2.379072),(48.879022,2.379930),(48.883651,2.386968)

facet

Active une Facette pour qu'elle soit incluse dans les résultats (les Facettes disponibles sont indiquées au niveau de la défition du Dataset); ce paramètre peut-être utilisé plusieurs fois pour activer plusieurs Facettes. Par défaut aucune Facette n'est activée.

facet=ville

refine.<FACET>

Limite les résultats à ceux inclus dans le chemin (path) spécifié pour cette Facette; peut-être utilisé plusieurs fois, pour une même Facette ou pour plusieurs

refine.ville=paris

exclude.<FACET>

Exclut les résultats inclus dans le chemin (path) spécifié pour cette Facette; peut-être utilisé plusieurs fois, pour une même Facette ou pour plusieurs.

exclude.creation=2010/12/23

sort

Trie les valeurs selon le champ numérique spécifié (les champs numériques sont indiqués au niveau de la définition du Dataset); par défaut le tri est descendant, mais si précédé d'un '-', le tri est ascendant. Disponible uniquement si la recherche est effectuée sur un seul Dataset.

sort=-largeur

rows

Nombre de résultats maximum à retourner. Par défaut 10. Note : pour un grand nombre de résultats (10 000 ou plus), vous pouvez utiliser le service Téléchargement.

start

Index du premier résultat à retourner (commence à 0); à combiner avec rows pour implémenter une pagination

pretty_print

Si true, formatte la réponse pour être lisible par un humain (indentation, retours à la ligne)

format

Format de la réponse : JSON (défaut), JSONP, GeoJSON, GeoJSONP

callback

Nom de la fonction JavaScript renvoyé dans le cas d'un format JSONP ou GeoJSONP

Téléchargement (download)

/api/records/1.0/download/
Description

Ce service permet de télécharger les données d'un Dataset sous format CSV, en les limitant éventuellement par différents critères de recherche, identiques à ceux du service de recherche.

Dans le cas d'une utilisation sans paramètre de recherche, toutes les données du Dataset sont restituées.

Mode de consommation

Ce service se consomme en GET. Le POST est également supporté mais non recommandé pour des raisons de standards.

Les formats de sortie supportés sont CSV (par défaut), JSON (ou JSONP en spécifiant un callback) et GeoJSON (callback également possible).

Paramètres
q

Requête textuelle "full-text". Par défaut, pas de requête, tous les résultats sont renvoyés. Documentation détaillée.

lang

Langage de la requête utilisateur (paramètre q), permettant l'activation de fonctions linguistiques sur la requête. Le langage est un code ISO 639-1 (code à 2 lettres tel que "fr").

geofilter.distance

Restreint les résultats à une distance maximale (en mètres) donnée d'un point WGS84 donné : x,y,distance

geofilter.distance=48.8520930694,2.34738897685,1000

geofilter.polygon

Restreint les résultats à une zone géographique donnée, déterminée par un polygone constitué de points WGS84 : (x1,y1),(x2,y2),(x3,y3)

geofilter.polygon=(48.883086,2.379072),(48.879022,2.379930),(48.883651,2.386968)

refine.<FACET>

Limite les résultats à ceux inclus dans le chemin (path) spécifié pour cette Facette; peut-être utilisé plusieurs fois, pour une même Facette ou pour plusieurs

refine.modified=2012/11

exclude.<FACET>

Exclut les résultats inclus dans le chemin (path) spécifié pour cette Facette; peut-être utilisé plusieurs fois, pour une même Facette ou pour plusieurs

exclude.modified=2011

format

Format de la réponse : CSV (défaut), JSON, JSONP, GeoJSON, GeoJSONP

callback

Nom de la fonction JavaScript renvoyé dans le cas d'un format JSONP ou GeoJSONP

Analyze (Analyse)

/api/records/1.0/analyze/
Description

Ce service permet d'analyser les données d'un Dataset, en les limitant éventuellement par différents critères de recherche, identiques à ceux du service de recherche.

Ce service prend en paramètre des séries (voir plus bas) et retourne le résultat de ces séries statistique.

Mode de consommation

Ce service se consomme en GET. Le POST est également supporté mais non recommandé pour des raisons de standards.

Le service prend un paramètre X sur lequel agréger les données et une ou plusieurs séries Y qui décrivent la manière de les agréger.

Les formats de sortie supportés sont JSON (par défaut), JSONP (en spécifiant un callback), et CSV.

Paramètres
dataset

Obligatoire : Identifiant du Dataset (datasetid) où la recherche a lieu.

x

Obligatoire : Nom du champ du dataset sur lequel découper les données. Il permet de retourner dans l'analyse un sous ensemble des données en fonction des différentes valeurs des champs

Exemple : pour récuperer la moyenne de la hauteur des arbres par espèces

x=espece_arbre&y.serie1.func=AVG&y.serie.expr=hauteur

Le comportement change en fonction du type du champ :

  • Date ou Datetime : Le découpage est réalisé sur les dates contenues dans le champ. Il est possible de préciser de manière plus fine l'agrégation souhaitée avec les paramètres precision et periodic

    x=date_evenement

  • Autres types : découpage sur les valeurs du champ

    x=espece_arbre

    [{"x": "platane", "serie1": 10.7}, {"x": "chene", "serie1": 12.3}]

y.<SERIE>.<FUNC>

Obligatoire : Fonction à appliquer à chacun des découpage.

Le nom <SERIE> est libre. Il est utilisé pour définir l'expression associée (<EXPR>) et dans la sortie de l'API

Liste des fonctions disponibles :

  • Fonctions ne necessitant pas d'expression (<EXPR>) : COUNT :

    Ces fonctions se basent seulement sur le paramètre X, le paramètre <EXPR> n'est dans ce cas pas utilisé

    x=ville&y.countserie.func=COUNT
  • Fonctions prenant en paramètre supplémentaire une expression : AVG, SUM, MIN, MAX, STDDEV, SUMSQUARES

    Ces fonctions retournent pour chacune des valeurs de X le résultat de la fonction sur l'expression définie dans y.<SERIE><EXPR>

    Par exemple : x=espece_arbre&y.serie1.func=AVG&y.serie1.EXPR=hauteur

    Sortie d'API : [{"x": "platane", "serie1": 14}, {"x": "chene", "serie1": 25}]

y.<SERIE>.<EXPR>

Obligatoire dans le cas des fonctions AVG, SUM, MIN, MAX, STDDEV, SUMSQUARES. Le paramètre <SERIE> doit porter le même nom utilisé pour la fonction.

Le paramètre peut contenir le nom d'un champ numérique du dataset (INT ou DOUBLE), ou une expression mathématique.

Par exemple : x=espece_arbre&y.serie1.func=AVG&y.serie1.expr=0.079578 * hauteur * circonference * circonference

Sortie d'API : [{"x": "platane", "serie1": 0.716}, {"x": "chene", "serie1": 1.114}]

Dans cet exemple, circonference et hauteur sont des champs du dataset

De plus il est possbile d'utiliser un certain nombre de fonctions prédéfinies dans une expression

Les fonctions disponibles sont les suivantes : time, sin, cos, tan, asin, acos, atan, toRadians, toDegrees, exp, log, log10, sqrt, cbrt, IEEEremainder, ceil, floor, rint, atan2, pow, round, random, abs, max, min, ulp, signum, sinh, cosh, tanh, hypot

x=espece_arbre&y.serie1.func=Min&y.serie1.expr=sin(hauteur) * 2

y.<SERIE>.cumulative

Ce paramètre peut prendre comme valeur true ou false (défaut). Si le paramètre est à true les résultats d'une séries seront cumulés avec les valeurs précédentes

maxpoints Permet de limiter le nombre de réponses retournées. Par défaut aucune limite.
periodic

Utilisé seulement dans le cas où X est de type date ou datetime

Définie à quel niveau de date l'agrégation doit se faire. Les valeurs possibles sont year, month, week, weekday, day, hour, minute

Par exemple : x=date_evenement&periodic=weekday&y.serie1.func=count

Résultat : [{"x": {"weekday":0},"serie1": 12}, {"x": {"weekday":1},"serie1": 30}]

Weekday retourne une valeur entre 0 et 6 où 0 est lundi et 6 dimanche. Dans cet exemple, il y a dans le jeu de données 12 évenements le lundi et 30 le mardi

precision

Utilisé seulement dans le cas où X est de type date ou datetime

Définie quel doit être la précision de l'aggrégation. Les valeurs possibles sont year, month, week, day, hour, minute

Ce paramètre est ignoré dans le cas où weekday à été défini comme paramètre periodic

Le paramètre ne peut être plus fin que la précision qui a été défini lors de la publication du dataset

Si le paramètre n'est pas précisé, alors la précision est day par défaut

Par exemple : x=date_evenement&periodic=year&precision=month&y.serie1.func=count

Résultat : [{"x": {"year": 2002, "month":1},"serie1": 3}, {"x": {"year": 2002, "month":1},"serie1": 5}]

sort

Trie les valeurs selon la série spécifiée ou selon le paramètre X. Par défaut le tri est descendant, sur le champ de découpage (paramètre X), mais si précédé d'un '-', le tri est ascendant.

x=ville&y.serie1.func=SUM&y.serie1.expr=population&sort=-x

x=ville&y.serie1.func=SUM&y.serie1.expr=population&sort=-serie1

q

Requête textuelle "full-text". Par défaut, pas de requête, tous les résultats sont renvoyés. Documentation détaillée.

lang

Langage de la requête utilisateur (paramètre q), permettant l'activation de fonctions linguistiques sur la requête. Le langage est un code ISO 639-1 (code à 2 lettres tel que "fr").

geofilter.distance

Restreint les résultats à une distance maximale (en mètres) donnée d'un point WGS84 donné : x,y,distance

geofilter.distance=48.8520930694,2.34738897685,1000

geofilter.polygon

Restreint les résultats à une zone géographique donnée, déterminée par un polygone constitué de points WGS84 : (x1,y1),(x2,y2),(x3,y3)

geofilter.polygon=(48.883086,2.379072),(48.879022,2.379930),(48.883651,2.386968)

refine.<FACET>

Limite les résultats à ceux inclus dans le chemin (path) spécifié pour cette Facette; peut-être utilisé plusieurs fois, pour une même Facette ou pour plusieurs

refine.modified=2012/11

exclude.<FACET>

Exclut les résultats inclus dans le chemin (path) spécifié pour cette Facette; peut-être utilisé plusieurs fois, pour une même Facette ou pour plusieurs

exclude.modified=2011

format

Format de la réponse : JSON (défaut), CSV, JSONP

callback

Nom de la fonction JavaScript renvoyé dans le cas d'un format JSONP

GeoCluster

/api/records/1.0/geocluster/
Description

Ce service permet d'effectuer un clustering géographique sur des points d'un dataset.

Mode de consommation

Ce service se consomme en GET. Le POST est également supporté mais non recommandé pour des raisons de standards.

Le service prend en paramètre la précision du cluster, un polygon représentant la vue actuelle (sur la carte) et retourne un tableau de clusters avec pour chacun le nombre de points qu'il contient et un polygon délimitant le points

Le format de sortie est le JSON.

Paramètres
dataset

Obligatoire : Identifiant du Dataset (datasetid) où la recherche a lieu.

clusterprecision

Obligatoire : Le niveau de precision que l'on souhaite avoir en fonction du niveau de zoom actuel de la carte (dans le cas d'une utilisation depuis Leaflet, le niveau de zoom Leaflet peut être utilisé).

shapeprecision

Permet d'affiner la forme du polygon retourné. La somme de la shapeprecision et du clesterprecision ne doit pas excéder 29.

clustermode

Définit le mode de clustering souhaité. Les valeurs possibles sont polygon (défaut), heatmap et world

Polygon retourne un geoshape décrivant pour chacun des cluster le pourtour des points qu'il contient

Heatmap permet de réaliser une aggrégation plus fine des valeurs, et ne retourne pas le polygon associé

Séries

L'API de geo clustering peut prendre des séries comme celles définies dans l'API d'analyze.

L'agrégation se fait alors sur les clusters retournés

clusterprecision=6&y.serie1.expr=hauteur&y.serie1.func=SUM

q

Requête textuelle "full-text". Par défaut, pas de requête, tous les résultats sont renvoyés. Documentation détaillée.

lang

Langage de la requête utilisateur (paramètre q), permettant l'activation de fonctions linguistiques sur la requête. Le langage est un code ISO 639-1 (code à 2 lettres tel que "fr").

geofilter.distance

Restreint les résultats à une distance maximale (en mètres) donnée d'un point WGS84 donné : x,y,distance

geofilter.distance=48.8520930694,2.34738897685,1000

geofilter.polygon

Restreint les résultats à une zone géographique donnée, déterminée par un polygone constitué de points WGS84 : (x1,y1),(x2,y2),(x3,y3)

Si ce paramètre n'est pas présent, on considère que la zone de recherche est le monde entier

geofilter.polygon=(48.883086,2.379072),(48.879022,2.379930),(48.883651,2.386968)

refine.<FACET>

Limite les résultats à ceux inclus dans le chemin (path) spécifié pour cette Facette; peut-être utilisé plusieurs fois, pour une même Facette ou pour plusieurs

refine.modified=2012/11

exclude.<FACET>

Exclut les résultats inclus dans le chemin (path) spécifié pour cette Facette; peut-être utilisé plusieurs fois, pour une même Facette ou pour plusieurs

exclude.modified=2011

callback

Nom de la fonction JavaScript renvoyé dans le cas d'un format JSONP ou GeoJSONP

Annexes

Identifier un Jeu de Données (Dataset)

Vous cherchez des données précises pour construire une application mais ne savez pas encore dans quel Dataset les trouver ?

Vous pouvez utiliser l'interface de recherche en choisissant Explorer dans le menu en haut de page, et effectuer une recherche full-text sur l'ensemble des jeux de données et/ou jouer sur les filtres (affinages) tels que la source ou le nuage de mots-clés pour trouver le Dataset qui contient les données qui vous intéressent. Une fois sur la page du Dataset, il vous suffit de déplier les détails pour obtenir l'Identifiant que vous pourrez utiliser dans vos appels à l'API Records.

Toute cette démarche est évidemment faisable intégralement via l'API, en utilisant l'API de recherche Datasets pour récupérer l'attribut "datasetid" du Dataset qui vous intéresse.

Utilisation des Facettes

Une Facette est une catégorie à laquelle une entrée (un Dataset ou un Record) peuvent appartenir avec une certaine valeur. Par exemple, pour une Facette "ville", un Record pourrait appartenir à la valeur "Paris".

Les Facettes sont traditionnellement un outil d'aide à l'affinage de résultat dans les applications de recherche. On peut les utiliser pour rapidement restreindre ses résultats grâce à la vue d'ensemble de la répartition des résultats dans les valeurs des Facettes. Ainsi, pour une Facette "Dernière Modification", on pourra voir qu'il y a 240 résultats modifiés en 2012, 130 en 2011, et affiner ses résultats (affinages) sur 2011.

Récupération et Répartition

Par défaut, que ce soit pour les Datasets ou les Records, aucune Facette n'est activée. Pour cela, il faut activer les Facettes voulues par le paramètre "facet", en spécifiant le nom de la Facette. Dans le cas d'un Dataset, les Facettes sont standard (tous les Datasets ont les mêmes) et sont décrites dans une Annexe. Dans le cas de records, les Facettes disponibles sont définies au sein du Dataset contenant les Records :

...
"fields": [
    ...
    {
        "label": "VARIETE",
        "type": "text",
        "name": "variete",
        "annotations": [
            {
                "name": "facet"
            }
        ]
    },
    ...

Les Facettes sont retournées à la fin des résultats retournés par la requête.

A chaque valeur correspond un name, qui est une valeur affichable dans une interface par exemple, et un path, qui permet d'effectuer un affinage ou une exclusion sur cette valeur. Les valeurs de Facettes sont sous forme hiérarchique, par exemple une année contient ses mois et ainsi de suite. Une valeur peut donc contenir d'autres valeurs.

Exemple pour les Facettes à l'intérieur d'une entrée :

"facet_groups": [
    {
        "name": "modified",
        "facets": [
            {
                "name": "2012",
                "path": "2012",
                "facets": [
                    {
                        "name": "09",
                        "path": "2012/09",
                        "facets": [
                            {
                                "name": "11",
                                "path": "2012/09/11"
                            }
                        ...

Dans le cas de la répartition des Facettes à la fin du résultat, chaque valeur contient également le nombre d'entrées contenues dans cette valeur (count), ainsi que son état (si elle est actuellement utilisée pour un affinage ou pour une exclusion). Le niveau de profondeur de hiérarchie pour une Facette est limité à 1, sauf si un affinage a lieu sur une valeur, auquel cas la profondeur descend jusqu'au niveau au dessous de la valeur filtrée.

"facet_groups": [
    {
        "name": "modified",
        "count": 45,
        "facets": [
            {
                "name": "2012",
                "path": "2012",
                "count": 24,
                "state": "displayed"
            },
        ...

Affinage

Il est possible de restreindre ses résultats (y compris pour une requête sans critère) en effectuant un affinage sur une valeur d'une Facette.

/api/datasets/1.0/search/?refine.modified=2011

Dans les résultats obtenus, seuls les Datasets appartenant à la valeur 2011 pour la Facette "modified" sont retournés, c'est à dire les Datasets ayant été modifiés en 2011. En réalité, un Dataset sera dans une valeur correspondant au jour de sa dernière modification (2011 > 12 > 04 par exemple), mais puisque les valeurs sont hiérarchiques, elle appartient également au mois et à l'année.

Puisque l'affinage a eu lieu sur l'année, on observe que dans la répartition des Facettes à la fin des résultats, on récupère le niveau inférieur, le mois; également, l'année est marquée comme dans un état "refined" :

facet_groups: [{
        name: "modified",
        count: 20,
        facets: [{
            name: "2011",
            path: "2011",
            count: 20,
            state: "refined",
            facets: [{
                name: "04",
                    path: "2011/04",
                    count: 7,
                    state: "displayed"
Exclusion

Sur le même principe que les affinages, il est possible d'exclure une valeur précise de Facette.

/api/datasets/1.0/search/?exclude.modified=2011

Seuls seront retournés les résultats n'appartenant par à cette valeur pour la Facette "modified".

Contrairement à l'affinage, une exclusion sur une valeur n'étend pas l'affichage de la répartition au niveau directement inférieur; en revanche, la valeur exclue est marquée comme étant dans l'état "excluded".

Facettes disponibles pour les Datasets

modified Date de dernière modification
publisher Publicateur
issued Date de première publication
accrualperiodicity Fréquence de publication
language Langue
license Licence de publication
granularity Granularité des données
dataquality Qualité des données
theme Thème
keyword Mots-clés
created Date de création
creator Créateur
contributor Contributeur

Champs de Tri disponibles pour les Datasets

modified Date de dernière modification
issued Date de première publication
created Date de création

Langage de requête (paramètre q=)

Description

Le langage de requête peut être utilisé avec tous les points d'entrées d'API qui acceptent le paramètre q.

Il permet d'affiner la recherche de base et peut être utilisé en complément des facets.

Recherche "plein texte"

Permet de restreindre le résultat de la recherche sur les élément contenant les mots passés en paramètre

Si la chaine de caractères est entre guillemets alors la recherche ne retourne que les résultats exacts

q=film retourne les entrées contenant film, films, filmographie ...

q="film" retourne les entrées contenant seulement film

Requête booléenne

Le langage de requête supporte les opérateurs booléens : "AND", "OR" et "NOT"

Les espaces dans les requêtes sont considérés comme des opérateurs “AND"

L'utilisation des parenthèses permet de grouper les opérations

Exemples :

q=film OR arbres

q=(film OR arbres) AND paris

Requête sur les champs

Le langage de requête permet de réaliser une requête sur un champ précis d'un jeu de données

Les champs disponibles pour l'API Dataset sont définis plus haut.

Les champs pour l'API Records dépendent du schéma du dataset que l'on souhaite interroger. La liste de ces champs peut être obtenue avec l'API Dataset

Par exemple : q=titre_film:lord

Plusieurs types d'opérateurs peuvent être utilisés entre le nom du champ et la requête :

  • ":", "=" ou "==" : Retourne les résultats pour lesquels le champ correspond exactement à la valeur passée (fonctionne avec les champs de type texte ou numérique)
  • ">", "<", ">=", "<=" : Réalise une requête respectivement supérieure, inférieure, supérieure ou égale, ou inférieure ou égale à la valeur passée (fonctionne sur les types numériques ou date)
  • [date_debut TO date_fin] : Réalise une requête sur un intervalle de date de date_debut à date_fin

Le format de date peut être renseigné avec différent formats : simple (YYYY[[/mm]/dd]) ou ISO 8601 (YYYY-mm-DDTHH:MM:SS)

Exemples :

q=date_film >= 2002

q=date_film >= 2013/02/11

q=date_film: [1950 TO 2000]

q=film_box_office > 10000 AND date_film < 1965

Fonctions du langage de requête

Il est possible d'utiliser des fonctions dans le langage de requête.

Il faut pour cela préfixer le nom de la fonction avec #

Liste des fonctions disponibles :

  • now

    La fonction now permet de réaliser une recherche à partir de la date actuelle

    Cette fonction peut être appelée comme valeur de requête sur un champ

    Si elle est appelée sans argument, alors la recherche se portera sur le moment actuel

    q=anniversaires >= #now() retourne tous les enregistrements qui contiennent une date anniversaire postérieure à la date actuelle

    la fonction now peut aussi prendre des paramètres :

    years, months, weeks, days, hours, minutes, seconds, microseconds : Ces paramètres permettent d'ajouter ou de soustraire du temps par rapport à la date actuelle

    Par exemple : #now(years=-1, hours=-1) Retournera la date actuelle moins un an, moins une heure

    year, month, day, hour, minute, second, microsecond : Permet de spécifier une date absolue

    Par exemple : #now(year=2001) retournera la date courante mais en 2001 (même mois, jour, heure que la date actuelle)

    weekday : Permet de spécifier un jour de la semaine.

    Le paramètre prend soit un entier entre 0 et 6 (où 0 est lundi et 6 est dimanche). Soit les deux premières lettres du jour de la semaine en anglais suivi entre parenthèse de la Nième semaine à partir de laquelle commencer la requête (positive ou négative)

    #now(weeks=-2, weekday=1) Retourne le mardi, deux semaines précédant la date actuelle

    #now(weekday=MO(2)) Retourne le lundi, deux semaines après la date actuelle

Exemples