Bienvenue dans la documentation de DATASUD

Cette documentation est organisée en plusieurs parties, chacune correspondant à un usage particulier de la plateforme. Le catalogue des données et des ressources disponibles sont amenés à évoluer avec la version 3 de DataSud. La version 2 de DATASUD est disponible depuis le 15 décembre 2018.

Table des matières

Généralités

Régles éditoriales

Règles de nommage des ressources

Selon les recommandations en matière de nommage des fichiers électroniques et de plan de classement, nous vous proposons de respecter les règles suivantes relatives aux intitulés des ressources (fichiers) associées à vos jeux de données :

  • Le nom d’un fichier doit être succinct : éviter de dépasser 30 caractères (sans compter l’extension).
  • Le nom d’un fichier doit être précis : il contiendra idéalement : le nom du producteur, le sujet, le type de document, la date de création, éventuellement la version.
  • Date: pour le 20 décembre 2018 => 20181220 (norme ISO 8601).
  • Ne pas utiliser des articles ou mots vides : le, la, les, de, etc…
  • Préférer le caractère _(underscore, tiret du 8) à un espace
  • Eviter les lettres accentuées
  • Le nom d’un fichier ne doit pas contenir : espace, ponctuation (sauf le point avant l’extension), caractères accentués ou spéciaux (ùé+’@à°[] :</* »& !$, etc.).
  • La gestion des versions permet de suivre l’évolution et les étapes de l’élaboration d’un fichier. Il faut les distinguer soigneusement en les numérotant pour obtenir une suite logique exemple V01, V02, etc.
Amélioration des champs descriptifs avec le langage Markdown

Pour les champs descriptifs des jeux de données, des ressources et des organisations vous pouvez utiliser le langage Markdown dans le but est d’offrir une syntaxe facile à lire et à écrire.

Voici quelques exemples de syntaxe Markdown.

Cette liste n’est pas exhaustive.

=== Formatage ===

Mettre du texte en italique

*quelques mots*

quelques mots

Mettre du texte en gras

**plus important**

plus important

Pour mettre du code dans le texte:

``Mon code``

Mon code

=== Listes ===

Sauter une ligne avant le début de la liste.

Pour créer une liste non ordonnée

* Pommes
* Poires
  • Pommes
  • Poires

=== Image ====

Vous pouvez afficher une image dans vos descriptifs. Attention, la taille n’est pas paramétrable et l’image doit déjà être disponible en ligne quelque part

.. image:: CaptureDataSudConnect.PNG
_images/CaptureDataSudConnect.PNG

=== Liens ===

Pour créer des liens

[texte du lien](url_du_lien "texte pour le titre, facultatif")
https://trouver.datasud.fr (automatique si mon url commence par http ou https).

[Trouver des données sur Datasud.fr](https://trouver.datasud.fr)

=== Aller plus loin ===

https://fr.wikipedia.org/wiki/Markdown

https://guides.github.com/features/mastering-markdown/

https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf

Les outils pour nettoyer vos données

[La méthode infolabs pour produire un CSV de qualité](http://infolabs.io/prod-csv)

[l’Outil de validation des données ouvertes Validata](https://validata.fr/)

[Nettoyer les CSV avec CSVLint (en Anglais)](http://csvlint.io)

https://goodtables.io/

http://openrefine.org/

Espace consultation

DataSud est un catalogue ouvert à tous : https://trouver.datasud.fr

Les consultations des données ouvertes, géographiques et intelligentes sont libres sur DataSud. Vous pouvez parcourir le catalogue, rechercher des jeux de données et télécharger des ressources dans différents formats de fichier.

Ceci ne concerne pas les données diffusées sur accès retreints, pour lesquelles les producteurs ont volontairement limité leur téléchargement à certains utilisateurs. Toutefois ces jeux de données apparaissent au catalogue général pour porter à connaissance des publics l’existence de ces données. Pour les consulter il faut en faire la demande directement au producteur.

Rechercher des données sur DataSud

Pour de meilleurs résultats, DataSud permet de « filtrer » les données, d’effectuer des recherches par thématique, selon la fréquence de mise à jour, par format ou uniquement les jeux de données associés à une organisation.

_images/Trouver_donnees.png

L’ensemble de ces « filtres » peuvent être cumulés pour affiner les résultats avec un moteur de recherche “textuel”

Il n’y a pas d’inscription préalable pour accéder aux jeux de données et aux ressources diffusés en « Open Data ».

Dans le respect des conditions générales d’utilisation de DataSud, chaque jeux de données est publié avec une licence ( licences ouvertes, licence odbl, etc…), choisie par le producteur de la donnée, dans le but de définir les conditions de leur réutilisation.

« Voir le passage sur le Cadre légal et réglementaire »

Si vous recherchez un jeu de donnée qui ne figure pas au catalogue de DataSud, vous pouvez utiliser le service de « demande de données » Toute demande sera étudiée et une réponse vous sera apportée. Nous relayerons le cas échéant votre demande à la collectivité ou à l’organisme concerné.

Vous pouvez déposer une demande d’accès à un document administratif ou à un jeu de données relatif au territoire régional à l’adresse suivante : https://www.datasud.fr/demande-de-donnees

« Voir le passage sur la demande de documents administratif »

S’identifier sur Datasud : l’espace utilisateur

S’il n’est pas nécessaire de s’inscrire sur la plateforme pour consulter le catalogue et télécharger des données ouvertes, s’enregistrer sur DataSud https://publier.datasud.fr permet de disposer de fonctionnalités complémentaires.

Note

Toute personne, morale ou physique, publique ou privée, peut s’inscrire sur DataSud et ainsi contribuer à l’ouverture et la mise en commun des données publiques ou privées, en publiant des jeux de données, des textes, des ressources et des commentaires.

S’inscrire sur DataSud

  • L’utilisateur enregistre son identité, distincte de la personne morale qu’il représente.
  • En s’inscrivant, l’utilisateur crée un profil sur la Plateforme.
  • En s’inscrivant, l’utilisateur accepte les « conditions d’utilisation »
_images/CaptureDataSudConnect.PNG

Le formulaire d’inscription est disponible en cliquant sur S’inscrire/Publier depuis le site www.datasud.fr.

_images/CaptureDataSudSubscribe.PNG

Note

**Le nom d’utilisateur doit contenir uniquement des caractères alphanumériques en minuscules (ascii) et ces symboles : -_

L’utilisateur doit ensuite valider son inscription en cliquant sur le lien reçu par courriel.**

Participer et échanger sur Datasud

De nombreuses fonctionnalités participatives sont proposées :

  • Rentrer en contact
  • S’abonner à une thématique, une organisation, un jeu de données
    • Suivre/s’abonner à un jeu de données, une thématique ou une organisation,
  • Qualifier les données
    • Noter la qualité d’un jeu de donnée
    _images/VuesDataSud.PNG
    • Commenter une organisation ou un jeu de données
    _images/Commentaires.PNG
  • Accéder aux données particulières
    • Demander l’accès aux administrateurs à des données réservées sur accès restreint,
    • Accéder aux données et services autorisés pour une organisation.
    • Faire une demande de donnée: https://www.datasud.fr/demande-de-donnees/
  • Réutiliser un jeu de donnée

  • Participer au contrôle de la qualité de DataSud en signalant les contenus n’ayant pas vocation à y figurer (illicites ou contraires aux CGU).

  • Devenir contributeur ou référent pour une organisation
    • Créer une nouvelle Organisation ou demander à être rattaché à une Organisation existante (voir rubrique dédiée),
    • Demander à devenir contributeur d’une organisation et éventuellement référent d’une organisation pour maitriser l’ensemble des publications de ladite organisation (voir rubrique dédiée).

  • Accéder à certaines fonctionnaltés de l’API nécessitant une clé d’authentification.

Espace contributeurs

Ce guide est destiné aux producteurs de données, déjà inscrit en tant qu’Utilisateurs https://publier.datasud.fr/ et souhaitant contribuer à l’enrichissement des publications sur la plateforme. « voir la documentation sur les Utilisateurs »

Note

Toute personne, morale ou physique, publique ou privée, producteur de données publiques ou privées peut publier des données sur la DataSud, sous reserve d’accepter les « conditions d’utilisation » et de respecter la réglementation sur les données à caractères personnelles.

Plus précisément, vous pouvez publier des données sur datasud.fr :

  • Si vous produisez ou collectez des données dans le cadre d’une mission de service public, à condition que ces données ne contiennent pas d’informations personnelles et qu’elles ne révèlent pas de secrets.
  • Si vous enrichissez ou complétez des données pour le compte d’une association, d’un projet de recherche, ou sur votre temps libre.
  • Si vous produisez des données d’intérêt public de votre côté, même hors du cadre d’une mission de service public.
    • publication des données privées ?

Qu’est-ce qu’un Contributeur ?

Un contributeur dispose des fonctionnalités suivantes :

  • il peut publier un jeu de données et y ajouter des ressources, sous la forme d’un fichier téléchargeable, d’un lien URL ou d’une API,
  • il peut définir le niveau d’accès aux ressources et jeux de données qu’il a crée pour l’organisation :
    • accessible à tous les utilisateurs - solution par défaut,
    • restriction d’accès à un ou plusieurs utilisateurs inscrits,
    • restriction à une ou plusieurs organisations choisies,
    • restriction aux seuls membres de l’organisation propriétaire du jeu de données.
  • il peut paramétrer les services DataSud associés aux jeux de données qu’il publie

Devenir Contributeur pour une Organisation

Un Contributeur est un Utilisateur inscrit à DATASUD. Un Contributeur peut demander à contribuer pour une ou plusieurs Organisations. Il peut le faire :

  • soit au moment de l’inscription en tant qu’utilisateur de DATASUD en cochant la case « Devenir un contributeur »,
  • soit dans son Espace utilisateur, dans la rubrique Organisation en cochant la case « Je souhaite devenir contributeur » après avoir sélectionner l’organisation concernée dans la liste déroulante.

À la première connexion,…

_images/CaptureDataSudFirstConnect.PNG

Les demandes de statut de Contributeur sont soumises à la validation des Administrateurs de la plateforme ou des Référents des organisations. Un mail de confirmation est envoyée lorsque la demande est acceptée.

Note

Par défaut, un Utilisateur qui s’inscrit avec un email personnel (gmail, ymail, hotmail,…) et dont le nom de domaine ne peut correspondre à l’organisation pour laquelle il demande de contribuer, ne peut se rattacher, contribuer ou devenir référent d’une Organisation

Les Administrateurs de la Plateforme se réservent la possibilité de révoquer une inscription, une organisation, un statut de Contributeur ou de Référent, sans avis préalable.

– Qui peut publier

Tout le monde peut publier des données sur data.gouv.fr, du moment qu’il s’agit de données d’intérêt public.

Plus précisément, vous pouvez publier des données sur data.gouv.fr :

Si vous produisez ou collectez des données dans le cadre d’une mission de service public, à condition que ces données ne contiennent pas d’informations personnelles et qu’elles ne révèlent pas de secrets. Si vous enrichissez ou complétez des données publiques pour le compte d’une association, d’un projet de recherche, ou sur votre temps libre. Si vous produisez des données d’intérêt public de votre côté, même hors du cadre d’une mission de service public.

Publier un jeu de données

Pour publier un jeu de données, le Contributeur se connecte avec son identifiant et mot de passe sur https://publier.datasud.fr

Renseigner les métadonnées

Les métadonnées obligatoires sont les suivantes :

  • Titre
  • Organisation à laquelle est rattaché ce jeu de données
  • Descriptif : C’est un champ incontournable pour garantir une bonne réutilisation, car une donnée bien décrite est une donnée bien réutilisée !
  • Dates de création, de dernière modification et de publication : La valeur par défaut indique la date du jour. La date de modification se met à jour automatiquement lorsque des modifications sont effectuées sur les ressources.
  • Licence

Les métadonnées facultatives sont les suivantes :

  • Thématiques : Un jeu de donnée peut-être associé à une ou plusieurs thématiques
  • Mots-clés : Plus le nombre de mots clés est important et mieux le jeu de donnée est indexé dans le catalogue
  • Fréquence de mise à jour
  • Type de données
  • Meta-données INSPIRE
  • Fréquence de mise à jour
  • Couverture régionale
  • Granularité

Note

De nombreux mots-clés sont déjà répertoriés et apparaissent dans une liste déroulante dès la saisie des premières lettres du mot. Mieux vaut choisir un mot clés existant plutot que d’en créer un nouveau afin de relier les jeux de données similaires.

Publier une ressource

Lors de la publication, le type de ressource doit être précisé. Il peut s’agir de données brutes du jeu de données, proposées dans un format permettant la modification, ou de documentations associées au jeu de donnée, qui permettent aux visiteurs de DataSud d’obtenir plus d’informations (plaquettes de communications, affiches, photographie, site internet….).

Il existe quatre manières différentes d’ajouter un jeu de données :

1. Téléverser manuellement un fichier depuis votre poste local:

A l’aide du bouton Parcourir, vous pouvez déposer le fichier qui s’ajoute dans l’entrepôt de données DataSud;

_images/Upload_ressources.PNG

Le Titre de votre fichier est automatiquement recopié, mais il est possible de modifier manuellement le nommage de ce jeu de donnée.

_images/Upload_ressources1.PNG

2. Télécharger depuis une URL en indiquant une URL de téléchargement du jeu de donnée:

Dans ce cas, Datasud va télécharger la ressource pour l’ajouter dans l’entrepôt de données;

_images/Upload_ressources_URL.PNG

Ce mode de publication permet de synchroniser la ressource distante, selon une périodicité régulière à indiquer :

  • Jamais
  • Quotidienne (tous les jours à minuit)
  • Hebdomadaire (tous les lundis)
  • Bimensuelle (1er et 15 de chaque mois)
  • Trimestrielle ( 1er des mois de Janvier, Avril, Juillet et Octobre)
  • Annuelle (1er Janvier)

Par exemple, un fichier transport.zip peut-être synchronisé sur DataSud directement grace à son URL de téléchargement.

Note

Quelques précautions à prendre pour que la synchronisation s’active correctement :

  • le nom de votre fichier doit avoir exactement le même nommage de fichier pour toute la synchronisation : si un script modifie le nom du fichier (pour rajouter une date ou autre par exemple), la synchronisation ne fonctionnera pas.
  • votre fichier doit être accessible via une URL fixe : évitez les liens temporaires.:

En cas d’erreur, les Administrateurs de DATASUD se chargeront de vous indiquer que la synchronisation ne fonctionne pas ou plus.

3. Référencer une URL:

Dans ce cas, la ressource n’est pas téléchargée dans DataSud et vous indiquez précisement l’adresse URL de téléchargement de la donnée. qui reste hebergée chez son producteur. Cette donnée apparait au catalogue de DataSud mais elle n’est pas hébergée dans son entrepot.

_images/Upload_ressources_ref_URL.PNG

4. Dépot FTP:

il faut pour activer au préalable le compte FTP en cliquant sur le lien « cliquez ici »

_images/Upload_ressources_FTP.PNG
Publier une donnée géographique

Datasud détecte automatiquement le format des ressources publiées.

Si il s’agit de données géographiques (GeoJSON, Shapfiles, MapInfo, …) des services géographiques associés à ces données sont automatiquement déclenchés tels que l’emission de flux WMS et WFS, l’accessibilité à ces ressources via l’extracteur de données du CRIGE ou encore la publication de fait de la ressource au format GeoJSON.

Les données au format Shapefiles ou MapInfo devront être poussées dans un zip, déclaré sur Datasud comme “Shapefile (Fichier Zip)” ou “Mapinfo (Fichier ZIP)”.

Renseigner une métadonnée INSPIRE

Les jeux de données rentrant dans le champ de la Directive INSPIRE doivent faire l’objet d’une description standardisée. Cette description suit dans les grandes lignes le standard ISO19115 : https://www.iso.org/standard/53798.html.

Afin d’être conforme avec la règlementation INSPIRE, tous les contributeurs ont la possibilité de renseigner un plus grand nombre d’informations sur leur jeu de données grâce à un formulaire spécifique.

Ce formulaire est accessible dans votre Espace Utilisateur https://publier.datasud.fr/ depuis l’onglet « Mes jeux de données » en sélectionnant un jeu de données à éditer et en sélectionnant « Editer la métadonnée INSPIRE » dans le menu qui s’affiche.

Les services ajoutés

Datastore et données intelligentes

Datasud propose un datastore, c’est à dire un entrepôt de données qui offre des services dits « intelligents » sur les données tabulaires aux formats CSV, XLS, GeoJSON, SHP.

La publication des données sur Datasud, dans un format ouvert et interprétable par une machine, permet leur indexation dans le datastore afin notamment de proposer des apercus, de les filtrer par champs et de les parcourir sans utiliser de tableur dédiés.

Le format CSV est le format pivot à privilégier pour transformer vos données tabulaires en données semi-structurées dites « intelligentes » afin que le datastore génère des datavisualisations simples sous forme de grille, de graphe ou de carte.

Des données intelligentes permettent également d’en automatiser l’accès par API ( Application Programming Interface) : L’accessibilité des données par interface de programmation est une condition nécessaire pour massifier et industrialiser les usages qui peuvent être fait de ces dernières. Les données indexées dans le datastore sont ensuite « requetables » directement à travers l’API à travers une série de fonctionnalités puissantes. ( voir la présentation de l’API CKan : http://datasud.readthedocs.io/fr/latest/developpeurs/index.html#service-api-ckan)

Vos jeux de données doivent être préparés pour être proprement indexés dans le datastore :

  • Le format CSV doit être privilégié avec un ; comme séparateur / délimiteur.
  • Idéalement, passez tous vos jeux de données en UTF-8. Pour cela le programme Notepad++ fait cela très bien.
  • Idéalement, exportez vos tableurs favoris (Microsoft, Libre et Open Office) au format CSV.
  • Restreindre vos titres de colonnes à moins de 62 caractères.
  • Ne pas doublonner le titre d’une colonne.
  • En théorie les caractères spéciaux (“:.,( -“) sont acceptés, mais c’est beaucoup mieux de les éviter dans les titres.
  • Harmoniser le type de vos données (et oui vos données sont typées!) : en effet si une colonne ne comporte que des chiffres, le datastore autodéterminera le type de cette colonne comme étant un nombre. Or il suffit qu’une cellule de la colonne contienne l’entrée N/A, pour que le datastore génére une erreur.

Pour éviter les erreurs de type, il est préférable de les corriger avant d’indexer le jeu de donnée dans DataSud ou bien de transformer la valeur des cellules en cellules au format TEXTE. Cela n’est pas satisfaisant, mais ca fonctionne.

  • ERREUR : En cas d’erreur supprimez complètement la ressource associée au jeu de données et ajoutez en une nouvelle.

Note

Attention avec Excel

  • lorque le fichier contient plusieurs feuillet (ou onglet), seule la dernière feuille de calcul est indexée dans le datastore. Il est donc nécessaire de déplacer la feuille de calcul contenant les données que vous souhaitez indexer dans le datastore en dernière place de votre tableur.
  • si vous ne voulez pas indexer vos données dans le datastore (pour plein de bonnes et mauvaises raisons), il suffit d’ajouter une feuille de calcul vide en dernière place de votre tableur.

Géolocalisation des données tabulaires (XLS et CSV)

Une carte peut automatiquement être générée à partir de vos données tabulaires geolocalisées. Pour cela vous devez intituler deux colonnes du tableau « latitude » et « longitude » OU « lat » et « lon » OU « Y » et « X ».

Celles-ci doivent être en exprimées en angles, avec des décimales séparées par un point et non une virgule, avec pour référentiel le système géodésique mondiale (`WGS84<https://fr.wikipedia.org/wiki/WGS_84>`_) pour être interprétées par DATASUD. À titre d’exemple, le centre de Marseille a pour coordonnées « 43.2803692 » et « 5.31045872 ».

Le paramétrage des vues

Un contributeur a la possibilité de paramétrer les vues (la vue par défaut et des vues supplémentaires) visibles par un utilisateur du catalogue.

Les Géo-Services

Lors de la publication d’un jeu de données géographique, si le format est bien perçu par Datasud comme étant un format géographique, des flux WMS et WFS sont automatiquement déclenchés. Côté catalogue, ils sont disponibles depuis le dataset, dans la partie « services ».

Le contributeur a la possibilité de paramétrer le style des flux WMS. Il peut éditer le flux par défaut, utilisé dans l’affichage du flux côté catalogue.

L’extracteur Géographique

La publication d’un jeu de données géographique induit la disponibilité de cette données via l’extracteur de données.

Le moissonnage de données

Espace référents

Ce chapitre est destiné aux administrateurs distants de données de DATASUD, souhaitant gérer la publication, les droits des utilisateurs, le territoire de compétence de leur [ORGANISATION](contributeurs#license).

Qu’est-ce qu’un référent dans DATASUD ?

Un Référent des données de l’Organisation, à laquelle il appartient, dispose des fonctionnalités suivantes :

  • Il peut éditer ou supprimer un jeu de données créé et publié par un autre Contributeur de l’Organisation,
  • Il peut accorder le niveau d’accès aux ressources et jeux de données de toutes les publications de son Organisation,
  • Il peut autoriser ou supprimer le statut de Contributeur aux Utilisateurs,
  • Il recoit des notifications lorsque des modifications ont été apportées aux jeux de données et ressources de l’Organisation à laquelle il appartient.

Comment devenir référent ?

Gérer les demandes de rattachement et de contribution

Espace développeurs

Service API CKAN

Le site https://trouver.datasud.fr est construit à partir du système d’information OpenSource dédié à la gestion de catalogues de données CKAN.

Requêter l’API CKAN Catalogue

CKAN propose une API permettant d’interroger et de consulter le catalogue des données et leurs ressources. L’API permet également de requêter directement le contenu des ressources tabulaires (CSV, XLS) lorsque celles-ci ont été correctement intégrées au Datastore (http://datasud.readthedocs.io/fr/latest/producteurs.html#datastore-et-donnees-intelligentes).

Ainsi, il est par exemple possible de réaliser ce qui suit.

Requêter l’API CKAN DATA

DataSud.fr permet également de requêter directement le contenu des jeux de données, ou plutôt de leurs ressources. Cette mécanique est rendue possible à travers l’interrogation de l’API de données de CKAN (API CKAN DATA).

Comme expliqué plus haut, le Datastore propose un service d’indexation des données tabulaires (CSV et XLS). L’API CKAN DATA permet d’exposer le contenu des ressources indexées dans le Datastore dont on peut ainsi interroger tout ou partie sans avoir à télécharger le jeu de données. Il est alors possible de faire des opérations de recherche sur les différents champs de données.

  • Afficher les cinq enregistrements du jeu de données des hôtels en région Provence-Alpes-Côte d’Azur :

Cette requête utilise la méthode datastore_search de l’API de CKAN avec la notion de filtres.

https://trouver.datasud.fr/api/3/action/datastore_search?resource_id=9723b8ba-8379-4b1f-a85c-1f0efe916ce8&limit=5

Requête et résultats : https://bit.ly/2Lc3T12

  • Trouvez toutes les entreprises de la base INFOGREFFE 2017 dont le champ ville est égal à MARSEILLE:

Cette requête utilise la méthode datastore_search de l’API de CKAN avec la notion de filtres.

https://trouver.datasud.fr/api/3/action/datastore_search?resource_id=9723b8ba-8379-4b1f-a85c-1f0efe916ce8&filters={"Ville":"MARSEILLE"}

Requête et résultats : http://bit.ly/2BKn6VW

  • Trouver toutes les entreprises de la base INFOGREFFE 2017 de la ville de MARSEILLE avec le code APE 6831Z, et afficher les résultats à partir du centième (série de 100 à 199)

Cette requête utilise la méthode datastore_search de l’API de CKAN avec la notion de filtres.

resource_id=9723b8ba-8379-4b1f-a85c-1f0efe916ce8&filters={"Ville":"MARSEILLE","Code APE":"6831Z"}&offset=100

Requête et résultats : http://bit.ly/2oliZId

  • Production électrique régionale : trouvez les horaires ou le solaire est supérieur à 20MW (requête SQL)

Cette requête utilise la méthode datastore_search_sql de l’API de CKAN avec la notion de requête SQL .

https://trouver.datasud.fr/api/3/action/datastore_search_sql?sql=SELECT from "52a8f5dd-758d-4e54-a837-8fc7ad57d378"  WHERE "Solaire (MW)" > '20' AND "Date" > '2018-07-10'

Requête et résultats : https://bit.ly/2N8JCKn

Documentation de l’API (catalogue et ressources) et de l’API Datastore (requête sur les ressources) en anglais :

http://docs.ckan.org/en/latest/api/ http://docs.ckan.org/en/ckan-2.7.2/maintaining/datastore.html#the-datastore-api

Note

le mot « package » qu’on trouve dans certaines requête et dans la documentation CKAN correspond à un jeu de donnée.

Construire une requête pour l’API CKAN DATA

Pour appeler l’API CKAN, postez un dictionnaire JSON dans une requête HTTP POST sur l’une des URL d’API de CKAN. Les paramètres de la fonction API doivent être indiqués dans le dictionnaire JSON. CKAN retournera également sa réponse dans un dictionnaire JSON.

Une façon de publier un dictionnaire JSON sur une URL est d’utiliser le client HTTP en ligne de commande HTTPie. Il existe également d’autres outils comme Postman. Par exemple, pour obtenir une liste des noms de tous les jeux de données du groupe environnment sur le site, installez HTTPie, puis appelez la fonction API group_list en exécutant cette commande dans un terminal:

http http://trouver.datasud.fr/api/3/action/group_list

La réponse de CKAN ressemblera à ceci:

{
    "help": "...",
    "result": [
        "data-explorer",
        "department-of-ricky",
        "geo-examples",
        "geothermal-data",
        "reykjavik",
        "skeenawild-conservation-trust"
    ],
    "success": true
}

La réponse est un dictionnaire JSON avec 3 clés :

  1. "success": true or false.

    L’API est conçue pour retourner à chaque fois un 200 OK dans le code statut de sa réponse, qu’il y ait une erreur ou non dans la requête, il est donc important de toujours vérifier la valeur de la clé success dans le dictionnaire de réponse, et si elle est à false, de vérifier la valeur de la clé error.

Note

S’il y a vraiment un gros problème de syntaxe dans la requête à l’API, CKAN pourra retourner une réponse HTTP avec un status code 409, 400 or 500 (dans l’ordre croissant de gravité). Dans les prochaines versions de CKAN, il est prévu d’essayer de supprimer ce type de réponse pour n’avoirà la place que des retours 200 OK et utiliser les valeurs "success" et "error".

  1. "result": le résultat retournée par la fonction appelée. Le type et la valeur du résultat dépendent de la fonction appelée. Dans le cas de la fonction group_list, il s’agit d’une liste de chaînes, les noms de tous les jeux de données qui appartiennent au groupe.

    Si c’est une erreur qui est retournée à la requête, le dictionnaire contiendra une clé "error" avec le détail de l’erreur au lieu de la clé "result". Un dictionnaire de réponse contenant une erreur ressemblera à ceci:

    {
    "help": "Creates a package",
    "success": false,
    "error": {
        "message": "Access denied",
        "__type": "Authorization Error"
        }
 }

  2. "help": le texte de documentation de la fonction appelée.

La même requête HTTP peut être effectuée en utilisant le module Python standard urllib2 avec ce code Python

#!/usr/bin/env python
import urllib2
import urllib
import json
import pprint

# Make the HTTP request.
response = urllib2.urlopen('http://demo.ckan.org/api/3/action/group_list',
        data_string)
assert response.code == 200

# Use the json module to load CKAN's response into a dictionary.
response_dict = json.loads(response.read())

# Check the contents of the response.
assert response_dict['success'] is True
result = response_dict['result']
pprint.pprint(result)

Versions de l’API CKAN

Les API CKAN sont versionnées. Si vous faites une demande à une URL d’API sans numéro de version, CKAN choisira la dernière version de l’API:

https://trouver.datasud.fr/api/action/package_list

Vous pouvez également spécifier le numéro de version de l’API souhaité dans l’URL que vous envoyez:

https://trouver.datasud.fr/api/3/action/package_list

La version 3 est actuellement la seule version de l’API Action.

Nous vous recommandons de spécifier le numéro d’API dans vos demandes, car cela garantit que votre client API continuera à fonctionner si un jour le site est mis à niveau vers de nouvelles versions de CKAN).

Authentification et clés

Certaines fonctions de l’API nécessitent une autorisation, par exemple pour ajouter ou modifier des jeux de données et desressources). L’API utilise la même fonction d’autorisation et la configuration en tant qu’interface web, donc si un utilisateur est autorisé à faire quelque chose dans l’interface web, ils sera autorisés à le faire via l’API de la même façon.

Lorsque vous appelez une fonction de l’API nécessitant une autorisation, vous devez vous authentifier vous-même en fournissant votre clé API avec votre requête HTTP. Pour trouver votre clé API, connectez-vous au site CKAN en utilisant son interface web et visitez votre profil utilisateur.

Pour fournir votre clé API dans une requête HTTP, incluez-la dans un En-tête `` Authorization`` ou `` X-CKAN-API-Key``.

Par exemple, pour demander si vous suivez actuellement l’utilisateur `` markw`` sur demo.ckan.org en utilisant HTTPie, exécutez cette commande:

https://trouver.datasud.fr/api/3/action/am_following_user id = markw Autorisation: XXX

(Remplacer `` XXX`` avec votre clé API.)

Par exemple, pour obtenir la liste des activités de votre tableau de bord utilisateur, on lance ce code Python ::
request = urllib2.Request(“http://trouver.datasud.fr/api/3/action/dashboard_activity_list”) request.add_header(“Authorization”, “XXX”) response_dict = json.loads(urllib2.urlopen(request, “{}”).read())

Support JSONP

Pour répondre aux scripts d’autres sites qui souhaitent accéder à l’API, les données peuvent être renvoyé au format JSONP, où les données JSON sont “complétées” avec une fonction call. La fonction est nommée dans le paramètre “callback”. Par exemple:

https://trouver.datasud.fr/api/3/action/package_show?id=adur_district_spending&callback=myfunction

Note

Cela ne fonctionne qu’avec les requêtes GET

Service API OGC

Le site https://trouver.datasud.fr intègre des API OGC pour toutes les organisations publiant des données géographiques. Les API OGC sont des API standardisé par l’Open Geospatial Consortium <http://www.opengeospatial.org/> (OGC). Les standards utilisés dans DATASUD sont le WMS (Web Mapping Service), le WFS (Web Feature Service) et le CSW (Catalog Service for the Web).

Service WMS

En cours.

Service WFS

En cours.

Service CSW

En cours.

DATASUD, c’est …

DATASUD est une infrastructure de données à l’échelle régionale, accessibles à travers un catalogue de données à l’échelon régional. Elle est issue d’un projet piloté par le CRIGE Provence-Alpes-Côte d’Azur et la Région SUD Provence Alpes-Côte d’Azur, avec la participation financière de l’État et du Conseil départemental des Hautes-Alpes lancé fin 2016.

Le catalogue de données diffuse des données ouvertes, géographiques et intelligentes au service du développement des territoires et de l’innovation numérique. 80 organisations diffusent déjà des données sur DATASUD.

Des données supplémentaires vont être intégrées au fil de l’eau en 2019, en particulier toutes les données du Géoportail régional du CRIGE.

Pour quel public ?

DATASUD s’adresse :
  • aux producteurs de données en région, pour référencer et diffuser leur patrimoine de données à l’échelon régional ;
  • aux réutilisateurs pour trouver des données, les croiser, les analyser afin de développer le territoire régional ;
  • aux entreprises et start-up, à la recherche de données et de services performants pour proposer les applications innovantes de demain ;
  • aux citoyens et acteurs de la transparence de l’action publique.

Quels types de données trouve-t-on dans DataSud ?

DATASUD référence uniquement des données brutes. Par données « brutes » est entendu fichiers tabulaires (ex. tableur Excel), fichiers à composantes géographiques directe (qui contient des informations de points, lignes, polygones comme les fichiers GEOJSON ou ESRI Shapefile par ex.) ou indirecte.

DATASUD référence préférentiellement :
  • des données ouvertes ;
  • des données intelligentes ;
  • des données géographiques.

DATASUD permet également de référencer des données sensibles, en offrant la possiblité d’ouvrir ou non des accès à des utilisateurs ou des organisations. Pour favoriser les réutilisations, les données sont préférentiellement proposées dans des formats ouverts : CSV, JSON, GEOJSON, GPKG, JPEG2000, GeoTIFF. Elles sont ainsi lisibles dans un maximum d’applications et de logiciels.

Toute donnée de DATASUD est accompagné d’une licence. Celle-ci définit les conditions d’utilisation du jeu de données. Il convient d’en prendre soigneusement connaissance avant toute réutilisation. En cas de doute, vous pouvez contacter le producteur du jeu de données ou les administrateurs de DATASUD.

Qui peut s’inscrire à DATASUD ?

Note

Toute personne, morale ou physique peut s’inscrire. L’inscription à DATASUD est gratuite et individuelle, sous réserve d’accepter les « conditions d’utilisation » de la plateforme.

Qui peut publier des données ?

Toute personne, morale ou physique, publique ou privée, producteur de données publiques ou privées peut publier des données sur DATASUD, sous réserve d’accepter les « conditions d’utilisation » et de respecter la réglementation sur les données à caractères personnelles.

Plus précisément, vous pouvez publier des données sur datasud.fr :
  • si vous produisez ou collectez des données dans le cadre d’une mission de service public, à condition que ces données ne contiennent pas d’informations personnelles et qu’elles ne révèlent pas d’informations confidentielles ;
  • si vous enrichissez ou complétez des données pour le compte d’une association, d’un projet de recherche, ou sur votre temps libre ;
  • si vous produisez des données d’intérêt public, même hors du cadre d’une mission de service public ;
  • si vous produisez des données privées ie. accessibles uniquement à certains acteurs, sous réserve de respecter la réglementation en vigueur.

Note

La publication des jeux de données fait l’objet d’un contrôle a posteriori. Il convient donc de bien vérifier quelles informations sont publiées sur DATASUD. L’équipe de DATASUD se réserve également le droit de dépublier tout jeu de données jugé non conforme à la ligne éditoriale de la plateforme, et d’en informer ses producteurs.

Qu’est-ce qu’une Organisation pour DATASUD ?

Les organisations sont des personnes morales produisant ou intéressées par tout type de données : autorités administratives, établissements publics, associations, entreprises, start-up. Il s’agit d’entités au travers desquelles plusieurs utilisateurs peuvent collaborer sur des jeux de données.

Dans DATASUD, plusieurs contributeurs appartenant à des organisations différentes peuvent contribuer pour une organisation, moyennant validation d’un référent de ladite organisation ou d’un administrateur. Exemple : l’utilisateur “mdupont” membre de l’organisation “bureau d’étude” peut publier pour l’organisation “communauté d’agglomération” car l’utilisateur “dsi” qui est rattachée à celle-ci l’y a préalablement autorisé.

Quels services et fonctionnalités sont fournis par DATASUD ?

DATASUD repose sur un catalogue unique à l’échelle régionale pour toutes les données tabulaires ou géographiques, proposant un guichet unique et simplifiée de publication de données. Ce catalogue sur la technologie “CKAN <https://ckan.org/>”.

À travers ce catalogue, il permet aux utilisateurs de rechercher et de trouver des jeux de données, de les télécharger en 1-clic, de s’abonner et de déclarer des réutilisations faites avec des jeux de données de DATASUD. Les producteurs ou contributeurs de données

DATASUD propose également des outils métier pour les utilisateurs plus experts :
  • publication des données tabulaires par API : l’outil CKAN
  • publication d’API (ou flux) de données géographiques selon les standards WMS et WFS ;
  • publication de métadonnées INSPIRE : DATASUD offre aux organisations concernées la possibilité d’indexer leurs métadonnées de données géographiques selon le formalisme requis par le Directive INSPIRE ;
  • catalogage « en marque blanche » intégrable sur tout site internet ou tout portail institutionnel ;
  • l’extraction de données raster et vecteur à travers l’extracteur de données géographiques du CRIGE ;
  • la co-visualisation de données géographiques à travers l’outil de création de visionneuse du CRIGE ;

Note

Les deux derniers services sont accessibles uniquement aux partenaires du CRIGE.

Je dispose déjà d’un catalogue de données

DATASUD offre la possibilité de « moissonner », c’est-à-dire de référencer des jeux de données publiées sur des catalogues existants. Pour l’instant, il offre cette possibilité pour les types de catalogues suivant :

  • CKAN 2.*
  • GeoNetwork 3.*
  • ISOGEO

Si vous êtes dans cette situation et souhaitez référencer vos jeux de données, contactez les administrateurs de Datasud via la formulaire de contact ou sur contact@datasud.fr en indiquant votre demande.

Je suis développeur et souhaite utiliser les API de DATASUD

Le catalogue de DataSud (https://trouver.datasud.fr) est construit à partir du système d’information OpenSource dédié à la gestion de catalogues de données “CKAN <https://ckan.org/>”.

L’application CKAN propose une API REST permettant d’interroger et de consulter les jeux de données et leurs ressources référencés dans le catalogue, soit selon le formalisme de CKAN soit selon le standard DCAT. Elle permet également de requêter et d’exposer directement le contenu (ou une partie du contenu) des ressources tabulaires (CSV, XLS). Vous trouverez plus de détails sur les méthodes offertes ici.

DATASUD offre en plus la possibilité de requêter et d’exposer le contenu des données géographiques selon les standards d’API WMS et WFS grâce à l’outil MapServer. Vous trouverez plus de détails sur les méthodes offertes ici.

Voir aussi

Table des matières

Note

Ces guides sont maintenus par l’équipe Datasud (administrateurs de la Région SUD et du CRIGE Provence-Alpes-Côte d’Azur).