Handbuch
Nutzen
opendata.swiss API nutzen

opendata.swiss API nutzen

Wie nutze ich den API-Zugriff von opendata.swiss?

Das Portal opendata.swiss basiert auf dem Open-Source-Projekt CKAN. CKAN stellt eine umfangreiche API für die Metadaten des offenen Datenkatalogs zur Verfügung, die Applikationsentwickler_innen nutzen können. In diesem Kapitel erklären wir Ihnen, wie Sie mittels API auf die Daten von opendata.swiss zugreifen können. Werfen Sie auch einen Blick in aktuelle Beispiele, wie OGD genutzt wird.

Gut zu wissen

Hier geben wir Ihnen eine Einführung zur Nutzung der API von opendata.swiss. Eine ausführliche Dokumentation zur CKAN API finden Sie in der CKAN API Dokumentation.

Einführung

Eine API (Application Programming Interface) ermöglicht es, dass Software direkt mit einem externen System (in diesem Fall den Metadaten auf der Plattform opendata.swiss) interagiert. Während die Webseite der Plattform opendata.swiss und die Suchfunktion auf die Nutzung durch Menschen ausgerichtet ist, bieten wir über die API eine Zugriffsmöglichkeit, die für die Automatisierung optimiert ist.

Zugriffsmöglichkeiten

Sie haben verschiedene Möglichkeiten, auf die API von opendata.swiss zuzugreifen:

via Browser,
über die Kommandozeile, oder durch
spezialisierte Werkzeuge wie ckanapi oder Fetch-API.

Je nach Einsatzzweck eignen sich verschiedene Arten. Für den Zugriff über den Browser empfehlen wir die Nutzung eines JSON-Viewers (nativ oder Plug-In), um die Lesbarkeit der Informationen zu verbessern.

Die Basis-URL lautet https://ckan.opendata.swiss/api/3/action/ und wird gefolgt von der Aktion und allfälligen notwendigen Zusatzinformationen.

API Zugriff über den Browser

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

API Zugriffe über die Kommandozeile, etwa mit cURL

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

API Zugriffe über das CKAN Werkzeug ckanapi

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

Action-API

Alle Zugriffe verwenden das Wort action, wie in den Beispielen oben zu beobachten ist. Grundsätzlich sind die meisten Funktionen in CKAN als action programmiert, so dass sie über die API angestossen werden können. Mehr dazu lesen Sie im Abschnitt Action-API in der CKAN Dokumentation.

Die Rückmeldung wird als JSON Objekt ausgegeben. Mehr über die Struktur von JSON Objekten erfahren Sie hier.

Zuerst wird Ihnen eine Adresse angezeigt, unter der Sie Hintergrundinformationen zu Ihrer Anfrage erhalten (help). Darauf meldet Ihnen das System, ob die Anfrage erfolgreich war (success: true oder success: false). Unter result finden Sie die Inhalte Ihrer angefragten Informationen.

Beispiel API Response

JSON string

Eine API-Abfrage über den Browser liefert Ihnen als Beispiel folgende Informationen:

Übersicht Angaben Dataset-Ebene
Key	Value
help	Unter der angegebenen Adresse finden Sie weitere Informationen zur Query.
success	War Ihre Query richtig formuliert, so dass ein Ergebniss gefunden wurde? Falls True ausgegeben wird, aber eine leere Liste retourniert wird, war die Syntax Ihrer Anfrage korrekt formuliert, aber keine Datensätze entsprechen Ihren Parametern.
result	Diese Datensätze entsprechen Ihrer Anfrage.
issued	Das Erstelldatum des Datasets.
title_for_slug	Inhalt entspricht dem Namen des Datasets.
id	Die ID des Datasets.
type	Der Typ des Datasets. Mögliche Typen sind dataset, harvester, showcase.
description	Die Beschreibung des Datasets.
groups	Die Kategorien, zu der das Dataset gehört.
publisher	Die Stelle, welche das Dataset veröffentlicht hat. Inkl. name und url, etc.
organization	Die dem Publisher übergeordnete Organisation, die für das Dataset inhaltlich verantwortlich ist. Inkl. Name, URL, Anzahl publizierter Datasets (i.e. package_count).
name	Sprachunabhängiger Term, der für die API-Abfrage genutzt werden kann.
accrual_periodicity	Angabe, wie häufig das Dataset aktualisiert wird. Kontrolliertes Vokabular gemäss Standard von data.europa.eu.
resources	Eine Auflistung der Ressourcen, die zum Dataset gehören. Darin finden sich auch die entsprechenden Metadaten zu den Ressourcen.

