• Manuel

• Utiliser

• Utiliser l’API opendata.swiss

Utiliser l’API opendata.swiss

Comment utiliser l’accès API d’opendata.swiss ?

Le portail opendata.swiss est basé sur le projet open-source CKAN. CKAN met à disposition une API (Application Programming Interface) complète pour les métadonnéedu catalogue de données ouvertes, que les développeurs d’applications peuvent utiliser. Dans ce chapitre, nous vous expliquons comment accéder aux données d’opendata.swiss par l’API. Jetez également un coup d’oeil sur des exemples actuelles d’utilisation de données publiques ouvertes.

Bon à savoir

Nous vous donnons ici une introduction à l’utilisation de l’API d’opendata.swiss. Vous trouverez une documentation détaillée sur l’API CKAN dans la documentation API CKAN.

Introduction

Une API (Application Programming Interface) permet à un logiciel de communiquer directement avec un système externe – ici les métadonnées sur la plateforme opendata.swiss. Alors que le site web de la plate-forme opendata.swiss et sa fonction de recherche sont conçus pour être utilisés par des humains, nous offrons une possibilité d’accès optimisé pour l’automatisation par l’API.

Utilisation de l’API - Comment cela fonctionne

• Possibilités d’accès

• API d’action

• Exemples d’une reponse de l’API

• Terminologie

• Exemples

Possibilités d’accès

Plusieurs options existent pour accéder à l’API d’opendata.swiss :

• via le navigateur

• par la ligne de commande

• par des outils spécialisés comme ckanapi ou Fetch-API

Les différents types d’accès conviennent aux différents besoins de l’utilisation. Pour l’accès via le navigateur, nous recommandons l’utilisation d’un visualiseur JSON (natif ou plug-in) afin d’améliorer la lisibilité des informations.

L’URL de base est https://ckan.opendata.swiss/api/3/action/ et est suivie de l’action et des éventuelles informations complémentaires nécessaires.

Accès API via le navigateur

https://opendata.swiss/api/3/action/package_search?fq=tags:economy

Accès API via la ligne de commande, par exemple avec cURL

curl 'https://opendata.swiss/api/3/action/package_search?fq=tags:economy'

API Accès via l’outil CKAN ckanapi

ckanapi -r https://opendata.swiss action package_search fq='tags:economy'

Action API

Tous les accès utilisent le terme action, comme démontré dans l’exemples ci-dessus. En principe, la plupart des fonctions de CKAN sont programmées comme action, de sorte à ce qu’elles puissent être déclenchées via l’API. Pour en savoir plus, consultez la section API d’action de la documentation CKAN.

La réponse à la requête est émise sous forme d’objet JSON. Pour en savoir plus sur la structure des JSON, cliquez ici.

Tout d’abord, une adresse s’affiche pour vous fournir des informations de base sur votre demande (help). Le système vous informe ensuite si la demande a été acceptée (success : true ou success : false). Sous result, vous trouverez le contenu des informations que vous avez demandées.

Exemples d’une réponse de l’API

JSON string

