With the help of the Application Programming Interface (API), you can query automatically the web service correspSearch. The query is done via URL parameters, which are described in detail below. The results are output in machine-readable formats and can be used under the conditions of the Creative Commons license CC-BY 4.0.
As of October 30, 2023, the correspSearch API is available in version 2.0 (currently still in beta).
Looking for the documentation of the deprecated API v1.x? See here.
The output correspondence metadata is in part harmonized or enriched. For example, the URI used in correspSearch for a person is the same in all records and therefore no longer necessarily has to match the one in the original CMIF file.
As of version 2.0 of the correspSearch API, the search result is only
output in batches of 100 hits each for performance reasons ("paginated
API"). The parameter x
can be used to scroll to the
next batch. The next or previous „page“ is noted in notesStmt/relatedItem/@target
for TEI-XML / CMIF and TEI-JSON
formats. In addition, notesStmt/p
contains the
number of hits and the current batch of hits (e.g. "101-200").
Base URL:
https://correspSearch.net/api/v2.0/tei-xml.xql
The letter metadata is output as TEI-XML. The exact TEI encoding corresponds - with a few exceptions - to the Correspondence Metadata Interchange Format (CMIF), which is a very reduced and restrictive subset of the TEI. More information about the CMIF can be found here. However, there are two necessary deviations from CMIF:
teiHeader//respStmt
.notesStmt/relatedItem
.Beispielabfrage: https://correspSearch.net/api/v2.0/tei-xml.xql?s=http://d-nb.info/gnd/118540238&d=1793-01-01-1808-02-02
Base URL:
https://correspSearch.net/api/v2.0/tei-json.xql
The result is output as TEI, but in JSON format. To do this, the TEI XML / CMIF is converted to JSON using eXistdb's serialization. Since the CMIF contains almost no "mixed content" elements (i.e. XML elements with mixed content, i.e. text and elements), the TEI-JSON largely corresponds to the CMIF.
Beispielabfrage: https://correspSearch.net/api/v2.0/tei-json.xql?s=http://d-nb.info/gnd/118540238&d=1793-01-01-1808-02-02"
Base URL:
https://correspSearch.net/api/v2.0/csv.xql
The letter metadata is output as a text table in CSV format. The CSV file uses semicolons (;) as separators and English quotes (") as text delimiters. At the end of the actual letter metadata, the publishers of the metadata are named for licensing reasons. The CSV interface is currently intended primarily for the individual further use of search results on one's own computer. Among other things, the interface uses a modified version of the script "cmi2csv", which was developed by Klaus Rettinghaus.
Please note that the table format is not yet standardized and needs further development. For machine queries, please preferably use the TEI-XML or TEI-JSON interface as described above.
s (Persons / institutions)
Searches the dataset for the specified correspondence partner - by default regardless of their role (i.e. as sender or recipient).
Possible valuesComplete URI from one of the following standards data sets:
Multiple persons can be specified by adding additional
comma-separated URIs. Multiple URIs are combined with the AND
operator. The URIs can be specified with
http
as well as with https
.
If you want to distinguish between sender and recipient, URIs can be
qualified with the suffix ::sent
or ::received
.
s=http://d-nb.info/gnd/118540238
s=http://d-nb.info/gnd/118540238::sent
p (Place)
Place of write or receiving of the letter.
Possible valuesA URI from GeoNames must be specified.
As with people/institutions, places can be qualified by write/send or
receive location with the suffix ::sent
or ::received
.
p=http://www.geonames.org/2879139
p=http://www.geonames.org/2879139::sent
d (Date)
Period of time to be searched.
Possible valuesDate specification of the searched period in machine-readable form.
It is best to specify the period in the format YYYY-MM-DD-YYYY-MM-DD.
The following other formats are
possible: YYYY-MM-DD
, YYYY-MM
, YYYY
, YYYY-YYYY
. However, the last formats are set to an exact
day specification (first day of the month or year) for processing
purposes.
d=1792-10-01-1793-07-31
d=1792-1793
d=1793-12-05
o (Occupation)
Search for letters by the profession of the correspondent.
Possible valuesThe URI of the profession from Wikidata, e.g. http://www.wikidata.org/entity/Q115785313
.
o=http://www.wikidata.org/entity/Q115785313
e (Edition / publication)
Search for a specific edition or publication, in which a letter is published.
Possible valuesUUID of an edition or publication. The UUID can be found in the CMIF
file in sourceDesc/bibl/@xml:id
.
e=h74acf70-b928-4a2a-9b90-292877b22bab
c (CMIF file)
Search for a specific CMIF file by its URL.
Possible valuesURL of a CMIF file. This is always also noted in the CMIF file itself in
publicationStmt/idno[@type="url
"].
c=https://gams.uni-graz.at/context:hsa/CMIF
a (Availability)
Availability of the edited letter: online, printed or hybrid.
Possible values
online
, print
, hybrid
. If the parameter is not set or left
empty, both printed and online available letters will be found.
a=online
x (Pagination)
Specifies the page of the result, since the API always returns only
100 hits at a time. In TEI-XML / CMIF as well as TEI-JSON formats,
the next or previous page is also specified in notesStmt/relatedItem
.
Integer, 1-n. By default 1
.
x=5
Base URL:
https://correspSearch.net/api/v2.0/beacon.xql
Besides the APIs for letter metadata, you can retrieve BEACON files for supported authority files from correspSearch. Through BEACON it is possible to link automatically to all letters from or to a person in correspSearch. Through the single link, which can be assembled via the BEACON file, the end user gets to the respective search result in correspSearch.
By default, the BEACON API delivers the GND IDs of the persons. In addition,
BEACON files can be retrieved for the standards files supported by
correspSearch. For this purpose, the base URL must be supplemented with the
parameter authority
, e.g. https://correspsearch.net/api/v2.0/beacon.xql?authority=viaf
. The
following values are possible: gnd, viaf, bnf, lc, ndl
.
The JavaScript widget csLink points to chronologically related letters of the correspondence partners from other editions for an edited letter in the own digital edition.
The data made available via the TEI-XML or TEI-JSON API can be reused under the terms of the Creative Commons license CC-BY 4.0.