DKAN API - HowTo
Wie benutzt man die DKAN API
Über das Portal ist es nicht nur möglich sich Datensätze anzuschauen und herunterzuladen. Man kann ausgewählte Datensätze auch direkt über URL ansprechen und so, programmgesteuert, mit diesen arbeiten. Grundsätzlich funktioniert dies über eine API (Programmierschnittstelle), die lesenden Zugriff auf Portalinhalte ermöglicht. Im Folgenden werden die DKAN API, die sich in drei i Blöcke gliedert, nämlich (1) die Dataset API, (2) die Datastore API und (3) die DCAT-AP.de API und deren Möglichkeiten veranschaulicht.
1. DKAN Dataset API
Diese API bezieht sich auf das Portal und dessen Inhalte im Allgemeinen. So ist es möglich, den Zustand des Portals auszulesen bis hin zu einer Ausgabe aller
vorhandenen Datensätze. Zu erreichen sind die einzelnen Funktionen unter http://offenedaten-koeln.de/api/3/action/{Name der Funktion} wobei {Name der Funktion} mit einer der unten gelisteten Funktionen zu besetzen ist. Die Ausgabe erfolgt immer im json Format.
Funktion site_read
Beschreibung: Zeigt an, ob das Portal grundsätzlich erreichbar ist
Beispielaufruf: http://offenedaten-koeln.de/api/3/action/site_read
Rückgabetyp: Boolean
Funktion package_list
Beschreibung: Liefert eine Liste mit allen Datensatz Containern (Dataset)
Beispielaufruf: http://offenedaten-koeln.de/api/3/action/package_list
Rückgabetyp: List of Dictionaries
Funktion current_package_list_with_ressources
Beschreibung: Liefert eine Liste mit allen Datensatz Containern (Dataset) und den beinhaltenden Dateien (Ressourcen)
Beispielaufruf: http://offenedaten-koeln.de/api/3/action/current_package_list_with_resources
Rückgabetyp: List of Dictionaries
Funktion package_show
Beschreibung: Liefert die Metadaten eines Datasets und dessen Ressourcen
Parameter: id
Beispielaufruf: http://offenedaten-koeln.de/api/3/action/package_show?id=vornamen
Rückgabetyp: Dictionary
Funktion resource_show
Beschreibung: Liefert die Metadaten einer Ressource
Parameter: id
Beispielaufruf: http://offenedaten-koeln.de/api/3/action/resource_show?id=99fb632a-bb8f-4139-807f-78f284e9c4a6
Rückgabetyp: Dictionary
Funktion group_list
Beschreibung: Liefert die Namen der angelegten Gruppen (Beteiligte)
Beispielaufruf: http://offenedaten-koeln.de/api/3/action/group_list
Rückgabetyp: List of strings
Funktion group_package_show
Beschreibung: Liefert alle Datasets und Ressourcen einer Gruppe (Beteiligte)
Beispielaufruf: http://offenedaten-koeln.de/api/3/action/group_package_show?id=cbb1845a-1277-49a8-835c-b7316e566408
Rückgabetyp: List of Dictionaries
2. DKAN Datastore API
Diese API bezieht sich auf Datensätze, die von uns in den internen Datastore geladen wurden. Der Datastore bietet die Möglichkeit, (zurzeit nur CSV) Dateien in einem json Format aufrufbar zu machen. Dies ermöglicht das direkte arbeiten mit den einzelnen Ressourcen, ohne diese herunterladen zu müssen. Die einzelnen Dateien können nach folgendem Schema aufgerufen werden http://offenedaten-koeln.de/api/action/datastore/search.json?resource_id={ID der Ressource}. Zurzeit werden Ressourcen, bei denen ein Datastore Zugriff möglich ist über den Button "Data API" innerhalb der Ressourcenansicht angezeigt. Hier wird auch ein Beispiel-Link mit der jeweiligen Ressourcen ID dargestellt. Sukzessive werden Verlinkungen zur Json Darstellung der Ressource auch in der Hauptansicht (Dataset) angezeigt werden, um eine bessere Sichtbarkeit zu erreichen. Folgende Beispiele beziehen sich auf die Ressource Vornamen 2014 http://offenedaten-koeln.de/dataset/4b35bd42-a198-4a5a-b48b-9ba5be441833/resource/4b35bd42-a198-4a5a-b48b-9ba5be441833 des Datensatzes Vornamen http://offenedaten-koeln.de/dataset/vornamen
Parameter: limit
Beschreibung: Beschränkt die Ausgabe auf die angegebene Anzahl der Treffer. Standardmäßig werden 100 Treffer zurückgegeben, dieser Wert kann über den Parameter limit erweitert oder eingegrenzt werden. Es wird gerade bei größeren Dateien empfohlen eine Ausgabe von 100 Treffern nicht zu überschreiten sondern bei Bedarf an weiteren Treffern den Parameter offset zu benutzen.
Beispielaufruf: http://offenedaten-koeln.de/api/action/datastore/search.json?resource_id=4b35bd42-a198-4a5a-b48b-9ba5be441833&limit=10
Rückgabetyp: Dictionary
Parameter: offset
Beschreibung: Beschreibt den Versatz an Treffern => die nächsten {n} Treffer.
Beispielaufruf: http://offenedaten-koeln.de/api/action/datastore/search.json?resource_id=4b35bd42-a198-4a5a-b48b-9ba5be441833&offset=10
Rückgabetyp: Dictionary
Parameter: fields
Beschreibung: Komma separierte Zeichenketten. Schränkt die Ausgabe auf die gewünschten Felder ein.
Beispielaufruf: http://offenedaten-koeln.de/api/action/datastore/search.json?resource_id=4b35bd42-a198-4a5a-b48b-9ba5be441833&fields=vorname,anzahl
Parameter: filters
Beschreibung: Konditionen, die man auf Felder anwenden kann, um die Trefferliste geeignet einzuschränken
Beispielaufruf: http://offenedaten-koeln.de/api/action/datastore/search.json?resource_id=4b35bd42-a198-4a5a-b48b-9ba5be441833&filters[vorname]=Paul,Anna
Parameter: query
Beschreibung: Sucht nach dem gelisteten Feld in der Ressource
Beispielaufruf: http://offenedaten-koeln.de/api/action/datastore/search.json?resource_id=4b35bd42-a198-4a5a-b48b-9ba5be441833&query=Maria
Parameter: sort
Beschreibung: Rückgabe der Daten in Auf- oder Absteigender Sortierung, entsprechend der gewählten Sortier-Eigenschaft d.h. Field nach dem sortiert werden soll.
Beispielaufruf: http://offenedaten-koeln.de/api/action/datastore/search.json?resource_id=4b35bd42-a198-4a5a-b48b-9ba5be441833&sort[vorname]=desc
Hinweis: alle Parameter sind untereinander kombinierbar.
Z.B.: Die ersten 10 weiblichen Vornamen, wobei nur die Felder Vorname und Anzahl ausgegeben werden sollen =>
3. DCAT-AP.de API
Seit 2018 dient DCAT-AP.de als offizieller Metadatenstandard zum Austausch von offenen Verwaltungsdaten. Die Spezifikationen des Metadatenmodells können hier https://www.dcat-ap.de/def/ eingesehen werden.
Über die DCAT-AP.de - API Können die Metadaten des gesamten Datenkatalog des Portals nach dem DCAT-AP.de-Modell Standard im RDF Format als .xml, sowie die Metadaten einzelner Datensätze im RDF als .xml,. JSON als. json und Turtle als .ttl Format abgerufen werden.
Abruf des gesamten Open Data-Katalogs der Stadt Köln im RDF – Format als xml-Datei
Beispielaufruf: https://offenedaten-koeln.de/dcatapde.xml
Rückgabetyp: Metadaten des Kompletten Open Data-Katalog der Stadt Köln, inklusive der Metadaten aller Datasets und ihrer Ressourcen im RDF- Format.
Abruf einzelner Datasets im RDF, JSON oder TTL -Format
Die Metadaten der einzelnen Datensätze im DCAT-AP.de Standard können nach folgendem Schema https://offenedaten-koeln.de/dcatapde/dataset.{File-Format}?dct:identifier={Identifier des Datasets} in den Formaten RDF als .xml, JSON als .json und Turtle als .ttl abgerufen werden.
Beschreibung: Liefert die Metadaten eines Datasets und dessen Ressourcen
Format: RDF als.xml, JSON als .json, Turtle als .ttl
Parameter: dct:identifier
Beispielaufrufe:
http://offenedaten-koeln.de/dcatapde/dataset.xml?dct:identifier=4064ce61-48ae-46c4-a81b-0ec019349279
http://offenedaten-koeln.de/dcatapde/dataset.json?dct:identifier=4064ce61-48ae-46c4-a81b-0ec019349279
http://offenedaten-koeln.de/dcatapde/dataset.ttl?dct:identifier=4064ce61-48ae-46c4-a81b-0ec019349279
Rückgabetyp: Dictionary
Neuen Kommentar schreiben