Utiliser l’API

Une interface de programmation applicative, abrégée en API (Application Programming Interface), est une interface conçue pour permettre l’échange de données entre différents programmes. L’API OpenDataSoft offre une méthode d’accès unifiée à toutes les données téléchargées sur la plateforme, quels que soient leur source et leur format, tout en appliquant les règles de sécurité définies par le propriétaire des données.

L’ensemble de la plateforme OpenDataSoft repose exclusivement sur ces API pour accéder aux données. Elles sont en particulier utilisées par notre bibliothèque de widgets. Il s’agit uniquement d’une couche de présentation pour les données fournies par les API.

Ces API vous permettent de rechercher des jeux de données, d’effectuer des recherches parmi les données, de calculer des analyses, de réaliser des agrégations géographiques et bien plus encore.

Pour accéder à la documentation d’API pour les développeurs, cliquez sur les liens suivants :

Concepts clés

Toutes les API vous donnent accès aux mêmes données, mais de différentes manières. Il est particulièrement important de s’être familiarisé avec la nature de ces données avant de se plonger dans les spécifications complètes de chaque API.

Tous les composants de la plateforme sont organisés dans une arborescence. Cela signifie que vous pouvez envisager OpenDataSoft de la manière suivante :

  • 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.

Il existe bien entendu de nombreux autres types de données au sein la plateforme, mais ces dernières ne sont pertinentes que dans certains contextes très spécifiques.

La plateforme OpenDataSoft propose sa propre API (API ODS v1 et v2) et intègre certaines API standard telles qu’ODATA, que WFS ou que CSW.

API ODS

Cette API est celle utilisée en interne par la plateforme et les widgets OpenDataSoft. Si vous souhaitez développer votre propre application, cette API est la plus adaptée.

Différences entre les APIs Search v1 et v2

Note

Cette API est actuellement en développement et sera bientôt disponible officiellement.

Voici une liste des principales différences et modifications clés qui distinguent l’API v1 de l’API v2.

  • L’APIv2 signe l’arrivée d’une meilleure implémentation des principes REST. Chaque point d’entrée de l’API présente des liens permettant de naviguer facilement entre les différentes ressources liées (HATEOAS).

  • Cette API dispose d’un langage de requêtes plus complet comportant de nouvelles fonctions et expressions arithmétiques.

  • Les filtres spéciaux (filtres de facettes ou filtre géographique) sont désormais intégrés au langage de requêtes. Par exemple, geofilter.distance='42,1,100' est remplacé par q=distance(geo_field,geom'Point(42 1)',100)

  • L’API d’agrégation (anciennement API d’analyse) dispose d’un nouveau langage similaire à SQL et est disponible dans le catalogue et plus seulement dans les enregistrements des jeux de données.

  • Les exportateurs disposent de leur propre point d’entrée sous /api/catalog/exports et /api/catalog/datasets/<dataset_id>/exports

  • La recherche dans la navigation (anciennement la recherche de facettes) et la recherche standard sont complètement séparées.

À propos d’ODATA, de WFS et de CSW

Ces 3 acronymes désignent les autres normes mises en œuvre par la plateforme. Si vous ne connaissez pas ces normes, contentez-vous alors d’utiliser l’API ODS, car elle offre l’accès aux données le plus complet.

ODATA

ODATA est une norme pour les API REST qui offre un langage commun pouvant être utilisé avec les différentes API, afin d’effectuer des demandes. 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 met en œuvre cette norme pour les opérations simples (la recherche de jeux de données et d’enregistrements), les opérations plus complexes (par ex. l’analyse, les agrégations, les calculs géographiques...) sont uniquement disponibles via les API v1 et v2.

WFS et CSW

Il s’agit de normes portant sur les données géographiques, elles sont donc utiles si vous souhaitez créer une interface entre la plateforme et d’autres logiciels GIS.