{
"help": "https://ckan.opendata.swiss/api/3/action/help_show?name=package_show",
"success": true,
"result": {
    "owner_org": "4309c328-c618-4077-bcdc-378a21ee1b46"
    "maintainer": "info@bfs.admin.ch",
    "issued": "2023-03-01T00:00:00",
    "title_for_slug": "csv-file-der-datensatze-auf-opendata-swiss",
    "private": false,
    "maintainer_email": "auskunftsdienst@bfs.admin.ch",
    "num_tags": 9,
    "contact_points": [
        {"email": "auskunftsdienst@bfs.admin.ch",
        "name": "info@bfs.admin.ch"}
        ],
    "keywords": {
        "fr": [
            "tableau",
            "bases-statistiques-et-generalites"
            ],
        "de": [
                "tabelle",
                "grundlagen-und-ubersichten"
                ],
        "en": [
                "statistical-basis-and-overviews",
                "table"
            ],
        "it": [
                "tabella",
                "basi-statistiche-e-presentazioni-generali"
            ]
        },
    "temporals": [],
    "id": "380fbe1f-8ddb-4bbe-bdcf-68217cd42f09",
    "metadata_created": "2023-03-01T09:36:26.218643",
    "relationships_as_object": [],
    "display_name": {
        "fr": "Fichier csv des jeux de donn\u00e9es sur opendata.swiss",
        "en": "csv-file of the data sets on opendata.swiss",
        "de": "csv-File der Datens\u00e4tze auf opendata.swiss",
        "it": "File csv dei set di dati su opendata.swiss"},
    "metadata_modified": "2023-03-02T10:38:56.947322",
    "author": null,
    "author_email": null,
    "relations": [{
        "url": "https://www.admin.ch/opc/de/classified-compilation/19920252/index.html",
        "label": "legal_basis"}],
    "state": "active"
    }
}

Une requête API via le navigateur vous fournit les informations suivantes:

Informations au niveau Dataset

Key	Value
help	À l’adresse indiquée, vous trouverez des informations supplémentaires sur la requête.
success	Votre requête était-elle correctement formulée? Si le résultat est True mais qu’une liste vide est retournée, la syntaxe de votre requête était correcte, mais aucun enregistrement ne correspond à vos paramètres.
result	Cette réponse corresponde à votre demande.
issued	La date de création du dataset.
title_for_slug	Ce contenu correspond au nom du dataset.
id	L’identifiant du dataset.
type	Le type de dataset. Les types possibles sont dataset, harvester, showcase.
description	La description du dataset.
groups	Les catégories auxquelles le dataset appartient.
publisher	L’organisation qui a publié le dataset. Y compris le nom, l’URL, etc.
organization	Les informations sur l’organisation de l’éditeur, responsable du contenu du dataset. Y compris le nom, l’URL, le nombre de datasets publiés (i.e. package_count).
name	Terme indépendant de la langue qui peut être utilisé pour la requête API.
accrual_periodicity	Indication de la fréquence de mise à jour du dataset. Vocabulaire contrôlé selon la norme de data.europa.eu.
resources	Une liste des ressources appartenant au dataset. On y trouve également les métadonnées correspondantes aux ressources.

Informations au niveau resource

Key	Value
package_id	L’identifiant du dataset auquel appartiennent les ressources.
issued	La date de création de la ressource.
id	L’ID de la ressource.
download_url	L’adresse à laquelle la ressource peut être téléchargée.
media-type	Der Medientyp der Ressource.
format	Le format de la ressource.
rights	Les conditions d’utilisation de la ressource.
created	La date à laquelle la ressource a été créée dans la base de données.
description	La description de la ressource.
num_resources	Le nombre de ressources pour le dataset.

Terminologie CKAN dans opendata.swiss

L’API permet d’effectuer une recherche dans l’ensemble des métadonnées dans opendata.swiss. La syntaxe de recherche correspond à Apache Lucene, car opendata.swiss est basé sur CKAN et utilise Apache Solr comme moteur de recherche. Ceci est également décrit en détail dans la documentation CKAN. Travaillez-vous avec des métadonnées de l’organisation, des métadonnées des datasets ou des métadonnées avec lesquelles vous pouvez trouver des informations dans opendata.swiss :

organization

Correspond à l’organisation qui publie les données. Chaque dataset est publié par une seule organisation. Une organisation peut toutefois avoir des sous-organisations.

package, dataset

Correspond à un jeu de donnée sur opendata.swiss. Il s’agit des métadonnées relatives à un ensemble de ressources.

id

Correspond en règle générale au identifiant (slug) du dataset ou de l’organisation sur opendata.swiss. Pour les cas exceptionnels, veuillez consulter la documentation CKAN.

