Quick-start Guide: Builders Edition

Introduction

The Knowledge Graph Platform API allows developers to search, filter, and retrieve data quickly and efficiently. This guide will help you start using the API in under 5 minutes. Ensure you have your API key ready, and let’s get started.

Authentication

To authenticate, include your API key in the request header using the x-api-key field. Make sure every API call starts with https://proxy. and NOT https://app..

In the examples below, replace the placeholder <APIKEY> with the API key you want to use.

Common Use Cases

Keyword Search

Performing a simple keyword search is as easy as sending a GET request. For example, to search for data supported by ODTA Domain Specifications in the city of "Jena", you can use:

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

The response will be in JSON format, typically including metadata like dsCount (the number of results found for a given DS), page size, and the total of results. The actual data is an array holding the found objects. They have the properties @type to describe of what type the data is, an @id, that identifies the data uniquely in the knowledge graph and the ds:compliesWith property, which denotes the domain specification with which the data complies.

More about the keyword search can be found here: https://changelog-dzt-kg.readme.io/docs/query-api

Fetching Instances

To retrieve detailed information about a specific instance, use the get-by-id endpoint. A sample request for the dataset identified by the @id: https://thuecat.org/resources/020968973575-nxbz

curl 'https://proxy.opendatagermany.io/api/ts/v2/kg/things/020968973575-nxbz?ns=https://thuecat.org/resources/&projectionDs=https://semantify.it/ds/Xkd5YH3-1' \
-H 'accept: application/json' \
-H 'x-api-key: <APIKEY>'

(Mind the projectionDS parameter that makes the query fast and the result slim. Read more about it by following the link below.)

Read this page https://changelog-dzt-kg.readme.io/docs/retrieving-objects for more information on how to retrieve objects.

Quick Tips

The API may have rate limits, so consider the number of requests. Errors such as 401 indicate authentication problems; check your API key if this happens. If your response is paginated, look for the next field to fetch additional results pages. If your query is too generic, you might encounter errors such as 524; check the optimizations page if that happens.

For more information consider reading this section of the guide: https://dash.readme.com/project/changelog-dzt-kg/v1.0/docs/guidelines-and-debugging

Next Steps

Refer to the full documentation here for advanced use cases and more complex queries. If you need help, feel free to contact our team.