What is transcriptiones?

(This text exists in English only)

Why an API?

transcriptiones lets you search for documents and view their transcription. But what if you want to download a bunch of transcriptions in a certain format and use it in your research?

That's where the transcriptiones Application Programming Interface comes into play. With a set of simple commands you can search and download our database. The request results are in JSON format and the transcription exports are TEI or plain text.

All examples in this documentation can be pasted to any command line application. Alternatively you can paste only the URL to the address bar of your favourite internet browser.

Example (Request the document list):

curl -X GET https://transcriptiones.ch/api/v1/documents/?auth=[AuthenticationCode]
Example Result (First page of the document list):
{
    "request": {
        "api": "transcriptiones API",
        "documentation": "https://transcriptiones.ch/api/documentation/",
        "api-version": "v1",
        "requested-at": "2022-01-25 15:52:11"
    },
    "num-results": 456,
    "num-pages": 46,
    "page": 1,
    "result-list": [
        {
            "id": 2794,
            "url": "https://transcriptiones.ch/display/institutions/staatsarchiv-basel/stabs-b3-456/grundungsurkunde-xyz/",
            "api-request": "/api/v1/documents/2794/",
            "name": "Gr├╝ndungsurkunde XYZ"
        },
        {
            "id": 2823,
            "url": "https://transcriptiones.ch/display/institutions/klosterarchiv-einsiedeln/ein-67-43526/weinumgelt-1654/",
            "api-request": "/api/v1/documents/2823/",
            "name": "Winumgelt 1654"
        },
        [...] (8 results skipped in this example)
    }
}
This page documents the API and the supported commands



Before You Start

For all requests you need to provide an authentication key. You pass it with the auth=KEY parameter. If you have a transcriptiones login you'll find the key on your Profile Page. It might not exist yet, but you can always generate one. A key is valid for a month. In this period you can request data from the API without any limitations. After this period you need to renew your key on your profile.

Don't have a login? Create one!



Command Structure

Versions

Currently there is only one version. Its identifier is v1. We might want to adapt our API in the future but we don't want to break existing scripts. Future versions will thus have a different identifier while the old versions will stay available.

In all following examples, replace <VERSION> with v1.


Request A List

You can request a list of a certain type which returns a paginated result of the found objects. You can filter the result by adding parameters.

Command structure:

curl -X GET https://transcriptiones.ch/api/<VERSION>/<TYPE>/?auth=xxx&<PARAM>=value

The <TYPE> specifies the object type you want to query. The possibilities are: institutions (archives, libraries and similar institutions which hold documents), refnumbers (reference numbers of document collections), sourcetypes (the type of a document, e. g.: poetry / scientific writings), scribes (people who have written the source documents) and documents (actual transcribed documents).

There are several <PARAM> filters which can be applied. The following table shows what the parameters mean and to which <TYPE> they can be applied.

<PARAM>/<TYPE> institutions refnumbers sourcetypes scribes documents
auth=<api-key>
You need an API Key to access the API. Get it from your profile page or create a login if you don't have one.
page=<num>
Returns the specified page number or an error if out of bounds.
query=<search_term>
Ignores cases and returns results containing the query.

(Institution name)

(Reference title)

(Source type name [en])

(Scribe name)

(Document title)
institution=<id>
Only returns objects held in this institution.
refnumber=<id>
Only returns objects of this reference number.
sourcetype=<id>
Only returns objects of this sourcetype.
level=<top|bottom>
Source types are in a 2-level hierarchy which you can filter by.
user=<username>
Only returns objects by this user.
Valid examples to retrieve lists are:
Example Returns
curl -X GET https://transcriptiones.ch/api/v1/institutions/?auth=xxx Returns the first page of a list of all institutions.
curl -X GET https://transcriptiones.ch/api/v1/refnumbers/?auth=xxx&page=3 Returns the third page (results 21-30) of a list of all reference numbers.
curl -X GET https://transcriptiones.ch/api/v1/sourcetypes/?auth=xxx&level=top Returns the first level of the Source type hierarchy.
curl -X GET https://transcriptiones.ch/api/v1/scribes/?auth=xxx&query=jane Returns a list of scribes which hve "Jane" in their name.
curl -X GET https://transcriptiones.ch/api/v1/documents/?auth=xxx&query=letter&institution=1&sourcetype=3 Returns the first page of a list of documents which have 'letter' in their title, belong to the institution with ID '1' and are of the source type with ID '3'.