resource, distribution

Correspond à une distribution ou forme de distribution sur opendata.swiss. La plateforme opendata.swiss n’héberge pas elle-même des datasets ou des ressources, mais met à disposition des downloadUrls ou des accesssUrls et parfois aussi des data previews. Les ressources dans CKAN correspondent à dcat:Distribution dans le standard DCAT AP .Un dataset peut appartenir à plusieurs catégories.

group

Correspond à une catégorie sur opendata.swiss ou dcat:theme dans le standard DCAT AP.

Exemples d’application de l’API

Requêtes typiques pour les utilisateurs de données

status_show

Statut de la plateforme

 curl 'https://ckan.opendata.swiss/api/3/action/status_show'

organization_list

Liste de toutes les organisations

curl 'https://ckan.opendata.swiss/api/3/action/organization_list'

package_list

Liste de tous les datasets

curl 'https://opendata.swiss/api/3/action/package_list'

package_search, fq, organization

Liste de tous les datasets d’une organisation spécifique

curl 'https://ckan.opendata.swiss/api/3/action/package_search?fq=organization:bundesamt-fur-statistik-bfs'

package_show, id

Informations sur un dataset spécifique

curl 'https://ckan.opendata.swiss/api/3/action/package_show?id=administrative-units-switzerland-inspire'

package_search, language

Recherche de tous les datasets par langue

curl 'https://ckan.opendata.swiss/api/3/action/package_search?fq=language:de'

group_list

Liste des catégories

curl 'https://ckan.opendata.swiss/api/3/action/group_list'

facet_field

Liste des dix mots-clés les plus fréquents

curl 'https://ckan.opendata.swiss/api/3/action/package_search?facet.field=[%22tags%22]&facet.limit=10&rows=0'

sort=relevance+asc

Recherche des mots-clés par fréquence croissante

curl 'https://ckan.opendata.swiss/api/3/action/package_search?facet.field=[%22keywords%22]&sort=relevance+asc'

Applications typiques pour les personnes publiant des données

packet_search, organization, dataset_type

Trouver l’identifiant Harvester de son organisation

curl 'https://ckan.opendata.swiss/api/action/package_search?q=(organization:[“name” Ihrer Organisation)&fq=dataset_type:harvest'

packet_search, -harvest_source_id, organization

Liste des données ajoutées manuellement

curl 'https://ckan.opendata.swiss/api/3/action/package_search?fq=-harvest_source_id:(*)organization:(“name” Ihrer Organisation)'

packet_search, harvest_source_id

Liste des données harvestées de votre organisation

curl 'https://ckan.opendata.swiss/api/3/action/package_search?fq=harvest_source_id:[id Ihres Harvesters]'

POST

Si vous disposez des droits nécessaires, vous pouvez également adapter les métadonnées de vos datasets via l’interface API. Vous trouverez votre clé API sur la page utilisateur sur le backend d’opendata.swiss. La syntaxe exacte dépend entre autres de votre système opérateur spécifique (par exemple le format correcte des guillements).

Envoi (POST) via l’interface API: package_patch

curl -X POST https://ckan.ogdch-abnahme.clients.liip.ch/api/3/action/package_patch -H "Authorization: YOUR-PERSONAL-API-KEY"
-d "{""id"": ""eafa8336-3012-47f2-bc6a-bd3044687484"", ""accrual_periodicity"": ""http://publications.europa.eu/resource/authority/frequency/CONT""}"

Les datasets peuvent également être créés via l’API. Pour cela, vous avez besoin de votre clé API et vous devez transmettre les métadonnées au format JSON.

Envoi (POST) via l’interface API: package_patch

