Grundlegende Funktionen der Geolinker-API

Die histHub-Geolinker-API ist ein Service, der geographische Einheiten mit Links anreichern kann. Wird dem Service die URL der Einheit gesendet, kann er diese über verschiedene Wege mit den in histHub existierenden Ressourcen verbinden. Die resultierenden Links können in Websites implementiert werden und so die dort existierenden Daten erweitern.

Mitmachen

Um den histHub-Geolinker zu verwenden, müssen gewisse Basisinformationen über die zu bearbeitenden geographischen Daten im histHub-System via Webcrawlers oder Streams erfasst werden. Folgende Voraussetzungen sind essentiell, damit der Service funktioniert:

  • Die Daten müssen unter einer freien Lizenz stehen.
  • Sie müssen jeweils über eine unique URL verfügen.
  • Es muss eine Sitemap der Daten zur Verfügung gestellt werden.
  • Es müssen strukturierte Informationen über Name und Geokoordinaten vorliegen.
  • Weitere Informationen, zum Beispiel Ortstypen, helfen die Präzision zu verbessern.

Neben diesen Grundvoraussetzungen wird folgendes empfohlen, dass die Daten strukturiert via API zur Verfügung gestellt werden.

Verarbeitung

Nach der Erfassung der Daten werden sie dem histHub-Format angepasst. Die mehrfach transformierten Daten werden in mehreren „Data Lakes“ gespeichert. Von dort aus werden sie mit verschiedenen Services bearbeitet, um gleiche oder ähnliche Ressourcen in der histHub-Datenbank zu finden.


Daten abrufen

Um Daten aus dem Geolinker abzurufen stellen wir zwei Endpoints zur Verfügung:

Sameas:

Der Sameas-Endpoint kann manuell oder halb-manuell verbundene Entitäten aus dem histHub-Geolinker abrufen. Solche qualitativ hochwertigen Links wurden mehrheitlich durch Menschen generiert und im Geolinker gespeichert. Dieser Datensatz enthält Links unserer Partner und solche zu anderen Services wie Geonames oder Wikidata, die wir generiert haben. Im entsprechenden Datastore ist jeder Link als Pfeil zwischen zwei Knotenpunkten (Nodes) repräsentiert. E.g. URI1 (Projekt A) <-> URI2 (Projekt B). Die API ermöglicht nur das Abrufen dieser First-Level-Links, das heisst von und zu einer URI.

Beispiel:

„Bern“ ist in Dodis die URL https://dodis.ch/G43 zugewiesen.

Die Anfrage

https://api.geolinker.histhub.ch/v2/sameas/https://dodis.ch/G43

wird fünf verlinkte Entitäten (Linked Entities) abrufen, die manuell generiert wurden. Eine davon ist „Bern“ in Geonames http://geonames.org/2661552.

Wenn der Geolinker nach den Linked Entities von „Bern“ in Geonames

https://api.geolinker.histhub.ch/v2/sameas/http://geonames.org/2661552

gefragt wird, resultiert nur der Link zu Dodis, weil dieser der einzige ist, der manuell generiert wurde.

In anderen Szenarien ist es nützlicher, eine Liste mit allen verbundenen Einheiten zu erhalten, beispielsweise alle Links für „Bern“. Über den Tiefenparameter in der API kann definiert werden, wie viele Beziehungen passiert werden können, um verlinkte Entitäten zu finden. Je tiefer dabei ins Netzwerk eingedrungen wird, desto unschärfer werden die Links.

Beispiel:

Geolinker wird nach Entitäten verlinkt mit dem Geoname „Uri“ gefragt.

https://api.geolinker.histhub.ch/v2/sameas/http://geonames.org/266155.

Diese Abfrage ergibt ein Resultat. Wenn nun auch die Links von Dodis abgerufen werden sollen, muss tiefer in die verknüpften Ressourcen vorgedrungen werden.

Durch die Anfrage

https://api.geolinker.histhub.ch/v2/sameas/http://geonames.org

/2661552?depth=2

erhalten wir alle mit der Entität des Geonames verknüpften Links (1) und alle Links die mit den Entities verknüpft sind, die wiederum mit dem Geoname verknüpft sind (2). Unter diesen Links ist jener von Dodis und es resultieren schliesslich fünf verknüpfte Nodes.

Similarto

Während die Sameas-API stabile Verbindungen, die manuell oder halbmanuell generiert wurden, abfragen kann, findet der Similarto-Service Ressourcen, die vollautomatisch verbunden sind, basierend auf verschiedenen Ähnlichkeitskriterien. Ähnlichkeit wird durch die geographische Distanz (10km) zum Ursprungsort und der Ähnlichkeit des Namens definiert. Abhängig von der Konfiguration der Anfrage können unterschiedliche Resultate erreicht werden. Die API kann nach Ressourcen mit demselben Namen in einem festgelegten Bereich um den spezifizierten Node abgefragt werden.

Beispiel:

Über „Kaiping“ https://dodis.ch/G300 sollen mehr Informationen gesammelt werden. Der Geolinker liefert keine Sameas-Resultate zu „Kaiping“. Aber es könnten ähnliche Einheiten über 

https://api.geolinker.histhub.ch/v2/similarto/https://dodis.ch/G300

gefunden werden.

Diese Abfrage ergibt zwei Geonames, einer ist mit dem Tag „city“ versehen und der andere mit „third administrative division“, sodass beide als verschiedene Einheiten/Entitäten gewertet werden müssen.

Um mehr Kontrolle über die Resultate zu gewinnen, kann der Suchbereich und der Grad der Unschärfe angepasst werden. Mit dem Parameter „distance“ kann der Radius der Geolinker-Suche eingestellt werden (Distanz<0). Die Einheit ist dabei immer Meter und muss nicht angegeben werden. Der Parameter „fuzziness“ kontrolliert die Unschärfe im Namen der Entität, die gesucht wird.

https://api.geolinker.histhub.ch/v2

/similarto/https://dodis.ch/G300?distance=5000&fuzziness=2