All answers to list requests retrieve a JSON string as a result. The JSON has the following format:

{
    "request": {...},         <-- Information about the request and the API version
    "num-results": 456,       <-- Number of hits
    "num-pages": 46,          <-- Number of pages (10 results per page)
    "page": 1,                <-- Current page
    "result-list": [...]      <-- Actual list with max 10 results on a page
}
The result list objects depend on the requested list (for details see below).


Request An Object

You can request an object of a certain type. Objects are called by their respective id.

Command structure:

curl -X GET https://transcriptiones.ch/api/<VERSION>/<TYPE>/<ID>/?auth=xxx

The <TYPE> specifies the object type you want to query. The possibilities are: institutions (archives, libraries and similar institutions which hold documents), refnumbers (reference numbers of document collections), sourcetypes (the type of a document, e. g.: poetry / scientific writings), scribes (people who have written the source documents) and documents (actual transcribed documents).

The <ID> is the identification number of an object.

Valid examples to retrieve objects are:

Example Returns
curl -X GET https://transcriptiones.ch/api/v1/institutions/123/?auth=xxx Returns the institution with ID 123.
curl -X GET https://transcriptiones.ch/api/v1/documents/234/?auth=xxx Returns the document with ID 234.

All answers to object requests retrieve a JSON string as a result. The JSON has the following format:

{
    "request": {...},          <-- Information about the request and the API version
    "type": "document",        <-- Type of the object
    "id": 456,                 <-- Id of the object
    "url": "https://trans...", <-- URL to the object on transcriptiones.ch
    "page": 1,                 <-- Current page
    "details": {...}           <-- Object details (see below)
}
The result list objects depend on the requested list (for details see below).


Request An Export

For documents, the transcription can be downloaded by supplying the document id and the export type. <EXPORT> can be tei or plain.

Command structure:

curl -X GET https://transcriptiones.ch/api/<VERSION>/documents/<ID>/<EXPORT>/?auth=xxx

Valid examples to retrieve document transcriptions are:

Example Returns
curl -X GET https://transcriptiones.ch/api/v1/documents/123/tei/ Returns the transcription of the document with ID 123 in TEI xml format.
curl -X GET https://transcriptiones.ch/api/v1/documents/234/plain/ Returns the transcription of the document with ID 234 in plain text format.

The TEI transcriptions follow the TEI standard. Plain text is returned in utf-8 encoding.:



Object List Details

