Application Programming Interface (API)

Querying correspSearch automatically

Overview

With the help of the Application Programming Interface (API), you can query the web service automatically via URL parameters (see below). The results can be used and distributed under the terms of the Creative Commons license CC-BY 4.0.

The correspSearch API (TEI-XML output format) is available in the stable version 1.2.

Output Formats

TEI-XML (stable)

Base URL: https://correspSearch.net/api/v1.2/tei-xml.xql

The correspondence metadata are provided in TEI-XML format. The TEI encoding is generally compliant (apart from two differences) to the Correspondence Metadata Interchange (CMI) format, a highly reduced and restricted subset of the TEI Guidelines. See here for more information about the CMI format. The correspSearch API aggregates letter metadata from different sources which entails two necessary exceptions from the CMI format:

  • Since it is possible that correspDesc elements represent different sources, each correspDesc element has to be linked to the source it refers to. This is done by usage of the attribute correspDesc/@cs:source, the value of which should be the same as sourceDesc/bibl/@xml:id.
  • The names of the data providers, who have to be mentioned due to the CC BY 4.0 license, are encoded in teiHeader//respStmt.

Example query: 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)

Base URL: https://correspSearch.net/api/v1.2/tei-json.xql

The results are provided as TEI data which come in JSON format. For that purpose the TEI-XML data (see preceding section) are serialized with the help of the "exist-db JSON serializer". For more information about this serialization see the respective Blog post in the eXist-db blog. Due to the fact that the CMI format contains hardly any "mixed content" elements (i.e. XML elements with text and elements as children), the TEI-JSON output has a high correlation to the TEI-XML output.

Example query: 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 (stable)

Besides the TEI-API the web service correspSearch offers the possibility to create BEACON files (with the same parameters) for every Authority Controlled Files (e.g. VIAF). Thus it is possible to automatically link to all letters from or to a specific person found in the correspSearch collection. The individual link leads the end user to the corresponding search result in correspSearch.

Authority File Base 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

Example query of all correspondents who have a GND identifier: https://correspSearch.net/api/v1.2/gnd-beacon.xql?correspondent=all

To query the BEACON interface you can use all URL parameters as described below. This, for instance, enables queries that output only Authority Controlled IDs of those persons who have sent or received letters in a specific period.

Please note that the BEACON interface will only return the Authority File IDs of the correspondents as definded by the BEACON format. To retrieve the full correspondence metadata please use the TEI-XML or TEI-JSON interface as described above.

CSV (experimental)

Base URL: https://correspSearch.net/api/v1.2/csv.xql

The correspondence metadata are outputted in the CSV format. The CSV file uses semicolons (;) as dividers and quotes (") as text delimiters. At the end of the CSV file the data publishers are mentioned in coherence with the CC-BY 4.0 license. The CSV interface was designed so that search results from correspSearch could be saved locally on your own computer for further use. The interface uses (among others) a modified version of the XSLT "cmi2csv", developed by Klaus Rettinghaus (SAW Leipzig).

Please note that the table format isn't standardized yet and will be subject to further developments. For machine-readable requests please use the TEI-XML or TEI-JSON interface as described above.

Parameters

  • correspondent
    Description

    Searches the database for the given correspondent regardless of his or her role (i.e. as sender or recipient).

    Possible Values

    Unabridged persistent URL from one of the following sets of standardized data:

    • 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)

    It is possible to select more than one person by using the parameter several times.

    If the search is not restricted to a specific person, the value is set to all.

    Examples

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

    ?correspondent=all

  • sender
    Description

    Same as correspondent but limited to the sender

    Possible Values

    Like correspondent

    Examples

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

  • addressee
    Description

    Same as correspondent but limited to the recipient

    Possible Values

    Like correspondent

    Examples

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

  • startdate
    Description

    Start date of the time period covered by the query

    Possible Values

    Dates in machine-readable form. Possible formats are: JJJJ-MM-TT, JJJJ-MM, JJJJ. Note that due to technical reasons the latter two formats will be mapped to a specific date (i.e. first day of a month/year). Dates may be provided in text form as well. These dates are then automatically mapped to an ISO-date by means of the web service PDR-WS Dates. Up till now, the PDR-WS Dates web service processes German and Italian dates; a recognizer for English dates is currently under development.

    Examples

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

  • enddate
    Description

    End date of the time period covered by the query

    Possible Values

    Same as startdate, except ambiguous dates will be mapped automatically to the last day of the month or year.

    Examples

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

  • place
    Description

    Location where the letter was created or received.

    Possible Values

    Requires an ID number from Geonames.org as an unabridged URL.

    Examples

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

  • placeSender
    Description

    Location where the letter was created.

    Possible Values

    Like place

    Examples

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

  • placeAddressee
    Description

    Location where the letter was received.

    Possible Values

    Like place

    Examples

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

  • available
    Description

    Availability of the published letter: online or printed.

    Possible Values

    Possible parameters are online, print, [leer]. If the parameter is empty or not set then letters from both publication types (digital and print) will be selected.

    Examples

    ?correspondent=all&available=online

  • strictDate
    Description

    Strict date search: letters are retrieved that were created completely within the indicated date span. This is opposed to the default search, which also retrieves letters created only partially within the searched date span.

    Possible Values

    false (Standard), true

    Examples

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

Table of Contents

  • Overview
  • Output Formats
  • Parameters

    • Use our API with csLink

    The JavaScript widget csLink refers from an edited letter in its own digital edition to temporally nearby letters of the correspondence partners from other editions.

    [Download & more Information]

    Licensing of the data

    The data provided via the TEI-XML or the TEI-JSON API is available for subsequent use under the terms of the Creative Commons license CC-BY 4.0.