{
'name': 'NAME_PACKAGE',
'identifier': 'NAME_PACKAGE@YOUR-ORGANIZATION-SLUG',
'issued': '2023-02-12T00:00:00',
'private': False,
'isopen' : False,
'display_name': {
    'fr': 'display_name test_API_POST package fr',
        'de': 'display_name test_API_POST package de',
        'en': 'display_name test_API_POST package en',
        'it': 'display_name test_API_POST package it'
        },
'type': 'dataset',
'state': 'active',
'description': {
        'fr': 'description test_API_POST package fr',
        'en': 'description test_API_POST package en',
        'de': 'description test_API_POST package de',
        'it': 'description test_API_POST package it'
        },
'title': {
        'fr': 'title test_API_POST package fr',
        'de': 'title test_API_POST package de',
        'en': 'title test_API_POST package en',
        'it': 'title test_API_POST package it'
        },
'publisher': {
    'url': 'YOUR_ORGANIZATION_S_URL',
    'name': 'YOUR_ORGANIZATION'
    },
'keywords': {
    'fr': ['list', 'of','keywords', 'per','language','fr'],
    'de': ['list', 'of','keywords', 'per','language','de'],
    'en': ['list', 'of','keywords', 'per','language','en'],
    'it': ['list', 'of','keywords', 'per','language','it'],
    },
'contact_points': [{
    'email': 'CONTACT.POINT@EMAIL.ADDRESS',
    'name': 'NAME'
    }],
'accrual_periodicity': 'http://publications.europa.eu/resource/authority/frequency/MONTHLY',
'resources': [{
'owner_org': 'YOUR_ORGANIZATION_ID_ON_OPENDATA.SWISS',
        'display_name': {
        'issued': '2023-02-12T00:00:00',
                'de': 'display_name test_API_POST resource de',
                'fr': 'display_name test_API_POST resource fr',
                'it': 'display_name test_API_POST resource it'
                'en': 'display_name test_API_POST resource en',
        'title': {
                },
                'de': 'title test_API_POST resource de',
                'fr': 'title test_API_POST resource fr',
                'it': 'title test_API_POST resource it'
                'en': 'title test_API_POST resource en',
        'download_url': 'https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_200KB_CSV-1.csv',
                },
                'fr': 'description test_API_POST resource fr',
        'description': {
                'de': 'description test_API_POST resource de',
                'en': 'description test_API_POST resource en',
                },
                'it': 'description test_API_POST resource it'
        'name': {
    'format' : 'CSV',
                'de': 'name test_API_POST resource de',
                'fr': 'name test_API_POST resource fr',
                'en': 'name test_API_POST resource en',
                'it': 'name test_API_POST resource it'
                },
        'rights': 'NonCommercialAllowed-CommercialAllowed-ReferenceNotRequired',
        'url': 'https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_200KB_CSV-1.csv',
    'identifier': 'identifier_resource_for_name_package_''@YOUR-ORGANIZATION-SLUG',
        }],
}

Veuillez noter que les conditions d’utilisation (au niveau de la ressource) correspondent au vocabulaire contrôlé. Veuillez vérifier la norme DCAT AP CH içi.

Entre outres, les indications private et isopen sont obligatoire. Avec private, vous pouvez définir si le dataset est directement publié. Un dataset avec private:False est publié directement sur le frontend. Avec isopen, vous déclarez si les conditions d’utilisation correspondent à la définition de open selon l’Open Knowledge Foundation.

Fetch API

Vous pouvez aussi accéder à opendata.swiss via Fetch API.

Support

Des questions?

Avez-vous des questions sur l’utilisation de notre API? N’hésitez pas à nous contacter. Si vous avez des questions sur les différents datasets, veuillez vous adresser directement aux les personnes qui publient les données. Vous trouverez les coordonnées dans le dataset sous « Informations complémentaires ».

Vous avez un exemple d’utilisation intéressant ? Nous serions ravis d’en prendre connaissance et d’intégrer votre projet dans nos showcases. Vous pouvez aussi nous écrire.

Informations complémentaires

• Consignes d’utilisation de l’API CKAN sous Guide API CKAN (Link)