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]{
"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)
}
}
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!
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.
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. |
| 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
}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)
}
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=xxxValid 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.:
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/"
}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. | () |
{
"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)
}
}
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/)