Schnittstelle

correspSearch automatisch abfragen

Überblick

Mit Hilfe der technischen Schnittstelle (Application Programming Interface, API) kann der Webdienst correspSearch automatisiert abgefragt werden. Die Abfrage erfolgt dabei über URL-Parameter, die weiter unten ausführlich beschrieben werden. Die Ergebnisse können dabei unter den Bedingungen der Creative-Commons Lizenz CC-BY 4.0 weiter verwendet werden.

Die correspSearch-API steht im Ausgabe-Format TEI-XML in der stabilen Version 1.0 zur Verfügung.

Ausgabeformate

TEI-XML (stabil)

Basis-URL: http://correspSearch.bbaw.de/api/v1/tei-xml.xql

Das Briefmetadaten werden als TEI-XML ausgegeben. Die genaue TEI-Kodierung entspricht - bis auf wenige Ausnahmen - dem "Correspondence Metadata Interchange"-Format, was ein sehr reduziertes und restriktives Subset der TEI ist. Mehr Informationen zum CMI-Format erhalten Sie hier. Da die correspSearch-API Briefmetadaten aus mehreren Quellen aggregiert ergeben sich allerdings zwei notwendige Abweichungen vom CMI-Format:

  1. Es sind correspDesc-Elemente aus unterschiedlichen Quellen möglich, so dass bei jedem correspDesc-Eintrag auf die entsprechende Quelle verwiesen werden muss. Dies geschieht mit dem Attribut correspDesc/@cs:source, dessen Wert auf sourceDesc/bibl/@xml:id verweist. Das Attribut @source ist in den TEI Richtlinien nicht für die Verwendung in correspDesc vorgesehen, daher muss es in einem eigenen Namensraum notiert werden. Der Namespace für das Namespace-Kürzel "cs" lautet http://www.bbaw.de/telota/correspSearch.
  2. Die im Sinne der CC-BY-Lizenz 4.0 zu nennenden Datenersteller werden im teiHeader//respStmt notiert.

Beispielabfrage: http://correspsearch.bbaw.de/api/v1/tei-xml.xql?correspondent=http://d-nb.info/gnd/118540238&startdate=1793-01-01&enddate=1808-02-02

TEI-JSON (beta)

Basis-URL: http://correspSearch.bbaw.de/api/v1/tei-json.xql

Das Ergebnis wird als TEI ausgegeben, allerdings im JSON-Format. Dazu wird das TEI-XML (siehe vorangehenden Abschnitt) mit Hilfe des "JSON serializer" in JSON umgewandelt. Genauere Informationen zur Serialisierung erhalten Sie im entsprechendem Beitrag im eXistdb-Blog. Da das CMI-Format fast gar keine "Mixed Content"-Elemente enthält (d.h. mit XML-Elemente mit gemischtem Inhalt, also Text und Elemente), entspricht das TEI-JSON sehr stark der TEI-XML-Ausgabe.

Beispielabfrage: http://correspsearch.bbaw.de/api/v1/tei-json.xql?correspondent=http://d-nb.info/gnd/118540238&startdate=1793-01-01&enddate=1808-02-02

BEACON-Format

Neben der TEI-API bietet correspSearch auch die Möglichkeit mit Hilfe derselben Parametern BEACON-Dateien für die unterstützen Normdateien auszugeben. Durch diese Schnittstelle ist es möglich, automatisiert auf alle Briefe von bzw. an eine Person in correspSearch zu verlinken. Durch den einzelnen Link gelangt der Endnutzer zum jeweiligen Suchergebnis in correspSearch.

Normdatei Basis-URL
GND http://correspSearch.bbaw.de/api/v1/gnd-beacon.xql
VIAF http://correspSearch.bbaw.de/api/v1/viaf-beacon.xql
BNF http://correspSearch.bbaw.de/api/v1/bnf-beacon.xql
LC http://correspSearch.bbaw.de/api/v1/lc-beacon.xql

Beispiel-Abfrage aller Korrespondenten mit GND-Nummer: http://correspSearch.bbaw.de/api/v1/gnd-beacon.xql?correspondent=all

Für die Abfrage der BEACON-Schnittstelle können alle unten beschriebenen Parameter benutzt werden, so dass z.B. auch nur Personen-Norm-IDs ausgegeben werden, die in einem bestimmten Zeitraum Briefe, Postkarten etc. geschrieben oder empfangen haben.

