API-Nutzung

OpenData.HRO verfügt neben der intuitiven Web-Oberfläche über eine umfassende Programmierschnittstelle (API), mit der alle Funktionen der zugrundeliegenden Open-Source-Software CKAN genutzt werden können – sei es das Suchen von Datensätzen, das Anzeigen von Metadaten (beschreibenden Informationen) eines bestimmten Datensatzes, die Filterung des Inhaltes von Ressourcen oder die Verknüpfung von Ressourcen.

Die API nutzt sowohl als Eingabe- als auch als Ausgabeformatierung JSON. Ein beispielhafter Aufruf der API (Beispiel: Anzeigen des Datensatzes apotheken) lautet: https://www.opendata-hro.de/api/action/package_show?id=apotheken.

Eine vollständige Übersicht zur Programmierschnittstelle findet sich in der Dokumentation von CKAN.

Datensätze suchen und deren Metadaten anzeigen

https://www.opendata-hro.de/api/action/package_search?q=apothek

Wenn obige URL aufgerufen wird, werden Datensätze gesucht, die auf den Suchbegriff apothek passen. Es werden dabei diverse Metadatenfelder durchsucht und falls ähnliche Begriffe gefunden werden, gelten diese ebenfalls als Treffer.

Hat man die ID des gesuchten Datensatzes unter den Treffern identifiziert, können nun die Informationen in diesem Datensatabgerufen werden. Dazu kann folgende URL aufgerufen werden, wobei der letzte Teil der ID des Datensatzes entspricht:

https://www.opendata-hro.de/api/action/package_show?id=652e7b9e-5bb2-4a7e-aeff-12421d3c32a5.

Ein verkürztes Ergebnis dieses Aufrufes könnte folgendermaßen aussehen:

{ help: […], success: true, result: { id: "652e7b9e-5bb2-4a7e-aeff-12421d3c32a5", name: "apotheken", title: "Apotheken", maintainer: "Hansestadt Rostock – Kataster-, Vermessungs- und Liegenschaftsamt", maintainer_email: "geodienste@rostock.de", […] resources: [ { id: "0c2c4996-afad-4ebe-9a3d-a3a7d7047a4d", name: "Apotheken", url: "https://geo.sv.rostock.de/download/opendata/apotheken/apotheken.csv", format: "CSV", mimetype: "text/x-comma-separated-values", size: "18081", hash: "sha256:e056f7335e2ee420d9485a86c3924b54fff27a2e7edeb4bdd5f6278e8d41ddd6", […] }, […] ], […] tags: [ { id: "fbf2dd06-001b-4788-bd98-168a6df82bd3", name: "Arzneimittel", […] }, […] ], […] groups: [ { id: "08b0e154-77d7-440f-ab7b-70511004a405", name: "gesundheit", title: "Gesundheit", […] }, […] ], […] }

Die Antwort ist sehr umfangreich und sollte während der ersten Abfragen ausführlich analysiert werden. Die wichtigsten Informationen aus dem obigen (verkürzten) Resultat sind:

  • Es existiert eine Ressource im Dateiformat CSV, die unter https://geo.sv.rostock.de/download/opendata/apotheken/apotheken.csv erreichbar ist. Sie ist 18081 Bytes groß. Wichtig bei einer Datei-Ressource ist insbesondere deren Hash-Wert, der genutzt werden kann, um die Integrität der Datei zu prüfen.
  • Die Tags (Schlüsselbegriffe), die diesem Datensatz zugeordnet sind, sind vor allem für die Suche interessant.
  • Der Datensatz ist unter anderem der Gruppe (Kategorie) 08b0e154-77d7-440f-ab7b-70511004a405 zugeordnet. Eine Liste aller Datensätze sowie weitere Informationen zu einer Gruppe (Kategorie) können entweder über die Web-Oberfläche oder ebenfalls über die API abgerufen werden: https://www.opendata-hro.de/api/action/group_show?id=08b0e154-77d7-440f-ab7b-70511004a405
  • Der Datensatz verfügt zudem über eine Beschreibung mit zusätzlichen Hinweisen wie dem Aktualisierungsintervall oder Informationen über den Inhalt der Ressourcen.

Filterung des Inhaltes von Ressourcen und Verknüpfung von Ressourcen

Insbesondere auf mobilen Geräten oder in Bereichen, in denen nur eine geringe Datentransferrate zur Verfügung steht, ist es von Vorteil, wenn nicht die kompletten Ressourcen heruntergeladen werden müssen, sondern lediglich der in der aktuellen Situation interessante Ausschnitt. Diese Funktion des Filterns wird durch den CKAN-DataStore bereitgestellt, der jedoch nur für ausgewählte Ressourcen verfügbar ist. Um zu prüfen, ob der DataStore für eine Ressource aktiv ist, kann – neben der Detailansicht der Ressource in der Web-Oberfläche – vor allem die API mit der zu prüfenden ID der Ressource aufgerufen werden, beispielsweise für die Ressource mit der ID 290cdf3c-33eb-44a8-963e-65a0ee140a45: https://www.opendata-hro.de/api/action/datastore_search?resource_id=290cdf3c-33eb-44a8-963e-65a0ee140a45. Die Antwort enthält entweder die Fehlermeldung, dass die Ressource nicht gefunden wurde, oder aber den kompletten Inhalt des DataStore für diese Ressource.

Ist der DataStore für eine Ressource aktiviert, so können nun entweder mit der bereits gezeigten Funktion datastore_search einfachere Operationen oder mit der Funktion datastore_search_sql umfangreiche Operationen wie etwa SQL-Abfragen durchgeführt werden. Wichtig ist bei den SQL-Abfragen, dass explizit alle Spalten angegeben werden, die im Resultat angezeigt werden sollen, da es ansonsten zu Fehlern kommen kann.

Ein einfaches Beispiel für eine Verknüpfung zweier Datensätze anhand der räumlichen Lage und eine gleichzeitige Filterung des Inhaltes ebenfalls nach der räumlichen Lage könnte wie folgt aussehen:

SELECT bezeichnung, strasse_name, hausnummer, hausnummer_zusatz FROM "0c2c4996-afad-4ebe-9a3d-a3a7d7047a4d" WHERE ST_Within(ST_Transform(geometrie,25833),ST_Buffer(ST_Transform((SELECT geometrie FROM "e614d725-4fad-4447-820d-4475ca55cff5" WHERE bezeichnung = 'Deutsche Med'),25833),300))

Dieses Kommando kann über die API folgendermaßen aufgerufen werden:

https://www.opendata-hro.de/api/action/datastore_search_sql?sql=SELECT bezeichnung, strasse_name, hausnummer, hausnummer_zusatz FROM "0c2c4996-afad-4ebe-9a3d-a3a7d7047a4d" WHERE ST_Within(ST_Transform(geometrie,25833),ST_Buffer(ST_Transform((SELECT geometrie FROM "e614d725-4fad-4447-820d-4475ca55cff5" WHERE bezeichnung = 'Deutsche Med'),25833),300))

Eine ausführliche Beschreibung der DataStore-API ist zu finden in der Dokumentation von CKAN.