Site Open data Onisep
API

Cette page explique le fonctionnement de l'API gratuite de la plateforme Open data Onisep.

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 :

Pretty boolean Permet d'afficher la réponse JSON en mode lisible
Q string Chaîne de recherche

Size string,

par défaut : 10, maximum : 1000

Nombre de résultats maximum à retourner

inférieur ou égal à 1000

From string,

par défaut : 0

Index du premier résultat à retourner
Sort string

Champ à utiliser pour le tri des résultats

sort=(field) pour un tri par ordre croissant,

sort=-(field) pour un tri par ordre décroissant

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 -X HEAD "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é.

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 :

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.