correspSearch API v2

Querying our web service automatically and get machine-readable data

Overview

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.

Output formats for correspondence metadata

General

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").

TEI-XML / CMIF (beta)

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:

  • The data providers to be named in terms of the CC-BY license 4.0 are noted in the teiHeader//respStmt.
  • Since the result is output batch by batch (paginated), the following or preceding page is referenced in 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

TEI-JSON (beta)

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"

CSV (experimental)

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.

Parameters

  • s (Persons / institutions)
    Description

    Searches the dataset for the specified correspondence partner - by default regardless of their role (i.e. as sender or recipient).

    Possible values

    Complete URI from one of the following standards data sets:

    • Gemeinsame Normdatei (GND) of the German National Library.
    • Virtual Authority File (VIAF)
    • Autorités, Bibliothèque nationale de France (BNF)
    • Library of Congress (LC)
    • National Diet Library, Japan (NDL)

    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.

    Examples

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

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

  • p (Place)
    Description

    Place of write or receiving of the letter.

    Possible values

    A 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.

    Examples

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

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

  • d (Date)
    Description

    Period of time to be searched.

    Possible values

    Date 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.

    Examples

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

    d=1792-1793

    d=1793-12-05

  • o (Occupation)
    Description

    Search for letters by the profession of the correspondent.

    Possible values

    The URI of the profession from Wikidata, e.g. http://www.wikidata.org/entity/Q115785313.

    Example

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

  • e (Edition / publication)
    Description

    Search for a specific edition or publication, in which a letter is published.

    Possible values

    UUID of an edition or publication. The UUID can be found in the CMIF file in sourceDesc/bibl/@xml:id.

    Example

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

  • c (CMIF file)
    Description

    Search for a specific CMIF file by its URL.

    Possible values

    URL of a CMIF file. This is always also noted in the CMIF file itself in publicationStmt/idno[@type="url "].

    Example

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

  • a (Availability)
    Description

    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.

    Example

    a=online

  • x (Pagination)
    Description

    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.

    Possible values

    Integer, 1-n. By default 1.

    Example

    x=5

BEACON

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.

Using API with csLink

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.

More information

Licensing of data

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.