DKAN API - How To
Wie benutzt man die DKAN API
Datensätze können über das Open Data Portal nicht nur angeschaut und heruntergeladen werden. Ausgewählte Datensätze können auch direkt über eine URL angesprochen werden. Grundsätzlich funktioniert dies über eine API (Programmierschnittstelle), die lesenden Zugriff auf die Portalinhalte ermöglicht. Im Folgenden werden die API und ihre Möglichkeiten veranschaulicht.
Die gesamte DKAN-API-Dokumentation ist unter https://dkan.readthedocs.io/en/latest/apis/index.html abrufbar.
1. Dataset API
Die Dataset API hat Bezug auf Inhalte des Portals im Allgemeinen. So ist es möglich, den Zustand des Portals auszulesen und eine Ausgabe aller vorhandenen Datensätze zu erzeugen. Die einzelnen Funktionen sind unter https://opendata.essen.de/api/3/action/{Funktion} zu erreichen. {Funktion} ist dabei ein Platzhalter der nachfolgend aufgeführten Funktionen. Die Ausgabe erfolgt immer im JSON Format.
Funktion current_package_list_with_ressources
Beschreibung: Liefert eine Liste mit allen Datensatz Containern (Dataset) und den beinhaltenden Dateien (Ressourcen).
Beispielaufruf: https://opendata.essen.de/api/3/action/current_package_list_with_resources
Rückgabetyp: List of Dictionaries
Funktion group_list
Beschreibung: Liefert die Namen der angelegten Gruppen (Beteiligte).
Beispielaufruf: https://opendata.essen.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: https://opendata.essen.de/api/3/action/group_package_show?id=cbb1845a-1277-49a8-835c-b7316e566408
Rückgabetyp: List of Dictionaries
Funktion package_list
Beschreibung: Liefert eine Liste mit allen Datensatz Containern (Dataset).
Beispielaufruf: https://opendata.essen.de/api/3/action/package_list
Rückgabetyp: List of Dictionaries
Funktion package_show
Beschreibung: Liefert die Metadaten eines Datasets und dessen Ressourcen.
Parameter: id
Beispielaufruf: https://opendata.essen.de/api/3/action/package_show?id=vornamen
Rückgabetyp: Dictionary
Funktion resource_show
Beschreibung: Liefert die Metadaten einer Ressource.
Parameter: id
Beispielaufruf: https://opendata.essen.de/api/3/action/resource_show?id=99fb632a-bb8f-4139-807f-78f284e9c4a6
Rückgabetyp: Dictionary
Funktion site_read
Beschreibung: Zeigt an, ob das Portal grundsätzlich erreichbar ist.
Beispielaufruf: https://opendata.essen.de/api/3/action/site_read
Rückgabetyp: Boolean
2. Datastore API
Diese API bezieht sich auf Datensätze, die von uns in den internen Datastore geladen wurden. Der Datastore bietet die Möglichkeit, (derzeit 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:
https://opendata.essen.de/api/action/datastore/search.json?resource_id={RessourceID}.
Derzeit 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. Folgende Beispiele beziehen sich auf die Ressource Lebendgeburten in den Stadtteilen ab 2007 https://opendata.essen.de/dataset/lebendgeburten/resource/ccdaf8d2-aa91-4f47-b4ed-2d00d7eb8a4d#{} des Datensatzes Lebendgeburten https://opendata.essen.de/dataset/lebendgeburten
Parameter: filters
Beschreibung: Konditionen, die man auf Felder anwenden kann, um die Trefferliste geeignet einzuschränken.
Beispielaufruf: https://opendata.essen.de/api/action/datastore/search.json?resource_id=ccdaf8d2-aa91-4f47-b4ed-2d00d7eb8a4d&filters[Stadtteil]=Kray,Werden
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: https://opendata.essen.de/api/action/datastore/search.json?resource_id=ccdaf8d2-aa91-4f47-b4ed-2d00d7eb8a4d&limit=10
Rückgabetyp: Dictionary
Parameter: offset
Beschreibung: Beschreibt den Versatz an Treffern => die nächsten {n} Treffer.
Beispielaufruf: https://opendata.essen.de/api/action/datastore/search.json?resource_id=ccdaf8d2-aa91-4f47-b4ed-2d00d7eb8a4d&offset=10
Rückgabetyp: Dictionary
Parameter: query
Beschreibung: Sucht nach dem gelisteten Feld in der Ressource.
Beispielaufruf: https://opendata.essen.de/api/action/datastore/search.json?resource_id=ccdaf8d2-aa91-4f47-b4ed-2d00d7eb8a4d&query=2014
Hinweis: Alle Parameter sind miteinander kombinierbar.