Introduction à l'API Explore
Si vous êtes déjà familier avec les API et l'API Explore, vous pouvez accéder directement à la documentation Explore API v2. Sinon, lisez la suite pour plus de détails.
Une API, ou interface de programmation d'application, est un outil conçu pour permettre à différents systèmes logiciels de communiquer entre eux. Si vous souhaitez utiliser des données stockées quelque part en ligne, l'intérêt d'une API est de vous permettre d'interagir avec ces données d'une manière compréhensible pour la source. Et si vous souhaitez partager vos données avec d'autres, une API vous permet de définir le type d'accès dont ils disposent.
Opendatasoft fournit plusieurs API pour interagir avec la plateforme, mais la principale API utilisée pour accéder aux données publiques d'un espace de travail donné est notre API Explore.
Ce que notre API vous permet de faire
L'API Explore d'Opendatasoft vous donne accès aux données publiques sur la plateforme Opendatasoft. Ainsi, l'API Explore vous permet d'effectuer trois types d'actions :
Explore : Demandez les enregistrements et les champs que vous aimeriez voir. Les données vous sont fournies dans un objet JSON.
Exporter : Exporter l'intégralité du jeu de données selon les conditions spécifiées. Pour spécifier les conditions, vous utilisez un langage de requête que nous appelons "ODSQL". ODSQL est notre propre langage de requête, très similaire au langage SQL.
Analyse : vous pouvez combiner des données au sein d'un jeu de données et/ou effectuer une analyse simple sur un jeu de données.
Par exemple, vous pouvez interroger un jeu de données qui contient des écoles, le nombre d'élèves dans ces écoles et la région où se trouve chaque école, et combiner ces informations en demandant le nombre total d'élèves par région.
Interagir avec l'API
Alors, comment allez-vous réellement utiliser l'API ? La réponse est à la fois simple et compliquée.
Comme nous l'avons vu plus haut, utiliser l'API consiste à lui demander des choses, et à recevoir une réponse. En langage API, vous effectuez un "appel" ou une "requête" et recevez, dans le cas d'ODS, un objet JSON en retour. Ainsi, lorsque vous utilisez l'API, votre appel API est envoyé au serveur Opendatasoft et vous recevez une réponse avec un objet JSON.
Il est facile de voir cela en action dans votre navigateur. L'API peut être invitée à vous fournir une liste de tous les ensembles de données publics d'un espace de travail. https://data.opendatasoft.com/pages/home/ est l'URL du Data Hub d'Opendatasoft, une source de plus de 30 000 ensembles de données publics publiés par des organisations des secteurs public et privé. Son domaine est donc "data.opendatasoft.com". Ouvrez une fenêtre de navigateur et collez-y cette URL : http://data.opendatasoft.com/api/v2/catalog/datasets . Ce que vous voyez est un objet JSON contenant une sorte de liste des jeux de données, avec des liens vers d'autres objets JSON. Et rappelez-vous que vous pouvez remplacer "data.opendatasoft.com" par n'importe quel domaine Opendatasoft, et vous verrez les données de ce domaine. C'est l'API en action ! Bien sûr, en soi, ce n'est pas très intéressant. Mais lorsque d'autres outils sont utilisés, l'API peut être un moyen puissant d'interagir avec les données. Lire la suite pour plus de détails.
En pratique, vous voudrez utiliser certains outils pour rendre l'interaction avec l'API plus pratique et utile. Par exemple, les appels d'API peuvent être effectués à l'aide de plates-formes telles que PostMan conçues pour interagir avec les API. Si vous êtes développeur, vous pouvez utiliser la bibliothèque de requêtes Curl ou Python.
Explorer les données
Comme nous l'avons vu ci-dessus, l'exploration des données est l'un des trois types d'actions que vous pouvez effectuer avec l'API Explore. En explorant les données, nous voulons dire que vous pouvez demander des enregistrements à partir d'un ensemble de données public afin de les traiter et de les utiliser de votre côté.
Il existe des méthodes que vous pouvez utiliser (et des limites à connaître) lorsque vous spécifiez les données que vous souhaitez recevoir :
Select : vous pouvez sélectionner une plage spécifique de colonnes
Where : vous pouvez filtrer les données en fonction d'une condition
Order by : vous pouvez l'utiliser pour trier selon une colonne désignée
Limit/offset : vous pouvez limiter les enregistrements renvoyés ou accéder directement à un enregistrement spécifique
Group by : vous pouvez regrouper les données en fonction de certaines valeurs de champ ou de fonctions appliquées à ces champs.
Notez que vous ne pouvez explorer qu'une partie des données à la fois, car les appels d'API sont limités à 100 éléments à la fois. L'utilisation de limit/offset vous permet de gérer les parties des données que vous examinez.
Exportation des données
Les appels d'API sont limités à 100 enregistrements par appel. Mais si vous avez besoin de gérer toutes les données à la fois, vous pouvez exporter l'intégralité des données.
Les mêmes méthodes répertoriées sous "Explorer les données" peuvent être utilisées pour personnaliser vos demandes.
Analyse des données
Après avoir exploré ou exporté les données, vous souhaiterez peut-être effectuer une analyse de base sur celles-ci. C'est ce qu'on appelle l'agrégation, et vous pouvez utiliser différentes fonctions pour combiner ou agréger les données de manière productive :
avg (moyenne)
count
count distinct
envelope
bbox
max (maximum)
median
min (minimum)
percentile
sum
Ces fonctions s'appliquent à des "groupes" qui peuvent être définis par la méthode "group by", décrite ci-dessus.
Cela peut être utile si, par exemple, vous souhaitez obtenir le total des dépenses chaque mois, lorsque votre jeu de données est une liste de dépenses et leurs dates. Dans ce cas, vous pouvez regrouper les dépenses par mois et effectuer une somme de la colonne des dépenses. De cette façon, même avec une petite quantité d'analyses, vous pouvez commencer à comprendre et à utiliser réellement les données brutes. Et, selon la façon dont vous utilisez l'API, vous pouvez le faire de manière standardisée, automatisée ou évolutive.
Pourquoi passer à la version 2 ?
Différences et avantages de la v2 :
V1 | V2 | |
Utiliser le paradigme | 3 points d'accès principaux pour le catalogue et le jeu de données : "/search" pour récupérer les données "/analyse" pour utiliser la fonction d'agrégation "/download" pour exporter les données | Deux points de terminaison principaux pour le catalogue et jeu de données : - "/records" pour récupérer ou effectuer des analyses de données sur un échantillon du jeu de données (10 000 enregistrements max) - "/exports" pour exporter le jeu de données complet dans les différents formats disponibles Les deux points de terminaison utilisent notre langage ODSQL, qui fournit entre autres des fonctions d'agrégation. |
Exports | • Tous les formats d'export ne sont pas disponibles • Group_by n'est pas pris en charge | • Tous les formats d'export sont disponibles • Group_by pris en charge |
Utilisations internes et externes | Utilisé uniquement par les anciens outils ODS | Utilisé par le Studio et d'autres services externes (WFS, CSW, AUTOMATION, ...) |
Encodage d'URL | Besoin d'échapper certains caractères spéciaux, par exemple « # » | Pas besoin d'échapper les caractères spéciaux |
Cartographie des paramètres :
V1 | V2 |
q, sort | Utilisez plutôt select, where, order_by, et group_by de notre langage ODSQL |
dataset | dataset est dans le endpoint, ce n'est plus un paramètre |
rows & start | Deviennent limit et offset (mais gardent le même sens) |
refine.<facet_name>=<face_value> exclude.<facet_name>=<face_value> | refine=<facet_name>:<face_value> exclude=<facet_name>:<face_value> |
lang, timezone | Aucun changement |
Traduction de requête :
Exemple avec ce portail : https://documentation-resources.opendatasoft.com
V1 /api/records/1.0 | V2 /api/explore/v2.1 |
|
|
|
|
|
|
Quelle destination maintenant?
J'espère que vous comprenez mieux maintenant pourquoi une API peut être utile et que vous avez une idée de ce qu'Opendatasoft vous permet de faire avec l'API Explore.
Il ne fait aucun doute que l'utilisation d'une API n'est pas pour tout le monde. Mais avec un peu de travail, l'API peut vous permettre de mieux comprendre et d'utiliser efficacement vos propres données ou d'autres données publiques.
Pour répondre à vos questions et vous aider sur votre chemin, nous vous invitons à plonger dans notre documentation pour l'API Explore !