Utiliser l'API

Une API (Application Programming Interface, interface de programmation applicative) est une interface permettant aux programmes de communiquer et d'échanger des données.

Remarque

Pour en apprendre davantage sur les API et leur utilisation, vous pouvez consulter l'article en anglais "You don’t need analogies to understand APIs (Pas besoin d'analogies pour comprendre les API)" écrit par l'un de nos développeurs Opendatasoft.

Opendatasoft met à votre disposition 6 API :

  • API ODS Explore V2 : principales API d'exploration d'Opendatasoft, utilisées pour explorer des catalogues et des jeux de données avec un langage de requête personnalisé, similaire à SQL, nommé ODSQL.

  • API Triple Pattern Fragments : API ODS pour interroger les jeux de données des portails Opendatasoft à l'aide de Triple Pattern Fragments

  • OData, WFS et CSW : 3 protocoles standard pris en charge et proposés par Opendatasoft

Toutes ces API permettent d'accéder aux données envoyées à la plateforme, quels que soient leur source ou leur format, dans la mesure où les règles de sécurité définies par le propriétaire des données autorisent cet accès.

Ces API peuvent par exemple être utilisées pour rechercher des jeux de données et des données, effectuer des analyses ou encore des agrégations géographiques. Autre exemple, toujours orienté développeurs, mais plus concret, de ce que vous pouvez faire avec les API : réutiliser des données pour créer des applications. Les données de certains clients d'Opendatasoft ont en effet été réutilisées via leurs API pour créer des applications. Nous pouvons notamment citer "Qui dit miam !" et "Y'A D Frites!", 2 applications qui affichent le menu des cantines scolaires dans les villes françaises de Toulouse, Rennes et Saint-Malo.

Important

Avant d'utiliser l'une des API disponibles, il est primordial que vous connaissiez la nature de ces données. Tous les éléments au sein de la plateforme sont conçus par rapport à une arborescence (davantage de types de données résident dans la plateforme, mais elles sont uniquement pertinentes dans des contextes très spécifiques). Opendatasoft peut donc être représenté comme suit :

  • La plateforme Opendatasoft est un réseau de portails Opendatasoft.

  • Un portail fournit un catalogue de tous ses jeux de données.

  • Chaque jeu de données est défini par un dictionnaire de métadonnées, un schéma de données (qui spécifie les noms et les types de champs) et une collection d'enregistrements.

  • Chaque enregistrement fournit des valeurs pour chacun des champs du jeu de données.

API ODS Explore

L'API ODS Explore est utilisée dans les widgets Opendatasoft. Si vous souhaitez développer une application, nous vous recommandons d'utiliser cette API, et plus particulièrement la version V2.

Actuellement, 2 versions de l'API ODS Explore sont disponibles : l'API V2 et l'API V1, qui est désormais obsolète. Vous trouverez ci-dessous les principales différences entre les 2 versions.

  • Principales modifications dans l'API V2 :

    • Un langage de requêtes enrichi (ODSQL) comportant de nouvelles fonctions et expressions arithmétiques est disponible.

    • Des filtres spéciaux (tels que des filtres de facette et un filtrage géographique) font désormais partie intégrante du langage ODSQL, dans le paramètre where.

    • Nous avons déclaré obsolète l'API d'analyse étant donné que l'ensemble des opérations sont maintenant disponibles sur tous les points d'entrée. Si vous souhaitez procéder à des analyses (avec des expressions ou des fonctions), vous pouvez le faire sur le point d'entrée du jeu de données ou du catalogue. Si vous voulez effectuer des analyses sur des groupes d'enregistrements, il vous suffit de les regrouper avec un paramètre REST group_by.

Triple Pattern Fragments

L'API Triple Pattern Fragments (TPF) permet d'interroger le jeu de données au format Resource Description Framework (RDF).

OData, WFS et CSW

OData, WFS et CSW désignent les autres normes mises en œuvre par la plateforme. Nous recommandons aux utilisateurs qui ne connaissent pas ces 3 API d'utiliser l'API ODS Explore, car elle offre l'accès aux données le plus complet.

  • OData est une norme pour les API REST qui offre un langage commun pouvant être utilisé avec les différentes API, afin d'exécuter des requêtes. L'approche générique de cette norme présente l'inconvénient d'être plus complexe que les API REST personnalisées classiques. Opendatasoft a mis en œuvre cette norme pour les opérations simples (la recherche de jeux de données et d'enregistrements) ; pour les opérations plus complexes (l'analyse, les agrégations, les calculs géographiques, etc.), utilisez notre API Explore V2.

  • WFS et CSW sont des normes portant sur les données géographiques. Elles sont particulièrement utiles pour créer une interface entre la plateforme et d'autres logiciels GIS par exemple.