GeoResponder

Jump to:

Usage

Make a request

JSON Request

Download JSON file

Processing data

Usage

The Trismegistos GeoResponder is a simple online tool that can be used to gather quick facts about a TM place and display them on your own website or use the data in your own database application. Responses are formatted in a standardized GeoJSON format and can be served as a downloadable file or as parseable JSON.

Make a request

Requests are made based on the Trismegistos Geo ID; this identifying number is the last part of the URIs used on the Geo Portal. As an example we'll use the Egyptian city of Thebes; the URI of this city is: https://www.trismegistos.org/place/2355; so the TM Geo ID is 2355. Providing an ID is crucial for this endpoint to work. If a TM Geo ID is lacking you'll get an error message; if an inexistent ID is used, a notice will be displayed.

JSON Request

By default the response is going to be parseable JSON, making a request is done by appending ?id= followed by the ID to the address of the endpoint. A request for Thebes with the TM Geo ID of 2355 thus looks like: https://www.trismegistos.org/dataservices/georesponder/georesponder.php?id=2355. The server will process your request and send back the formatted JSON as follows: 


{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            25.68502752,
            32.6355912
        ]
    },
    "title": "Thebes",
    "uri": "https://www.trismegistos.org/place/2355",
    "TM_Geo_ID": "2355",
    "properties": {
        "country": "Egypt",
        "provincia": "Aegyptus"
    }
}

Download JSON file

In some cases users may want to download the file directly; the API facilitates this functionality by adding a second parameter to the URL. This parameter is &dl=1. A request to download the JSON file for the city of Thebes thus looks like: https://www.trismegistos.org/dataservices/georesponder/georesponder.php?id=2355&dl=1. When doing this request the JSON-file is downloaded onto the local hard drive of the visiting machine; each downloaded file contains the identifier of the city, prepended by "TM_Geo_" and followed by the file extension ".json". Therefore the name of the downloaded file is: TM_Geo_2355.json. The content of this file is exactly the same as the JSON-response.

Back to top

Processing data

The JSON responses will only send the data back that's available for a given record, this means that you shouldn't expect all keys to be present in every response and that some keys may not be present in the request you modelled your script after. To be on the safe side we recommend you to model your script after the following two IDs, these two contain all the keys that might be returned for any given record:

Data can be processed and used in multiple ways. To include the data on a website one can use and XMLHTTPRequest. There are some excellent tutorials by The Mozilla Foundation and W3C on the web that'll guide you through the process of setting this up.

Other possible uses of this endpoint is to enrich your own database. Software such as FileMaker (versions 16 and up) is natively able to handle JSON endpoints; others not so much. We recommend you to follow the manual/recommendation provided by the vendor of your database application.

Back to top