Cette page explique le fonctionnement de l'API gratuite de la plateforme Open data Onisep. L'API permet de requêter tous les jeux linéarisés au catalogue.

Pour plus d'information sur les différences entre jeux linéarisés et jeux en ressources globales, voir aussi la FAQ.

Attention, les jeux de données ouvertes Onisep sont proposés sous licence ODBL, et leur exploitation est encadrée par les CGU du site.

Authentification

De façon à pouvoir exécuter des requêtes journalières, vous devez être authentifié et obtenir une clé d'API. Cette clé doit être fournie à chaque appel dans l'entête http. « Les développeurs non authentifiés ont un quota de requêtes très limité ».

Autorisation
Pour obtenir votre clé d'API (authorization), munissez-vous des identifiants de votre compte développeur sur la plateforme Site Open data Onisep et exécutez la commande suivante :

$ curl -X POST -d email=(your-e-mail) -d password=(your-password) "https://api.opendata.onisep.fr/api/1.0/login"

Cela doit retourner une réponse similaire à ceci :

{"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyJ9.eyJleHAiOjE0NzYzNjMxNzksInVzZXJuYW1lIjoiZGR1cmlzQG9uaXNlcC5mciIsImlhdCI6IjE0NzYyNzY3NzkifQ.G-BOyZIiGf4y_wwvDQBcZ9NDIer8o8rGYU-YUS9loeuM0YbX7ne4qZWJZJ8Z2YgzzjHVOQTuYXrgvFM4dVxQPkxcHVhF1XFtQC6u14QPAYl3CqwG607VZmx1B0KUQgb3fmcVEr4f-XglLrsGcbx1daEnpR5MSgeZfVwp1Bg-BNEmdpJTBYMGjZi_JDXDb1O5dhtiD_eptl4TBC5A8rs2jU1GDFobV-BSTDb7AAZqi8t6d9DsgHUQcuz3ZL8mlGGqCBk_NWlabo6-zbCBet_r5QfXG2gqQxrtK9Mnc3Ks8epvZuSKpUmJ78TEnblqAZ4CfwE5Kqp0geNjI2I3RHiKNDb0ZOZcw5aZHNbOMdI5Gm5-f7IXba3ae3u8ZApBoFQdBlCxzp_MZ7JzrN5GBzHktTVjaZRfIJdgWAKMI4Tq4qqnlNkwRDjdsSPRgJWfNbdYeVGdKRBv6VLZTtIkvkGpEXivqNC23cJPlkLpfCYIrLE94utF_RoKjq3Gx7sWUXRBfDsbbjg5zsPaoHJaRZjpsu2Ya33-DzY4eI9_ZSy53g1w8-AzEaokxJF9Bvt3hU11idKqE0kSSTD88ByroEQPWBzbDBR08vwcSqYfXq8NJjZ3266Zu8pd_X27cDnlYgppt0qqd4bm_UhpYZ809JtteA0hiaLZSa2EbzP5tuSCUy4"}

Le token renvoyé constitue votre clé d'API. La validité de cette clé est de 24h.
A l’expiration de la clé, il vous faudra donc générer une nouvelle clé en ré exécutant cette commande si vous désirez faire des requêtes authentifiées.

Optimisation des résultats retournés
Les méthodes permettant la récupération d'un ensemble de ressources sont dotées de paramètres qui permettent d'optimiser les résultats :

Exemples
Voici quelques exemples de requêtes afin de mieux comprendre le fonctionnement de notre API. Pour ces exemples, nous utilisons la bibliothèque curl en ligne de commande, mais vous pouvez utiliser d'autres outils similaires de votre choix.

Requête HEAD

Pour commencer, observons les headers retournés par une requête adressée à la page de garde de notre API à l'aide de la commande suivante :

$ curl -I "https://api.opendata.onisep.fr/api/1.0/"

Cela doit retourner une réponse similaire à ceci :

HTTP/1.1 200 OK
Date: Wed, 12 Oct 2016 15:31:27 GMT
Server: Apache/2.4.10 (Debian)
Cache-Control: no-cache
Daily-Request-Limit: 200
Daily-Remaining-Request: 196
Content-Type: application/json

On remarquera deux headers intéressants, "Daily-Request-Limit" et "Daily-Remaining-Request". Daily-Request-Limit indique la limite de requêtes journalière fixée dans les paramètres de la plateforme et Daily-Remaining-Request le nombre de requêtes restantes. En effet, vous vous apercevrez en relançant la commande, que le nombre de requêtes restantes aura diminué.

