Documentation API
Cette page explique le fonctionnement de l'API gratuite de la plateforme Portail Open data.
Authentification
Pour avoir la possibilité d'effectuer un nombre important de requêtes journalières, nous vous conseillons de vous authentifier. En effet, les développeurs non authentifiés ont un quota de requêtes très limité.
Pour vous authentifier, vous devez obtenir une clé d'API et indiquer l'id de l'application pour laquelle vous effectuez votre requête.
Votre clé d'API (Authorization) ainsi que l'id de l'application à l'origine des opérations (Application-ID), doivent ensuite être mentionnés à chaque appel dans les entêtes HTTP.
Pour obtenir votre clé d'API, munissez-vous des identifiants de votre compte développeur sur la plateforme Portail Open data et exéctuez la commande suivante :
$ curl -X POST -d email=(your-e-mail) -d password=(your-password) "http://fr-api.data.gov.tn/api/1.0/login"Cela doit retourner une réponse similaire à ceci :
{"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyJ9.eyJleHAiOjE0NTMzNzA0OTYsInVzZXJuYW1lIjoiZmFubnlzY2hhbGxlckBtYWlsLmNvbSIsImlhdCI6IjE0NTMyODQwOTYifQ.AmAgtGsGSS0LCkPDBBZsIkgbY3aFm5obFyffrnH8JvJeX-JHJ4Q6IdO9f_3hgmVckUci70xr3nAkNLUTS0vzyJLnl1weFe2VD-xJWV-Gg8uZ_OmbmAoCXBlNRsKQTZ6lzSU4HMpc9otq5cf8N4wf_rcdTdM9k0NtgXFG7q9QHVmi5Gx6I6w0CUdNYjT33cLHSMlkoKRMaDQlfoK6t19tZNNwjK5-sxkl7Fy-ryabQN2CEIp5FUtN9DQtysERVHs26fLoW6PuNMXHzg1DuGXDiS1dv1A-s6OAAnk8HxQE2SLhjRUuzD54WyquqsLcYuQAixnSYTTZqgANhIoB01SA_MRpMXOPR1ton-C8IM6B4Ei-cJzMhZXYQrtAwye3MmEJTKgYmjF4PmJxlsFSB4E02c1TKewEYnbCu9gPdyP8kSKSg41RDKPzjOjbQFwkcFtRMQWKNF5EXskaeLaG7zNxt8tO_E7L2AhAwqz6aHbBlxyEomkIP353vCzZW904BRvKOev1WNz_gv8gKSNYmq2oWsaH9JTahPK4qoCJHEi6-OkTWgBpk2EZOTD4KqTlWTCzlmvvXiBEdv9njzJEqZJJTyoAjaJdUDNTiIOc59219SOzkKE99rptiwYEPG16AWHVeN1tzatvwv0Xo6-doUPxcrsG5yNWKqPmnZqKS1UhYUE"}
Le token renvoyé constitue votre clé d'API. Cette clé est valable 24h, il vous faudra donc en générer une autre en réexécutant cette commande si vous désirez faire des requêtes authentifiées au-delà de cette limite.
Ce token vous sert ensuite à vous authentifier pour chaque requête effectué. pour cela il vous faut passer votre clé d'API et le code de votre applications sous la forme suivante :
"Authorization" : "Bearer [+ votre token]"
"Application-ID" : "[id de votre application]"
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 vous permettant 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
Ne peut dépasser 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 pour 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 "http://fr-api.data.gov.tn/api/1.0/"Cela doit retourner une réponse similaire à ceci :
HTTP/1.1 200 OK
Server: nginx/1.6.2
Content-Type: application/json
Connection: keep-alive
Cache-Control: no-cache
Daily-Request-Limit: 200
Daily-Remaining-Request: 200
(...)
Date: Fri, 15 Jan 2016 13:01:36 GMT
On remarquera deux headers intéressants, "Daily-Request-Limit" et "Daily-Remaining-Request". Le premier indique la limite de requêtes journalière fixée dans les paramètres de la plateforme et le second le nombre de requêtes restantes. En effet, vous vous apercevrez si vous lancez une nouvelle fois 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 de l'ensemble des jeux de données contenant le mot "formation" en filtrant par le fournisseur appelé "Fournisseur" :
$ curl -X GET -v "http://fr-api.data.gov.tn/api/1.0/dataset?pretty=1&q=formation&facet.provider=Fournisseur"
HTTP/1.1 200 OK
Server: nginx/1.6.2
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache
Daily-Request-Limit: 200
Daily-Remaining-Request: 191
(...)
Date: Mon, 18 Jan 2016 10:28:30 GMT
{
"total": 2,
"size": 10,
"from": 0,
"results": [
{
"code": "catalogue-formations",
"siteCode": [
"demo"
],
"title": "Catalogue des formations",
"provider": "Fournisseur",
"providerCode": "fournisseur",
"themes": [],
"lastUpdatedAt": "2015-12-15T11:22:58+0100",
"createdAt": "2015-11-20T12:21:46+0100",
"lastPublishedAt": "2015-12-01T06:53:24+0100",
"recordsCount": 47,
"metas": [],
"fields": [
{
"name": "formation_dispensee",
"type": "string",
"title": "Formation dispensée"
},
{
"name": "enseignant",
"type": "string",
"title": "Enseignant"
},
{
"name": "nombre_de_participants",
"type": "numeric",
"title": "Nombre de participants"
}
],
"dataviz": [
{
"id": "567902d53a2d2",
"title": "Tableau",
"pluginCode": "table"
}
],
"exports": {
"json": "Json",
"csv": "CSV",
"xlsx": "Microsoft Excel",
"xml": "XML",
"geojson": "Geojson"
},
"downloads": 0,
"aPrioriNotation": 3,
"aPosterioriNotation": 3,
"notation": 3
},
{
...
}
],
"facets": {
"publishedAt": [],
"tags": [],
"licence": [],
"provider": [
{
"key": "Fournisseur",
"doc_count": 2
}
],
"themes": [],
"language": [],
"downloads": [
{
"key": 0,
"doc_count": 2
}
]
}
}
Exemple de récupération du jeu de données dont le code est "annuaire" :
$ curl -X GET -v "http://fr-api.data.gov.tn/api/1.0/dataset/annuaire?pretty=1"
HTTP/1.1 200 OK
Server: nginx/1.6.2
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-cache
Daily-Request-Limit: 200
Daily-Remaining-Request: 187
(...)
Date: Mon, 18 Jan 2016 12:27:37 GMT
{
"code": "annuaire",
"siteCode": [
"demo"
],
"isEnabled": true,
"title": "Annuaire",
"provider": "Fournisseur",
"providerCode": "fournisseur",
"themes": [],
"elementsToBePublished": false,
"lastUpdatedAt": "2015-11-25T14:42:33+0100",
"createdAt": "2015-11-25T14:40:26+0100",
"publishedAt": null,
"expiredAt": null,
"lastPublishedAt": "2015-11-25T14:42:33+0100",
"description": null,
"tags": null,
"licenceCode": null,
"licence": null,
"languageCode": null,
"language": null,
"geographicCoverage": null,
"coverageFromDate": null,
"coverageToDate": null,
"contactName": null,
"contactMail": null,
"recordsCount": 22,
"metas": [],
"fields": [
{
"name": "nom",
"type": "string",
"title": "Nom"
},
{
"name": "e-mail",
"type": "string",
"title": "E-mail"
},
{
"name": "telephone",
"type": "string",
"title": "Téléphone"
}
],
"dataviz": [],
"exports": {
"json": "Json",
"csv": "CSV",
"xlsx": "Microsoft Excel",
"xml": "XML",
"geojson": "Geojson"
},
"downloads": 1,
"aPrioriNotation": null,
"aPosterioriNotation": null
}
Consultez la documentation de référence ci-dessous pour avoir plus de précisions sur chaque ressource disponible.