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 oder die Filterung des Inhaltes von Ressourcen und die Verknüpfung von Ressourcen.

Die API nutzt sowohl als Eingabe- als auch als Ausgabeformatierung JSON. Es gibt drei verschiedene Versionen der API, die durch anhängen der Ziffern 1, 2 oder 3 an die URL des API-Aufrufs angesprochen werden können. Aktuell sollte Version 2 oder 3 verwendet werden. Wird an die URL keine Ziffer angehängt, so wird automatisch Version 1 angesprochen. Die URL für den Aufruf der API-Version 2 lautet https://www.opendata-hro.de/api/2.

Eine ausführliche, allerdings englischsprachige Beschreibung der Programmierschnittstelle ist zu finden in der Dokumentation von CKAN.

Suchen von Datensätzen und Anzeigen von Metadaten

Suchen von Datensätzen mit dem Suchbegriff bibliotheken: https://www.opendata-hro.de/api/2/search/dataset?q=bibliotheken

Beim Aufrufen der obigen URL werden Datensätze gesucht, die den Suchbegriff enthalten. Das Resultat enthält alle passenden Datensätze, die gefunden wurden. Wie folgt könnte nun eine Antwort zu der obigen Anfrage aussehen:

{
    count: 1,
    results: 
    [
        "0bd49d5f-cd42-44a9-8938-75173fe07b17"
    ]
}

Es wurde ein Datensatz mit der ID 0bd49d5f-cd42-44a9-8938-75173fe07b17 gefunden. Mit Hilfe der ID ist es nun möglich die Metadaten des Datensatzes anzuzeigen: https://www.opendata-hro.de/api/2/rest/dataset/0bd49d5f-cd42-44a9-8938-75173fe07b17

Ein (verkürztes) Resultat könnte dann folgendermaßen aussehen:

{
    id: "0bd49d5f-cd42-44a9-8938-75173fe07b17",
    license_id: "cc-zero",
    author_email: "geodienste@rostock.de",
    [...]
    resources:
    [
        {
            id: "290cdf3c-33eb-44a8-963e-65a0ee140a45",
            size: "16507",
            last_modified: "2016-03-02T15:01:37",
            hash: "sha256:3acb6d9431130e871c9d6b62aaf8008c777b4e6c2c4f61124c7de718ad72167f",
            format: "CSV",
            mimetype: "text/x-comma-separated-values",
            url: "https://geo.sv.rostock.de/download/opendata/bibliotheken/bibliotheken.csv",
            [...]
        }
        [...]
    ],
    tags:
    [
        "Bildung",
        "Kultur",
        [...]
    ],
    groups:
    [
        "64260234-43cf-4879-be3d-d3021e2ab2ac",
        "0801bc56-f5fc-4094-9446-c261af444955"
    ],
    name: "bibliotheken",
    title: "Bibliotheken",
    [...]
}

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:

  • Der Datensatz unterliegt der gemeinfreien Lizenz Creative Commons 1.0 Public Domain Dedication.
  • Es existiert eine Ressource im Dateiformat CSV, die unter https://geo.sv.rostock.de/download/opendata/bibliotheken/bibliotheken.csv erreichbar ist. Sie wurde zuletzt am 02.03.2016 aktualisiert und ist 16507 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 den beiden Kategorien 64260234-43cf-4879-be3d-d3021e2ab2ac und 0801bc56-f5fc-4094-9446-c261af444955 zugeordnet. Eine Liste aller Datensätze sowie weitere Informationen zu einer Kategorie können entweder über die Web-Oberfläche oder ebenfalls über die API abgerufen werden: https://www.opendata-hro.de/api/2/rest/group/64260234-43cf-4879-be3d-d3021e2ab2ac.
  • 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 in der Version 3 mit der zu prüfenden ID der Ressource aufgerufen werden, beispielsweise für die Ressource 290cdf3c-33eb-44a8-963e-65a0ee140a45: https://www.opendata-hro.de/api/3/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/3/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, allerdings englischsprachige Beschreibung der DataStore-API ist zu finden in der Dokumentation von CKAN.