Übersicht Angaben Ressourcen-Ebene
Key	Value
package_id	Die ID des Datasets, zu dem die Ressourcen gehören.
issued	Das Erstelldatum der Ressource.
id	Die ID der Ressource.
download_url	Die Adresse, unter der die Ressource heruntergeladen werden kann.
media-type	Der Medientyp der Ressource.
format	Das Format der Ressource.
rights	Die Nutzungsbedingungen der Ressource.
created	Der Zeitpunkt, als die Ressource in der Datenbank eingerichtet wurde.
description	Die Beschreibung der Ressource.
num_resources	Die Anzahl Ressourcen für das Dataset.

Terminologie von CKAN in opendata.swiss

Über die API können Sie nach sämtlichen Metadaten in opendata.swiss suchen. Die Suchsyntax entspricht Apache Lucene, da opendata.swiss auf CKAN basiert und Apache Solr als Suchmaschine benutzt. Dies ist ebenfalls in der CKAN-Dokumentation ausführlich beschrieben. Arbeiten Sie mit Metadaten der Organisation, Metadaten der Datasets oder Metadaten der Ressourcen? Beachten Sie dabei die Ebenen: Die folgende Auflistung zeigt die wichtigsten Terminologien, mit welchen Sie Informationen in opendata.swiss finden können:

organization: Entspricht der datenpublizierenden Organisation. Jedes Dataset wird von genau einer Organisation publiziert. Eine Organisation kann jedoch Unterorganisationen haben.
package, dataset: Entspricht einem Dataset bei opendata.swiss. Damit gemeint sind die Metadaten zu einem Bündel von Ressourcen.
id: Entspricht in der Regel dem Slug des Datasets oder der Organisation auf opendata.swiss. Bei Ausnahmefällen konsultieren Sie bitte die CKAN-Dokumentation.
resource, distribution: Entspricht einer Ressource bei Opendata.swiss. Die Plattform opendata.swiss hostet selbst keine Datasets oder Ressourcen, stellt aber downloadUrls oder accesssUrls und teilweise auch Daten Previews zur Verfügung. Ressourcen in CKAN entsprechen dcat:Distribution im DCAT AP Standard .
group: Entspricht einer Kategorie bei opendata.swiss. Ein Dataset kann mehreren Kategorien angehören. Entspricht dcat:theme im DCAT AP Standard.

Anwendungsbeispiele für die API

Typische Abfragen für Datennutzende

status_show

organization_list

package_list

package_search, fq, organization

package_show, id

package_search, language

group_list

facet_field

sort=relevance+asc

Typische Anwendungen für Datenpublizierende

packet_search, organization, dataset_type

packet_search, -harvest_source_id, organization

packet_search, harvest_source_id

POST

Wenn Sie über die entsprechenden Rechte verfügen, können Sie die Metadaten Ihrer Datasets auch über die API-Schnittstelle anpassen. Sie finden Ihren API-Key auf der Nutzerseite auf dem Backend von opendata.swiss. Die genaue Syntax ist u.a. von Ihrem spezifischen Betriebssystem abhängig (beispielsweise das richtige Format der Anführungszeichen)

Senden (POST) über die API Schnittstelle: 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""}"

Datasets können auch über die API neu erstellt werden. Dazu benötigen Sie Ihren API-Key und müssen die Metadaten als im JSON-Format übermitteln.

Senden (POST) über die API Schnittstelle: package_create

{
'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',
        }],
}

Bitte beachten Sie, dass die Nutzungsbedingungen auf Ebene der Ressource dem kontrollierten Vokabular entsprechen. Vgl. Sie dazu den DCAT AP CH Standard.

Zusätzlich werden die Angaben private und isopen benötigt. Mit private können Sie definieren, ob das Dataset direkt veröffentlicht wird. Ein Dataset mit private : False wird direkt auf dem Frontend publiziert. Mit isopen deklarieren Sie, ob die Nutzungsbedingungen der Definition von open gemäss der Open Knowledge Foundation entspricht.

Fetch-API

Es ist auch möglich, über Fetch-API auf opendata.swiss zuzugreifen.

Support

Noch Fragen?

Haben Sie noch Fragen zur Nutzung unserer API? Dann nehmen Sie mit uns Kontakt auf. Bei Rückfragen zu einzelnen Datasets wenden Sie sich bitte direkt an die Datenpublizierenden. Die jeweiligen Kontaktangaben finden Sie im Dataset unter Zusätzliche Information.

Haben Sie ein interessantes Nutzungsbeispiel? Wir würden uns sehr freuen, davon zu erfahren und Ihr Projekt in unsere Showcases aufzunehmen. Oder Schreiben Sie uns.