Bitte beachten Sie, dass über die BEACON-Schnittstelle nur die Identifier der Korrespondenten (bzw. Sender oder Empfänger) ausgegeben werden – so wie es das BEACON-Format vorsieht. Für den Abruf der kompletten Briefmetadaten nutzen Sie bitte die TEI-XML- oder TEI-JSON-Schnittstelle wie oben beschrieben.

CSV (experimentell)

Basis-URL: http://correspSearch.bbaw.de/api/v1/csv.xql

Die Briefmetadaten werden als Texttabelle im CSV-Format ausgegeben. Die CSV-Datei benutzt als Trennezeichen Semikolons (;) und als Textbegrenzung englische Anführungszeichen ("). Am Ende der eigentlichen Briefmetadaten sind aus lizenzrechtlichen Gründen die Herausgeber der Metadaten genannt. Die CSV-Schnittstelle ist derzeit vor allem für die individuelle Weiternutzung von Suchergebnissen auf dem eigenen Rechner gedacht. Die Schnittstelle verwendet u.a. eine modifizierte Version des Skripts "cmi2csv", das von Klaus Rettinghaus (SAW Leipzig) entwickelt wurde.

Bitte beachten Sie, dass das Tabellenformat noch nicht standardisiert ist und weiter entwickelt werden muss. Für maschinelle Abfragen benutzen Sie bitte vorzugsweise die TEI-XML- oder TEI-JSON-Schnittstelle wie oben beschrieben.

Lizenzierung der Daten

Die über die TEI-XML- oder TEI-JSON-API zur Verfügung gestellten Daten können unter den Bedingungen der Creative-Commons-Lizenz CC-BY 4.0 weiterverwendet werden.

Parameter

Name Beschreibung Mögliche Werte Beispiel(e)
correspondent Durchsucht den Datenbestand nach dem angegebenen Korrespondenzpartner – unabhängig von dessen Rolle (d.h. als Absender oder Empfänger). Vollständige URL aus einem der folgenden Normdatenbestände:
  • Gemeinsame Normdatei (GND) der deutschen Nationalbibliothek
  • Virtual Authority File (VIAF)
  • Autorités, Bibliothèque nationale de France (BNF)
  • Library of Congress (LC)
  • National Diet Library, Japan (NDL)

Angabe von mehreren Personen möglich, in dem der Parameter mehrfach gesetzt wird.

Soll nicht nach einer bestimmten Person gesucht werden, muss der Wert auf all gesetzt werden.

?correspondent=http://d-nb.info/gnd/118540238

?correspondent=all

sender Wie correspondent – allerdings nur als Absender Wie correspondent ?sender=http://d-nb.info/gnd/118540238
addressee Wie correspondent – allerdings nur als Empfänger Wie correspondent ?addressee=http://d-nb.info/gnd/118540238
startdate Beginn des Suchzeitraums Datumsangaben in maschinenlesbarer Form. Folgende Formate sind möglich: JJJJ-MM-TT, JJJJ-MM, JJJJ. Die letzten beiden Formate werden aber zwecks Verarbeitung auf eine genaue Tagesangabe gesetzt (erster Tag des Monats bzw. des Jahres). Datumsangaben in Textform sind auch möglich, da sie über den Webdienst PDR-WS Dates in ein ISO-Datum aufgelöst werden. Es werden Datumsangaben in deutschen, englischen und italienischen Texten erkannt. ?correspondent=all&startdate=1800-03-01
enddate Ende des Suchzeitraums Wie startdate, nur dass analog der letzte Tag des Monats bzw. des Jahres gesetzt wird. ?correspondent=all&enddate=1800-03-01
place Schreib- oder Empfangsort Angegeben werden muss eine Identifikationsnummer von Geonames.org als vollständige URL. ?correspondent=all&place=http://www.geonames.org/2879139
placeSender Schreibort Wie place ?correspondent=all&placeSender=http://www.geonames.org/2879139
placeAddressee Empfangsort Wie place ?correspondent=all&placeAddressee=http://www.geonames.org/2879139
available Verfügbarkeit des edierten Briefes: online oder gedruckt online, print, [leer]. Wird der Parameter nicht gesetzt oder leer gelassen werden sowohl nur gedruckte als auch online verfügbare Briefe gefunden ?correspondent=all&available=online
strictDate Enge Datumssuche: Es werden nur Briefe gefunden, deren Sende- bzw. Empfangszeitraum gänzlich im gesuchten Zeitraum liegt. Normalerweise findet die Suche auch Briefe, die nur teilweise im gesuchten Zeitraum abgesendet oder empfangen wurden. false (Standard), true ?correspondent=all&startdate=1800-03-01&enddate=1804-12-31&strictDate=true