Utilisation authentifiée

Les utilisateurs connectés disposent de 5000 requêtes quotidiennes contre 200 pour les utilisateurs anonymes.

Afin d'effectuer une requête API en mode connecté, il faut ajouter les paramètres suivants :

curl -H "Authorization: Bearer token" -H "Application-ID: ID application" -I "https://api.opendata.onisep.fr/api/1.0/"

Le token est généré par la commande curl présentée plus haut.

Pour obtenir un ID application, il faut aller à l'onglet VOS APPLICATIONS de son compte. A la création d'une application, un identifiant est généré.

Appliquer des filtres à facettes

Il est possible d'utiliser des facettes afin de préciser sa recherche.

Cela permet de restreindre sa recherche selon différents critères (géographiques, statuts, spécificités...).

Afin, par exemple, d'appliquer une facette région au jeu de données des organismes d'information (CIO et SCUIO), en filtrant sur l'Ile-de-France, il faut utiliser la commande :

curl -X GET --header "Accept: application/json" "https://api.opendata.onisep.fr/api/1.0/dataset/57daa24b35d4d/search?facet.region=Ile-de-France"

Parcourir et récupérer des données

Vous pouvez récupérer une liste de ressources (avec ou sans filtres) ou une ressource unique.

Exemple de récupération du jeu de données des "Formations initiales en France" dont le code est 57da8f4c4d1c9 (le code de chaque jeu de données est indiqué dans son url) :

curl -X GET --header "Accept: application/json" "https://api.opendata.onisep.fr/api/1.0/dataset/57da8f4c4d1c9"

{"code":"57da8f4c4d1c9","title":"Formations initiales en France","provider":"Onisep","providerCode":"onisep","themes":[],"lastUpdatedAt":"2016-09-27T18:21:49+0200","createdAt":"2016-09-15T14:08:44+0200","publishedAt":null,"expiredAt":null,"lastPublishedAt":"2016-09-27T18:21:49+0200","description":"\u003Cp\u003ELe jeu de donn\u0026eacute;es contient : le code CNIS\/NSF de la nomenclature des sp\u0026eacute;cialit\u0026eacute;s de formations, le type de formation, le libell\u0026eacute; principal et le libell\u0026eacute; compl\u0026eacute;mentaire, la dur\u0026eacute;e, le minist\u0026egrave;re responsable, le niveau de formation (colonne niveau RNCP - nomenclature de 1969) et le lien d\u0027acc\u0026egrave;s sur le site Onisep (\u003Ca href=\u0022http:\/\/www.onisep.fr\/\u0022 rel=\u0022nofollow\u0022\u003Ehttp:\/\/www.onisep.fr\u003C\/a\u003E)\u003C\/p\u003E","tags":[],"licenceCode":"open-licence","licence":"Licence ouverte","languageCode":"fr","language":"Fran\u00e7ais","geographicCoverage":["France"],"coverageFromDate":null,"coverageToDate":null,"contactName":"Daniel Duris","contactMail":"dduris@onisep.fr","recordsCount":9892,"updateFrequency":"annuelle","extra_metadata":[],"resources":[],"fields":[{"name":"code_cnis","type":"numeric","title":"code CNIS","filter":false},{"name":"sigle_type_formation","type":"string","title":"sigle type formation","filter":false},{"name":"libelle_type_formation","type":"string","title":"libell\u00e9 type formation","filter":false},{"name":"libelle_formation_principal","type":"string","title":"libell\u00e9 formation principal","filter":false},{"name":"libelle_formation_complementaire","type":"string","title":"libell\u00e9 formation compl\u00e9mentaire","filter":false},{"name":"sigle_formation","type":"string","title":"sigle formation","filter":false},{"name":"duree","type":"string","title":"dur\u00e9e","filter":false},{"name":"niveau_rncp","type":"numeric","title":"niveau RNCP","filter":false},{"name":"libelle_niveau_rncp","type":"string","title":"libell\u00e9 niveau RNCP","filter":true},{"name":"tutelle","type":"string","title":"tutelle","filter":true},{"name":"lien_site_onisepfr","type":"string","title":"lien site onisep.fr","filter":false}],"dataviz":[{"id":"57da8f7a706a8","title":"Tableau","pluginCode":"table"}],"exports":{"json":"Json","csv":"CSV","xlsx":"Microsoft Excel","xml":"XML"},"downloads":0,"harvested":null}

Consultez la documentation de référence ci-dessous pour avoir plus de précisions sur chaque ressource disponible.