GeoRelations Matcher API Documentation

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 places. 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 GeoRelations Matcher 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/georelations/documentation/"
}
                

You can provide IDs by adding a number to the URL; e.g. https://www.trismegistos.org/dataservices/georelations/49. This search parameter will look for all partner IDs that are related to the Trismegistos Geo ID: 49. (It is important to note that not all IDs present in the Geo database have a relation to one or more partners. In such cases, the ID is not present in the API.) The provided response is:

[
    {
        "TM_Geo": [
            "49"
        ]
    },
    {
        "Syriaca": [
            "7",
            "715",
            "2298"
        ]
    },
    {
        "DASI": [
            "346"
        ]
    },
    {
        "Wikipedia": [
            "Egypt_(Roman_province)"
        ]
    },
    {
        "Wikisource": null
    },
    {
        "DARE": null
    },
    {
        "Lexicon_Leponticum": null
    },
    {
        "Pleiades": [
            "981503",
            "766"
        ]
    },
    {
        "GeoNames": [
            "357994"
        ]
    },
    {
        "Talbert_Peutinger": [
            "3160"
        ]
    },
    {
        "RIB": null
    },
    {
        "Livius": null
    },
    {
        "FayumTex": null
    },
    {
        "FayumMap": null
    },
    {
        "Wikivoyage": null
    },
    {
        "VICI": null
    },
    {
        "RFO": 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 Trismegistos Geo ID
• string: the partner has only one ID related to your requested Trismegistos Geo ID
• array: the partner has multiple IDs related to your requested Trismegistos Geo ID

In both cases of the above, there was only one Trismegistos ID that matched the requested ID. There are however cases where the ID of a partner can be matched against multiple Trismegistos IDs. In this case the API provides only the found Trismegistos IDs and a warning as the last key-value pair. This happens when a partner has one ID for multiple places; whereas Trismegistos holds multiple IDs (1 per place). 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 413341 from source pleiades; the API call for this record is: https://www.trismegistos.org/dataservices/georelations/413341?source=pleiades.

The response given by this source consists of two parts. Firstly it provides all related Trismegistos Geo IDs under the TM key. The second part is a warning message explaining why this response may occur.

[
 {
   "TM": [
	"42466",
	"41819"
   ]
 },
 {
   "WARNING": "There are 2 Trismegistos IDs matching your search query. Those IDs are more precise than your requested IDs",
   "YOU CAN": "either perform a new API call with all or some of these IDs or use this data to provide a warning yourself."
 }
]
			    

URI responses

URI (Uniform Resource Identifier) responses are returned by modifying the API-call to https://www.trismegistos.org/dataservices/matchmakegeomatcher/uri/, followed by the same way you'd 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/matchmaker/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 Geo ID (tm_geo). Example: https://www.trismegistos.org/dataservices/georelations/xml/49

In this case the Trismegistos Geo ID 49 has multiple children, of which three belong to the Syriaca project. Every child of a given Trismegistos Geo ID is presented on its own, this is also true for multiple children coming from the same source. Example:

<TM_Geo id="49">
  <link cp="Syriaca">7</link>
  <link cp="Syriaca">715</link>
  <link cp="Syriaca">2298</link>
  <link cp="DASI">346</link>
  <link cp="Wikipedia">Egypt_(Roman_province)</link>
  <link cp="Pleiades">981503</link>
  <link cp="Pleiades">766</link>
  <link cp="GeoNames">357994</link>
  <link cp="Talbert_Peutinger">3160</link>
</tmid>
                

Fair use of this API

++

Complete list of covered projects

Word of thanks

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