Fetching Tours

This use case is about searching and retrieving Tours from the KG.

🚧

V1 is deprecated, please use V2

Version 1 of this endpoitn is deprecated, please use V2. The difference in calling the API is minor (the /v1 needs to be replaced with /v2). The changes in the response concern the quantity and nesting-depth of the properties. While V1 was responding with all properties of an object, V2 will only respond with the @id, @type and ds:compliesWith property. The actual data lookup needs to happen in a second step over the endpoint to retrieve an entity by id: https://changelog-dzt-kg.readme.io/reference/getthingbyid.

The relevant domain specifications are

• DZT Trails https://semantify.it/ds/nBTyKDsKX
• DZT D-Route https://semantify.it/ds/NiVlbxbkD

Fetching Objects belonging to the DZT Trails DS

This is a first start to call the simple Search API using the filterDs query parameter.

In addition, we use X-HOP:1parameter to limit the response data to only direct property value pairs and use page-size:10to limit the results for 10 objects max per page.

cURL

curl --location 'https://proxy.opendatagermany.io/api/ts/v2/kg/things?filterDs=https%3A%2F%2Fsemantify.it%2Fds%2FnBTyKDsKX' \
--header 'Accept: application/json' \
--header 'x-api-key:  API_KEY' \
--header 'X-HOP: 1'\
--header 'page-size: 10'\
--header 'page: 1'

The response should look similar to this one.

The metaDatafield contains information about the total number of Trails (e.g. 5341), some pagination information and how many results per DS can be expected ( here, we used only one filter domain specification).

The datafield then contains the actual information of the first 10 results. Each data item has a @id which is the identifier of the node in the graph, and a couple of datatype and objects properties - data type properties are for example the description, the keywords or the name. Object properties are imags with their @id. For those object properties one can do another lookup to retrieve the information ( see user guide for retrieving objects)

{
    "metaData": {
        "dsCount": {
            "https://semantify.it/ds/nBTyKDsKX": {
                "count": "5341",
                "name": {
                    "de": "Tour"
                }
            }
        },
        "page-size": 10,
        "sortSeed": "b2b53627-1a83-461a-9856-6bf84cf80752",
        "total": 5341,
        "current-page": 1
    },
    "data": [
        {
            #JSON LD representation of the first query result object
        }, ......

The same can be done for the DZT D-Route DS, eithe rby adding the filterDs or changing the filterDs.

Querying for DZT Trails

The next use case is to query for Trails using one or more filters. To do so, we are using the Shape Query API

Search by certain type of Trail

Here we use a shape query that restrict the results to the specific domain specification (see ds:compliesWith) and which have the value "Wandern" in german for the property odta:typeOfTrail

cURL

curl --location 'https://proxy.opendatagermany.io/api/ts/v2/kg/things' \
--header 'Content-Type: application/ld+json' \
--header 'x-api-key: API_KEY' \
--header 'page-size: 10' \
--header 'X-hop: 1' \
--data-raw '{
    "@context": {
        "ds": "https://vocab.sti2.at/ds/",
        "schema": "https://schema.org/",
        "odta": "https://odta.io/voc/",
        "sq": "http://www.onlim.com/shapequery/",
        "@vocab": "http://www.onlim.com/shapequery/",
        "onlim": "http://onlim.com/schema/",
        "query": {
            "@container": "@set"
        }
    },
    "sq:query": [
        {
            "ds:compliesWith": {
                "sq:value": "https://semantify.it/ds/nBTyKDsKX",
                "sq:datatype": "iri"
            },
            "odta:typeOfTrail":{
                "sq:value":"Wandern",
                "sq:lang":"de",
                "sq:datatype":"langString"
            }
        }
    ],
    "sq:select": []
}'