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.2 zur Verfügung.

Ausgabeformate

TEI-XML (stabil)

Basis-URL: https://correspSearch.net/api/v1.2/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:

  • 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/@source, dessen Wert auf sourceDesc/bibl/@xml:id verweist.
  • Die im Sinne der CC-BY-Lizenz 4.0 zu nennenden Datenersteller werden im teiHeader//respStmt notiert.

Beispielabfrage: https://correspSearch.net/api/v1.2/tei-xml.xql?correspondent=http://d-nb.info/gnd/118540238&startdate=1793-01-01&enddate=1808-02-02

TEI-JSON (beta)

Basis-URL: https://correspSearch.net/api/v1.2/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: https://correspSearch.net/api/v1.2/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 https://correspSearch.net/api/v1.2/gnd-beacon.xql
VIAF https://correspSearch.net/api/v1.2/viaf-beacon.xql
BNF https://correspSearch.net/api/v1.2/bnf-beacon.xql
LC https://correspSearch.net/api/v1.2/lc-beacon.xql

Beispiel-Abfrage aller Korrespondenten mit GND-Nummer: https://correspSearch.net/api/v1.2/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: https://correspSearch.net/api/v1.2/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.

Parameter

  • correspondent
    Beschreibung

    Durchsucht den Datenbestand nach dem angegebenen Korrespondenzpartner – unabhängig von dessen Rolle (d.h. als Absender oder Empfänger).

    Mögliche Werte

    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.

    Beispiele

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

    ?correspondent=all

  • sender
    Beschreibung

    Wie correspondent – allerdings nur als Absender

    Mögliche Werte

    Wie correspondent

    Beispiele

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

  • addressee
    Beschreibung

    Wie correspondent – allerdings nur als Empfänger

    Mögliche Werte

    Wie correspondent

    Beispiele

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

  • startdate
    Beschreibung

    Beginn des Suchzeitraums

    Mögliche Werte

    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.

    Beispiele

    ?correspondent=all&startdate=1800-03-01

  • enddate
    Beschreibung

    Ende des Suchzeitraums

    Mögliche Werte

    Wie startdate, nur dass analog der letzte Tag des Monats bzw. des Jahres gesetzt wird.

    Beispiele

    ?correspondent=all&enddate=1800-03-01

  • place
    Beschreibung

    Schreib- oder Empfangsort

    Mögliche Werte

    Angegeben werden muss eine Identifikationsnummer von Geonames.org als vollständige URL.

    Beispiele

    ?correspondent=all&place=http://www.geonames.org/2879139

  • placeSender
    Beschreibung

    Schreibort

    Mögliche Werte

    Wie place

    Beispiele

    ?correspondent=all&placeSender=http://www.geonames.org/2879139

  • placeAddressee
    Beschreibung

    Empfangsort

    Mögliche Werte

    Wie place

    Beispiele

    ?correspondent=all&placeAddressee=http://www.geonames.org/2879139

  • available
    Beschreibung

    Verfügbarkeit des edierten Briefes: online oder gedruckt

    Mögliche Werte

    online, print, [leer]. Wird der Parameter nicht gesetzt oder leer gelassen werden sowohl nur gedruckte als auch online verfügbare Briefe gefunden

    Beispiele

    ?correspondent=all&available=online

  • strictDate
    Beschreibung

    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.

    Mögliche Werte

    false (Standard), true

    Beispiele

    ?correspondent=all&startdate=1800-03-01&enddate=1804-12-31&strictDate=true

Inhaltsverzeichnis

  • Überblick
  • Ausgabeformate
  • Parameter

    • API nutzen mit csLink

    Das JavaScript-Widget csLink weist zu einem edierten Brief in der eigenen digitalen Edition auf zeitlich benachbarte Briefe der Korrespondenzpartner aus anderen Editionen hin.

    Mehr Informationen

    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.