Changelog
Guides

Query API

Suggest Edits

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 you 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. This can be found here: https://changelog-dzt-kg.readme.io/docs/retrieving-objects.

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 'https://proxy.opendatagermany.io/api/ts/v2/kg/things?kw=Wartburg&filterDsList=https://semantify.it/list/CRkyvcqGqeUu' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'page: 1' \
  -H 'page-size: 5' \
  -H 'x-api-key: <APIKEY>'

Mind the filterDsList query parameter, which pre-filters the results by a list of defined domain specifications. Without that parameter, the query might time out.

Filter for things by a domain specification using the filterDs query parameter

filterDs searches things that have a ds:compliesWith statement with the search value

curl 'https://proxy.opendatagermany.io/api/ts/v2/kg/things?filterDs=https://semantify.it/ds/JxAwhroBYXVe' \
  -H 'accept: application/json' \
  -H 'page: 1' \
  -H 'page-size: 5' \
  -H 'x-api-key: <APIKEY>'

This query can be combined with the previous query by adding the kw parameter.

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

Updated 2 months ago

What’s Next