Data Packages

A Data Package is a curated set of knowledge graph entities that you can export as a downloadable ZIP file. Each package uses a shape query to define exactly which data is included.

Getting data out of a package is a four-step journey: register → find a package → subscribe → fetch the data. The steps below walk through each one, both in the web UI and via the API.

📘

API base URL & authentication

All API calls go through the proxy:

• Base URL: https://proxy.opendatagermany.io/api/ts
• Header: x-api-key: <your-api-key>

The endpoint paths below are relative to that base URL — e.g. GET /v1/kg/data-packages means GET https://proxy.opendatagermany.io/api/ts/v1/kg/data-packages.

Step 1 — Register on the platform (one time)

Before you can browse or request anything, you need an account on the platform. This is a one-time, manual step.

👉 Register here: https://app.opendatagermany.io/

Once registered, you'll have an organization and an API Key you can use both in the web UI and for the API calls in the following steps.

Step 2 — Find a data package

Browse the catalog to discover which packages are available and find the one you want.

In the web UI: go to Service Portal → Data Package Catalog.

Via the API: list all available packages:

GET /v1/kg/data-packages

You can narrow the results with filter and page query parameters. To view the details of a single package:

GET /v1/kg/data-packages/{id}

The response includes the package id, name, description, keywords, contactPerson, license, and — if you already have a subscription — its subscriptionId and subscriptionStatus. Note the id of the package you're interested in; you'll need it in the next steps.

Step 3 — Request a subscription

You can't export a package's data until your organization has an approved subscription to it. Requesting a subscription notifies the package owner, who then approves or rejects your request.

In the web UI: open the package in the catalog and click Request subscription.

Via the API:

POST /v1/kg/data-packages/subscriptions
Content-Type: application/json

{
  "dataPackageId": "<the-package-id-from-step-2>",
  "comment": "Why you'd like access to this package"
}

The response contains your subscription with a status of REQUESTED. Once the owner acts on it, the status becomes APPROVED (or REJECTED).

To check on your requests at any time, list your subscriptions:

GET /v1/kg/data-packages/subscriptions

Step 4 — Fetch the data you subscribed for

Once your subscription is approved, fetching data is a two-part process: trigger an export, then download it.

4a. Request an export

This queues the export. The system runs the package's shape query against the graphs you can access, bundles the matching entities into a JSON-LD file inside a ZIP archive, and then notifies you when it's ready. You must provide at least one of callbackEmail or callbackUrl so we can tell you when the export is done.

POST /v1/kg/data-packages/{id}/[email protected]

Optional query parameters:

4b. Download the export

After you're notified that the export is ready, download the ZIP:

GET /v1/kg/data-packages/{id}/download

This redirects (HTTP 302) to the actual ZIP file. If no export has been generated yet, you'll get a 404.

📘

Need regular updates? Exports are not refreshed automatically. If you need up-to-date data on a schedule, set up your own job (e.g. a cron) that calls the request endpoint at your preferred interval — daily, weekly, etc.

Quick reference