Introduction
The goal of this API is to connect different partner projects working on the Antiquity.
How to use this API
This API has three ways to return data, by default it will return JSON responses with the IDs of related texts. You can however make the API return a URI or XML-formatted response
JSON responses
This is the default way for the API to return data. You can find the API endpoint at the TexRelations section of our Data Services. Unless you provide it with an ID, the response is:
{
"message": "No search string given, please provide valid search parameters.",
"more info": "You can find the documentation at https://www.trismegistos.org/dataservices/texrelations/documentation"
}
You can provide IDs by adding a number to the URL; e.g. https://www.trismegistos.org/dataservices/texrelations/9.
This search parameter will look for all partner IDs that are related to the TM ID: 9
The provided response is:
[
{
"TM_ID": [
"9"
]
},
{
"EDB": null
},
{
"EDH": null
},
{
"EDCS": null
},
{
"EDR": null
},
{
"HE": null
},
{
"UOXF": null
},
{
"RIB": null
},
{
"PHI": null
},
{
"LUPA": null
},
{
"ISic": null
},
{
"IRT": null
},
{
"IGCyR": null
},
{
"Orient": null
},
{
"cisp": null
},
{
"DeM": null
},
{
"PSI": null
},
{
"PapNav-Duke": null
},
{
"Lexicological_lep": null
},
{
"Berliner_papyri": null
},
{
"Bremen_papyri": null
},
{
"chartes": null
},
{
"HispEpOl": null
},
{
"NaBuCCo": null
},
{
"Ashmolion_latin_inscriptions": null
},
{
"PUG": null
},
{
"IIP": null
},
{
"Dresden_papyri": null
},
{
"GVCYR": null
},
{
"Vindolanda": null
},
{
"Ghent_papyri": null
},
{
"Köln_papyri": null
},
{
"DDBDP": [
"p.adl.;;9"
]
},
{
"HGV": [
"9a",
"9b"
]
},
{
"CACHKaRN": null
},
{
"PapNav-Stanford": null
},
{
"PapNav-Fordham": null
},
{
"PapNav-Berenike": null
},
{
"PapNav-Oslo": null
},
{
"PapNav-Toronto": null
},
{
"PapNav-Lund": null
},
{
"PapNav-Hermitage": null
},
{
"PapNav-Wisconsin": null
},
{
"PapNav-UTS": null
},
{
"PapNav-UPenn": null
},
{
"PSR": null
},
{
"PTS": null
},
{
"PapNav-Perkins": null
},
{
"PapNav-Petra": null
},
{
"PapNav-Princeton": null
},
{
"Achemenet": null
},
{
"tir": null
},
{
"DaSi": null
},
{
"¨PetRaE": null
},
{
"DBMNT": null
},
{
"BritishMuseum-Ostraca": null
},
{
"BritishMuseum-Papyri": null
},
{
"PNCOL": null
},
{
"PapPal": null
},
{
"PapNav-SAC": null
},
{
"PapNav-Pull": null
},
{
"Runenprojekt_Kiel": null
},
{
"Penn_Museum": null
},
{
"SAAO": null
},
{
"CDLI": null
},
{
"OCIANA": null
}
]
In the above response you can find all three different datatypes:
- null: the partner in the key has no ID related to your requested TM ID
- string: the partner has only one ID related to your requested TM ID
- array: the partner has multiple IDs related to your requested TM ID
In both cases of the above, there was only one TM ID that matched the requested ID. There are however cases where the ID of a parnter can be matched against multiple TM IDs. In this case the API provides only the found TM IDs and a warning as the last key-value pair. This happens when a partner has 1 ID for multiple texts; whereas Trismegistos holds multiple IDs (one per text.). This was a conscious choice to prevent false matches with partners who follow the same or another strategy.
You can see this example for id rom.mil.rec;1;78 from source ddbdp; the API-call for this record is:
https://www.trismegistos.org/dataservices/texrelations/rom.mil.rec;1;78?source=ddbdp.
The response given by this source consists of two parts. Firstly it provides all related Trismegistos IDs under the TM key. The second part is a warning message explaining why this may occur.
URI responses
URI (Uniform Resource Identifier) responses are returned by modifying the API call to https://www.trismegistos.org/dataservices/texrelations/uri/, followed by the same way you would perform a request to the default-endpoint. The returned data is a JSON object, which has the same properties as the JSON object returned by the default-endpoint.
XML responses
The API supports XML responses by querying the endpoint at https://www.trismegistos.org/dataservices/texrelations/xml. Unlike the URI and JSON responses this methode does not return 'null' values. Each item that matches your request is presented as the child of a Trismegistos ID. Example:
<tmid id="93">
<link cp="DDBDP">p.lond;3;1206</link>
<link cp="HGV">93</link>
</tmid>
In this case the Trismegistos ID 93 has two children, one where the source is DDBDP and one where the source is HGV. If there are multiple children of a given TM ID from one source, then each child is presented separately. Example:
<tmid id="745515">
<link cp="EDCS">67200274</link>
<link cp="EDCS">67300005</link>
</tmid>
Fair use of this API
++
Complete list of covered projects
Notes
1) LSA remark: Searching for an LSA resource requires the use of a padded integer; so to find the records related to LSA-23, the searchvalue needs to be: LSA-0023. The total length of the padded integer needs to be 4, so IDs starting from 1000 and up won't need padding.
Word of thanks
Special thanks goes to Pietro Liuzzo who hosted a eXist-db solution during the development of the Trismegistos TexRelations API and gave access to his XML files.
We also wish to thank our partner projects for providing open access to their data and the entire Trismegistos team for adding new matches to this database on a daily basis.
Report mistakes & bug reports.
Thank you for taking the time to report bugs or mistakes. To help us fix the issue please provide the following details:
- Your web browser.
- Your API-call.
- The error message you got.