Wie benutze ich 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 wird die API, die sich in zwei Blöcke gliedert, und deren Möglichkeiten veranschaulicht.

 

1. 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 https://opendata.gelsenkirchen.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: https://opendata.gelsenkirchen.de/api/3/action/site_read
Rückgabetyp: Boolean

Funktion package_list

Beschreibung: Liefert eine Liste mit allen Datensatz Containern (Dataset).
Beispielaufruf: https://opendata.gelsenkirchen.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: https://opendata.gelsenkirchen.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: https://opendata.gelsenkirchen.de/api/3/action/package_show?id=krankenhaeuser-gelsenkirchen
Rückgabetyp: Dictionary

Funktion resource_show

Beschreibung: Liefert die Metadaten einer Ressource.
Parameter: resource_id
Beispielaufruf: https://opendata.gelsenkirchen.de/api/3/action/resource_show?id=36ee0dc6-4283-417c-86cd-778ab602f0f1
Rückgabetyp: Dictionary

Funktion group_list

Beschreibung: Liefert die Namen der angelegten Gruppen (Beteiligte).
Beispielaufruf: https://opendata.gelsenkirchen.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.gelsenkirchen.de/api/3/action/group_package_show?id=stadt-gelsenkirchen
Rückgabetyp: List of Dictionaries

 

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, (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 https://opendata.gelsenkirchen.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 Mini-Kitas (https://opendata.gelsenkirchen.de/dataset/kindertagespflege-einrichtungen-gelsenkirchen/resource/81c5bb92-b75f-41bb-b544-e12fe158fcdf) des Datensatzes Kindertagespflege (Einrichtungen in Gelsenkirchen) (https://opendata.gelsenkirchen.de/dataset/kindertagespflege-einrichtungen-gelsenkirchen).

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.gelsenkirchen.de/api/action/datastore/search.json?resource_id=81c5bb92-b75f-41bb-b544-e12fe158fcdf&limit=5
Rückgabetyp: Dictionary

Parameter: offset

Beschreibung: Beschreibt den Versatz an Treffern => die nächsten {n} Treffer.
Beispielaufruf: https://opendata.gelsenkirchen.de/api/action/datastore/search.json?resource_id=81c5bb92-b75f-41bb-b544-e12fe158fcdf&offset=5
Rückgabetyp: Dictionary

Parameter: fields

Beschreibung: Komma separierte Zeichenketten. Schränkt die Ausgabe auf die gewünschten Felder ein.
Beispielaufruf: https://opendata.gelsenkirchen.de/api/action/datastore/search.json?resource_id=81c5bb92-b75f-41bb-b544-e12fe158fcdf&fields=id,name
Rückgabetyp: Dictionary

Parameter: filters

Beschreibung: Konditionen, die man auf Felder anwenden kann, um die Trefferliste geeignet einzuschränken.
Beispielaufruf: https://opendata.gelsenkirchen.de/api/action/datastore/search.json?resource_id=81c5bb92-b75f-41bb-b544-e12fe158fcdf&filters[name]=Spielstube
Rückgabetyp: Dictionary

Parameter: query

Beschreibung: Sucht nach dem gelisteten Feld in der Ressource.
Beispielaufruf: https://opendata.gelsenkirchen.de/api/action/datastore/search.json?resource_id=81c5bb92-b75f-41bb-b544-e12fe158fcdf&query=Feldmark
Rückgabetyp: Dictionary

Hinweis: alle Parameter sind untereinander kombinierbar.

z.b.: Die ersten 5 Mini-Kitas, wobei nur die Felder id und Name ausgegeben werden sollen.
https://opendata.gelsenkirchen.de/api/action/datastore/search.json?resource_id=81c5bb92-b75f-41bb-b544-e12fe158fcdf&fields=id,name&limit=5