correspSearch API v2

correspSearch automatisch abfragen und maschinen-lesbare Daten erhalten

Ü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 werden in maschinenlesbaren Formaten ausgegeben und können dabei unter den Bedingungen der Creative-Commons Lizenz CC-BY 4.0 weiter verwendet werden.

Seit dem 30. Oktober 2023 steht die correspSearch-API in der Version 2.0 (derzeit noch Betaphase) zur Verfügung.

Die Dokumentation der veralteten API v1.x findet sich hier.

Ausgabeformate für Briefmetadaten

Allgemeines

Die Briefmetadaten, die über die correspSearch-API ausgegeben werden, sind stellenweise harmonisiert oder angereichert. So ist z.B. die in correspSearch verwendete URI für eine Person in allen Datensätzen gleich und muss daher nicht mehr zwangsläufig mit den ursprünglichen CMIF-Dateien übereinstimmen.

Ab der Version 2.0 der correspSearch-API wird das Suchergebnis aus Performancegründen nur noch abschnittsweise („paginiert“) zu je 100 Treffern ausgegben. Über den Parameter x kann zum nächsten Batch geblättert werden. Die nächste bzw. vorangehende Seite wird bei den Formaten TEI-XML / CMIF und TEI-JSON in notesStmt/relatedItem/@target notiert. In notesStmt/p ist darüber hinaus die Angabe der Trefferanzahl und des gerade ausgegeben Abschnitts (z.B. „101-200“) zu finden.

TEI-XML / CMIF (beta)

Basis-URL: https://correspSearch.net/api/v2.0/tei-xml.xql

Das Briefmetadaten werden als TEI-XML ausgegeben. Die genaue TEI-Kodierung entspricht - bis auf wenige Ausnahmen - dem Correspondence Metadata Interchange-Format (CMIF), was ein sehr reduziertes und restriktives Subset der TEI ist. Mehr Informationen zum CMIF erhalten Sie hier. Es gibt allerdings zwei notwendige Abweichungen vom CMIF:

  • Die im Sinne der CC-BY-Lizenz 4.0 zu nennenden Datenersteller werden im teiHeader//respStmt notiert.
  • Da das Ergebnis abschnittsweise (paginiert) ausgegeben wird, wird in notesStmt/relatedItem auf die nachfolgende bzw. vorhergehende Seite verwiesen.

Beispielabfrage: https://correspSearch.net/api/v2.0/tei-xml.xql?s=http://d-nb.info/gnd/118540238&d=1793-01-01-1808-02-02

TEI-JSON (beta)

Basis-URL: https://correspSearch.net/api/v2.0/tei-json.xql

Das Ergebnis wird als TEI ausgegeben, allerdings im JSON-Format. Dazu wird das TEI-XML (siehe vorangehenden Abschnitt) mit Hilfe des eXistdb-eigenen Serialisierung in JSON umgewandelt. Da das CMI-Format fast gar keine „Mixed Content“-Elemente enthält (d.h. XML-Elemente mit gemischtem Inhalt, also Text und Elemente), entspricht das TEI-JSON weitgehend dem CMIF (nur eben als JSON).

Beispielabfrage: https://correspSearch.net/api/v2.0/tei-json.xql?s=http://d-nb.info/gnd/118540238&d=1793-01-01-1808-02-02"

CSV (experimentell)

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

  • s (Personen/Institutionen)
    Beschreibung

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

    Mögliche Werte

    Vollständige URI 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, indem weitere URIs komma-separiert ergänzt werden. Mehre URIs werden mit dem Operator AND kombiniert. Die URIs können sowohl mit http als auch mit https angegeben werden.

    Sollen die Personen nach Absender und Empfänger unterschieden werden, können URIs mit dem Suffix ::sent bzw. ::received qualifiziert werden.

    Beispiele

    s=http://d-nb.info/gnd/118540238

    s=http://d-nb.info/gnd/118540238::sent

  • p (Ort)
    Beschreibung

    Schreib- oder Empfangsort

    Mögliche Werte

    Angegeben werden muss eine URI aus GeoNames.

    Wie bei Personen/Institutionen kann auch der Ort nach Schreib- bzw. Empfangsort mit dem Suffix ::sent bzw. ::received qualifiziert werden.

    Beispiele

    p=http://www.geonames.org/2879139

    p=http://www.geonames.org/2879139::sent

  • d (Datum)
    Beschreibung

    Zeitraum.

    Mögliche Werte

    Datumsangabe des gesuchten Zeitraums in maschinenlesbarer Form. Am besten wird der Zeitraum im Format JJJJ-MM-TT-JJJJ-MM-TT angegeben. Folgende weitere 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).

    Beispiele

    d=1792-10-01-1793-07-31

    d=1792-1793

    d=1793-12-05

  • o (Beruf)
    Beschreibung

    Suche nach Briefen anhand des Berufs der Korrespondent:innen.

    Mögliche Werte

    Die URI des Berufs aus Wikidata, z.B. http://www.wikidata.org/entity/Q115785313.

    Beispiel

    o=http://www.wikidata.org/entity/Q115785313

  • e (Edition/Publikation)
    Beschreibung

    Suche nach einer bestimmten Edition / Publikation.

    Mögliche Werte

    UUID einer Edition oder Publikation. Die UUID findet sich in der CMIF-Datei in sourceDesc/bibl/@xml:id.

    Beispiel

    e=h74acf70-b928-4a2a-9b90-292877b22bab

  • c (CMIF-Datei)
    Beschreibung

    Suche nach einer bestimmten CMIF-Datei anhand ihrer URL.

    Mögliche Werte

    URL einer CMIF-Datei. Diese ist stets auch in der CMIF-Datei selbst in publicationStmt/idno[@type=“url“] notiert.

    Beispiel

    c=https://gams.uni-graz.at/context:hsa/CMIF

  • a (Verfügbarkeit)
    Beschreibung

    Verfügbarkeit des edierten Briefes: online, gedruckt oder hybrid

    Mögliche Werte

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

    Beispiel

    a=online

  • x (Paginierung)
    Beschreibung

    Gibt die Seite des Ergebnisses an, da die API stets nur 100 Treffer auf einmal liefert. In den Formaten TEI-XML / CMIF sowie TEI-JSON ist die näächste bzw. vorangehende Seite auch in notesStmt/relatedItem angegeben.

    Mögliche Werte

    Ganzzahl, 1-n. Standardmäßig 1.

    Beispiel

    x=5

BEACON

Basis-URL: https://correspSearch.net/api/v2.0/beacon.xql

Neben den APIs für Briefmetadaten bietet correspSearch auch die Möglichkeit 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, der sich via BEACON-Datei zusammensetzen lässt, gelangt der Endnutzer zum jeweiligen Suchergebnis in correspSearch.

Standardmäßig liefert die BEACON-API die GND-IDs der Personen aus. Darüber hinaus können BEACON-Dateien für die von correspSearch unterstützten Normdateien abgerufen werden. Dazu muss die Basis-URL mit dem Parameter authority ergänzt werden, z.B. https://correspsearch.net/api/v2.0/beacon.xql?authority=viaf. Folgende Werte sind möglich: gnd, viaf, bnf, lc, ndl.

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.