API quickstart

The DataGarden REST API returns normalized public data — demographics, economics, health, household, social environment, energy, trade — keyed by consistent geographic identifiers. Authenticate with an API key, then fetch data with a single request.

1Get an API key

Create a key from My Account → API keys (sign in first). Send it on every request in the X-API-Key header. Keep it secret — treat it like a password.

2Make a request

curl

curl -H "X-API-Key: $DATAGARDEN_API_KEY" \
  "http://dg-api-staging.railway.internal:8080/v1/countries/NL/datasets/demographics"

Python

import os
import requests

BASE_URL = "http://dg-api-staging.railway.internal:8080"
headers = {"X-API-Key": os.environ["DATAGARDEN_API_KEY"]}

resp = requests.get(
    f"{BASE_URL}/v1/countries/NL/datasets/demographics",
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
dataset = resp.json()
print(dataset["period_from"], "→", dataset["period_to"])
for record in dataset["records"]:
    print(record["period"], record["source_name"])

Prefer a typed client? pip install the-datagarden — the Python SDK wraps these endpoints.

Example responses

Field shapes below are exact (from the OpenAPI spec); values are illustrative.

GET /v1/countries/NL

{
  "name": "Netherlands",
  "iso_cc_2": "NL",
  "continent_name": "Europe",
  "region_count": 12,
  "geojson_url": "http://dg-api-staging.railway.internal:8080/v1/countries/NL/geojson",
  "regions_url": "http://dg-api-staging.railway.internal:8080/v1/countries/NL/regions"
}

GET /v1/countries/NL/datasets/demographics

{
  "dataset": "demographics",
  "region": {
    "name": "Netherlands",
    "datagarden_id": "\u2026",
    "country_iso_cc_2": "NL",
    "type": "country",
    "parent_id": null,
    "geojson_url": "\u2026"
  },
  "period_type": "year",
  "period_from": "2015",
  "period_to": "2023",
  "records": [
    {
      "period": "2023",
      "period_type": "year",
      "period_as_period_type_frmt": "2023",
      "source_name": "CBS",
      "data": "\u2026demographics fields \u2014 see the model reference\u2026"
    }
  ]
}

Each record’s data object holds the domain fields — see the model reference for the full schema.

Key endpoints

Method	Path	Description
GET	/v1/continents	List continents
GET	/v1/countries	List countries
GET	/v1/countries/{iso_cc_2}	Country detail
GET	/v1/countries/{iso_cc_2}/regions	Regions within a country
GET	/v1/countries/{iso_cc_2}/datasets/demographics	Country demographics
GET	/v1/countries/{iso_cc_2}/datasets/economics	Country economics
GET	/v1/regions/{datagarden_id}/datasets/demographics	Region demographics
GET	/v1/datasets	List available datasets
GET	/v1/brands	List brands
GET	/v1/locations	List locations

The full endpoint list lives in the OpenAPI spec.