Retrieving data using the API

The IM-SAFE Knowledge Base is based on the open source software of MediaWiki en SemanticMediaWiki. These provide an open API for retrieving data in realtime, using open standards such as http and Json. For a full description of the features and in-depth manual on how to use the API, please refer to the MediaWiki API documentation and SemanticMediaWiki API documentation respectively. Below is a summary and an example.

Request syntax

To retrieve semantic data from the IM-SAFE Knowledge Base, use the ask module of the API. The basic request syntax is as follows:

https://imsafe.wikixl.nl/api.php?action=ask&query=abcd

To define the subset of data to retrieve, use the query url-parameter. Analyse the Knowledge model to determine the semantic paths defining your selection criteria, and then specify the query conditions accordingly, using the SemanticMediaWiki query documentation. For example, to select all case studies relating to civil engineeering works in Portugal, the internal SMW query selector would be:

[[Category:Case studies]][[Relates to civil engineering work.Located in country::Portugal]], and correspondingly the (html encoded) API call will be:

https://imsafe.wikixl.nl/api.php?action=ask&query=%5B%5BCategory:Case%20studies%5D%5D%5B%5BRelates%20to%20civil%20engineering%20work.Located%20in%20country::Portugal%5D%5D

To specify which properties of the selected pages the API should return, use the printouts specifier from the SemanticMediaWiki query language. The names of the available properties can be found in the Knowledge model. Property chaining is allowed. For example, to retrieve the author name and organisation of the Portugese case studies, the internal SMW printouts specifier would be:

|?Created by|?Created by.From organisation, and correspondingly the (html encoded) API call will be:

https://imsafe.wikixl.nl/api.php?action=ask&query=%5B%5BCategory:Case%20studies%5D%5D%5B%5BRelates%20to%20civil%20engineering%20work.Located%20in%20country::Portugal%5D%5D%7C%3FCreated%20by%7C%3FCreated%20by.From%20organisation

Additionally, you may provide other parameters such as result sorting criteria and result limits.

Tip: You may want to experiment on the IM-SAFE Knowledge Base query playground to construct and test your query before translating it into an API call.

Response syntax

The result set is returned in json format. Printed below is the response for the above query for Portugese case studies:

{
    "query": {
        "printrequests": [
            {
                "label": "",
                "key": "",
                "redi": "",
                "typeid": "_wpg",
                "mode": 2
            },
            {
                "label": "Created by",
                "key": "Created_by",
                "redi": "",
                "typeid": "_wpg",
                "mode": 1,
                "format": ""
            },
            {
                "label": "From organisation",
                "key": "From_organisation",
                "redi": "",
                "typeid": "_wpg",
                "mode": 4,
                "format": "",
                "chain": "Created by.From organisation"
            }
        ],
        "results": {
            "Leziria bridge (case study)": {
                "printouts": {
                    "Created by": [
                        {
                            "fulltext": "Frida Liljefors",
                            "fullurl": "https://imsafe.wikixl.nl/index.php/Frida_Liljefors",
                            "namespace": 0,
                            "exists": "1",
                            "displaytitle": ""
                        }
                    ],
                    "From organisation": [
                        {
                            "fulltext": "Norwegian University Of Science And Technology",
                            "fullurl": "https://imsafe.wikixl.nl/index.php/Norwegian_University_Of_Science_And_Technology",
                            "namespace": 0,
                            "exists": "1",
                            "displaytitle": ""
                        }
                    ]
                },
                "fulltext": "Leziria bridge (case study)",
                "fullurl": "https://imsafe.wikixl.nl/index.php/Leziria_bridge_(case_study)",
                "namespace": 0,
                "exists": "1",
                "displaytitle": ""
            }
        },
        "serializer": "SMW\\Serializers\\QueryResultSerializer",
        "version": 2,
        "meta": {
            "hash": "0904adb4af161aa0fc4e336200295c53",
            "count": 1,
            "offset": 0,
            "source": "",
            "time": "0.031894"
        }
    }
}