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.
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.
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:
teiHeader//respStmt
notiert.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
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"
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.
s (Personen/Institutionen)
Durchsucht den Datenbestand nach dem angegebenen Korrespondenzpartner – erstmal unabhängig von dessen Rolle (d.h. als Absender oder Empfänger).
Mögliche WerteVollständige URI aus einem der folgenden Normdatenbestände:
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.
s=http://d-nb.info/gnd/118540238
s=http://d-nb.info/gnd/118540238::sent
p (Ort)
Schreib- oder Empfangsort
Mögliche WerteAngegeben 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.
p=http://www.geonames.org/2879139
p=http://www.geonames.org/2879139::sent
d (Datum)
Zeitraum.
Mögliche WerteDatumsangabe 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).
d=1792-10-01-1793-07-31
d=1792-1793
d=1793-12-05
o (Beruf)
Suche nach Briefen anhand des Berufs der Korrespondent:innen.
Mögliche WerteDie URI des Berufs aus Wikidata, z.B. http://www.wikidata.org/entity/Q115785313
.
o=http://www.wikidata.org/entity/Q115785313
e (Edition/Publikation)
Suche nach einer bestimmten Edition / Publikation.
Mögliche WerteUUID einer Edition oder Publikation. Die UUID findet sich in der
CMIF-Datei in sourceDesc/bibl/@xml:id
.
e=h74acf70-b928-4a2a-9b90-292877b22bab
c (CMIF-Datei)
Suche nach einer bestimmten CMIF-Datei anhand ihrer URL.
Mögliche WerteURL einer CMIF-Datei. Diese ist stets auch in der CMIF-Datei selbst
in publicationStmt/idno[@type=“url“]
notiert.
c=https://gams.uni-graz.at/context:hsa/CMIF
a (Verfügbarkeit)
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.
a=online
x (Paginierung)
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.
Ganzzahl, 1-n. Standardmäßig 1
.
x=5
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
.
Das JavaScript-Widget csLink weist zu einem edierten Brief in der eigenen digitalen Edition auf zeitlich benachbarte Briefe der Korrespondenzpartner aus anderen Editionen hin.
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.