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 supporting 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 language ( inLang header parameter)

The API also allows the definition of the output shape of 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.

🚧

V1 is deprecated, please use V2

Version 1 of this endpoint 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.

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/v2/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 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 contain the mandatory properties of the specified shape filter DS
curl --location --request GET 'https://proxy.opendatagermany.io/api/ts/v2/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 to the shape of the shapeFilterDs.
Please use a projectionDs to define the output shape of the results specifically.

curl --location --request GET 'https://proxy.opendatagermany.io/api/ts/v2/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)

Fetching the full instances

While V1 of the API was responding with all properties of an object, V2 will only respond with the @id, @type and ds:compliesWith property. Therefore, a call to fetch a single instance is necessary.

A detailed description can be found here: https://changelog-dzt-kg.readme.io/docs/retrieving-objects

Multilingual data

The graph holds numerous objects that have data in various languages. All languages will be returned in the data in a query- or retrieval call, as described above. An example of a multilingual data object looks like this:

{
    "@id": "http://onlim.com/entity/3afcda58-86a3-406c-9675-f5946844a726",
    "@type": [
      "https://schema.org/TouristAttraction",
      "https://odta.io/voc/PointOfInterest"
    ],
    "https://schema.org/description": [
      {
        "@language": "de",
        "@value": "Die Krochsiedlung wurde von 1929 bis 1930 erbaut. Das Gemeinschaftsprojekt der Architekten Paul Mebes, Paul Emmerich, Johannes Koppe, Adolf Muesmann und Max Fricke befindet sich im Leipziger Stadtteil Gohlis. Der jüdische Bankier Hans Kroch, der auch das Krochhaus in der Goethestraße in Auftrag gab, finanzierte das Projekt mit.\nDie Krochsiedlung wurde als erste Bauetappe einer geplanten Wohnstadt „Neu-Gohlis“ geplant. Die unweit gelegene Versöhnungskirche sollte im Mittelpunkt der neuen Siedlung liegen. Das Projekt wurde jedoch nie vollendet. Damals verkörperte das Wohngebiet neuzeitliche Wohnkultur, die der Wohnungsnot in der späten Weimarer Republik Abhilfe schaffte. In den drei- und viergeschossigen Mehrfamilienhäusern befinden sich bis heute 1018 Wohnungen mit für den Bauhaus charakteristischen Wintergärten, die in den 1990er Jahren umfassend saniert wurden.\nUm das architekturhistorische und geschichtliche Erbe der Krochsiedlung zu pflegen, wurde 1991 der „Bürgerverein Krochsiedlung e.V.“ gegründet."
      },
      {
        "@language": "en",
        "@value": "The Krochsiedlung was built between 1929 and 1930. The collaborative project by architects Paul Mebes, Paul Emmerich, Johannes Koppe, Adolf Muesmann and Max Fricke is located in Leipzig's Gohlis district. The Jewish banker Hans Kroch, who also commissioned the Krochhaus in Goethestraße, helped finance the project.\nThe Krochsiedlung was supposed to be the first construction of a planned residential town \"Neu-Gohlis\". The nearby Reconciliation Church was supposed to be the centre of the new settlement. The project, however, was never completed. At that time, the residential area embodied modern residential culture and remedied the housing shortage of the late Weimar Republic. To this day, the three and four-storey apartment buildings contain 1018 apartments with conservatories characteristic of Bauhaus, which were extensively renovated in the 1990s.\nIn 1991, the \"Bürgerverein Krochsiedlung e.V.\" was founded to preserve the architectural and historical heritage of the Krochsiedlung."
      },
      ...

The property of interest in this response is https://schema.org/description. It has an array assigned holding two objects, each with an @language property.

Example

A full example is documented here: https://changelog-dzt-kg.readme.io/docs/pois-in-and-around-berlin


What’s Next