Query API

The platform also offers a client friendly query API that hides the underlying complexity of SPARQL queries.
The API provides a set of useful filter parameters which should support most of the simpler search use cases.
This allows the client to search for things that

  • adhere to a certain shape defined in a domain specification (filterDs and shapeFilterDs parameters),
  • contain a certain keyword in the schema:name property (kw parameter), optionally one can restrict the langague ( inLang header parameter)

The APi also allows to define the output shape the the results by using the projectionDs query parameters that would define which properties are to be returned. By default, the result shapes are defined by the domain specification of the inserted things (using the ds:compliesWith information in the graph) or by the shapeFilterDs if specified.

Brief overview of the most relevant filter values

search by keyword using the kw query parameter which triggers a search for all things that contain the value in the schema:name property.

curl --location --request GET 'https://proxy.opendatagermany.io/api/ts/v1/kg/things?kw=Jena' \
     --header 'Accept: application/json'\ 
     --header 'x-api-key: $API_KEY'
     #optional X-Publisher and X-Datasource

In addition, one can filter in addition by directly using domain specifications

filter for things by a domain specification using one of the following query parameters

  • filterDs search things that have ds:compliesWith statement with the search value
  • shapeFilterDs search things that are contains the mandatory properties of the specified shapeFilter DS
curl --location --request GET 'https://proxy.opendatagermany.io/api/ts/v1/kg/things?filterDs=https://semantify.it/ds/sloejGAwT' \
     --header 'Accept: application/json' \
     --header 'x-api-key: $API_KEY'
     #optional X-Publisher and X-Datasource

Specify the return shape of the things

By default, the results matching the filter specifications are returned according to the shape as defined by the inserted domain specification.
In case, the client uses the shapeFilterDs then the result objects are returned according the shape of the shapeFilterDs.
Please use a projectionDs to specifically define the output shape of the results.

curl --location --request GET 'https://proxy.opendatagermany.io/api/ts/v1/kg/things?projectionDs=https://semantify.it/ds/w6t-oYImr&kw=Onlim' \
   --header 'Accept: application/json' \
   --header 'x-api-key: $API_KEY'
   #optional X-Publisher and X-Datasource

Use the ShapeQuery query language for complex use cases
We provide a more feature rich version of the query API to support more complex query use cases on top of the filter query parameters. (Jump to the Shape Queries user guide)

What’s Next