If you request a list of objects, the returned string is always a JSON-String containing some basic information about the request (API version, # of results, # of pages, current page). It also contains a list with the key "result-list". This is a list of objects which describe single results. Depending on the type of object, the data varies slightly. Refer to the following table to see which type of object contains which information.

institutions refnumbers sourcetypes scribes documents
id Unique identifier of object
parent_id Unique identifier of parent object (returns None if no parent obect exists)
url URL to the transcriptiones page of this object
name Name or title of this object
api-request API request to get the detail object

Example for a document list object:

{
    "id": 2794,
    "name": "Document Title",
    "url": "https://transcriptiones.ch/display/institutions/institution-name/refnumber-name/document-title/",
    "api-request": "https://transcriptiones.ch/api/v1/documents/2794/"
}



Object Details

The object detail requests return a JSON string containing information about a single object. At transcriptiones, objects are organized in a hierarchy. You'll get information about the objects in the level below. For institutions you'll get a list of reference numbers, for reference numbers you'll get a list of documents. For source types you'll get a list of source type children if it is a top-level element or a list of documents if it is a bottom-level element. For scribes you'll get a list of documents.

institutions refnumbers sourcetypes scribes documents
id Unique identifier of object
name Name or title of this object
url URL to the transcriptiones page of this object
refnumber-ids A list of reference number-ids.
document-ids A list of document ids. ()
children A list of source type children. ()

The Document Object
The document object is different from the rest. These objects contain actual meta information about the source and are thus more detailed. The following examples shows the structure.

{
    "request": "{...}",                     <-- request info (the same for all requests)
    "id": <id>,                             <-- id of the document
    "name": <name-of-the-document>,         <-- name (=title) of the document
    "url": <url-to-the-document>,           <-- URL to the document on transcriptiones.ch

    "doc-meta-data": {                      <-- Meta data for the digital document
        "version": 1,                       <-- Version number of the document
        "created": "2022-02-02 22:22:22"    <-- Creation time of this version
        "transcript": {
            "tei": "...",                   <-- api-request to get the TEI transcript
            "plain": "..."                  <-- api-request to get the plain text transcript
        }
    },

    "source-meta-data": {                   <-- Meta data for the physical document
        "source-type": {                    <-- All documents have a source type. All source types are organized in two levels
            "first-level": {
                "id": 1,
                "name": "Poetry",
                "api-request": "..."        <-- api-request to get source type details
            },
            "second-level": {
                "id": 21,
                "name": "Epic",
                "api-request": "..."
            }
        },
        "pages": {
            "number": 12,                   <-- Number of pages in this source
            "paging-system": "Pagination"   <-- How are the pages numbered: (Pagination, Foliated)
        },
        "date": {                           <-- When the document was written (or dated).
            "start": {                      <-- Start of the dating timespan
                "date": "1622-11-01",
                "precision": "MONTH"        <-- Precision of date (DAY, MONTH, YEAR)
            },
            "end": {                        <-- End of the dating timespan. Optional.
                "date": "1623-01-01",
                "precision": "YEAR"
            }
        },
        "illuminated": False,               <-- Does the source have illuminations? (Boolean)
        "has-seal": True,                   <-- Does the source have a seal? (Boolean)
        "measurements": {                   <-- Measurements of book or page(s)
            "width": "10",
            "height": "20",
            "unit": "cm"                    <-- What unit are the measurements in: cm (static)
        },
        "material": "Parchment",            <-- On what material is the document written (Paper, Parchment, Papyrus)
        "languages": ["German"],            <-- Which languages are used (controlled vocabulary)
        "location": "Basel",                <-- Where the document was written (uncontrolled vocabulary)
        "scribes": ["Jane Doe"]             <-- Who wrote the document (semi-controlled vocabulary)
    }
}



Error Handling

If you make an invalid API request you'll get an error message. Error messages are plain text and always start with TRANSCRIPTIONES API ERROR:. Invalid parameters (e. g.: as ?sourcetype=2 on an /institutions/ request) are ignored and do not produce an error. Empty results (e. g. from the ?query parameter) do not produce an error. However, requesting details for an object which does not exist, does produce an error.

Error Explanation
Invalid version You supplied an invalid version identifier after /api/. Currently, only "v1" is a valid version.
Invalid Request You supplied an invalid request identifier after /api/v1/. Currently, institutions, refnumbers, sourcetypes, scribes and documents are valid identifiers.
Invalid Authentication You supplied an invalid key for the auth parameter.
Expired Authentication You supplied an expired key for the auth parameter.
No Authentication You didn't supply the auth parameter.
Object does not exist There is no object with the requested ID in the object type you have requested.
Error 404: Page Not Found If your request is not in the format /api/<version>/<request>/ or /api/<version>/<request>/<identifier>/ you'll get an ERROR 404.

Example error message:

TRANSCRIPTIONES API ERROR: Invalid Request
 Valid Command Structure: /<version>/<request>/?param=value
           Error Details: <request> must be one of: [institutions, refnumbers, sourcetypes, documents, scribes]


---
(Get more Information about the TRANSCRIPTIONES API: https://transcriptiones.ch/api/documentation/)