Skip to content

Intro

The Hedgehog Energy API allows you to programmatically query energy meter data from your locations. Use it to integrate energy readings into your own dashboards, analytics, or automation workflows.

Base URL

https://api.hedgehogapplications.nl/v1

Interactive Docs

Swagger UI is available at api.hedgehogapplications.nl/docs for interactive testing.

Pre-requisites

Authentication

An X-API-Key header must be provided with every request:

X-API-Key: hh_live_a1b2c3d4e5f6...

Note

Your API key is provided by Hedgehog during onboarding. Keep it secret — it grants access to all your energy data. Contact us if you need to rotate your key.

Example Request

curl -H "X-API-Key: hh_live_a1b2c3d4e5f6..." \
  https://api.hedgehogapplications.nl/v1/locations

import requests

API_KEY = "hh_live_a1b2c3d4e5f6..."
BASE_URL = "https://api.hedgehogapplications.nl/v1"

headers = {"X-API-Key": API_KEY}
response = requests.get(f"{BASE_URL}/locations", headers=headers)
locations = response.json()

const API_KEY = "hh_live_a1b2c3d4e5f6...";
const BASE_URL = "https://api.hedgehogapplications.nl/v1";

const response = await fetch(`${BASE_URL}/locations`, {
  headers: { "X-API-Key": API_KEY },
});
const locations = await response.json();

Error Responses

Status Meaning
401 Missing or invalid API key
404 Resource not found (or not owned by your account)
429 Rate limit exceeded — wait and retry
500 Internal server error

Rate Limiting

Requests are limited to 100 per minute per API key. When the limit is reached, the API returns 429 Too Many Requests with a Retry-After header.

Terminology

Term Description
Location A physical site (building, plant, depot) that contains one or more energy meters
Energy Meter A device measuring electrical energy flow, reporting import_kwh and/or export_kwh
import_kwh Cumulative energy imported from the grid (kWh)
export_kwh Cumulative energy exported to the grid (kWh)
Telemetry Time-series data reported by energy meters

API Overview

The API follows a natural navigation flow:

1. List your locations          → GET /v1/locations
2. List meters at a location    → GET /v1/locations/:id/energy-meters
3. Discover available keys      → GET /v1/energy-meters/:id/keys
4. Query historical data        → GET /v1/energy-meters/:id/telemetry
5. Get the latest reading       → GET /v1/energy-meters/:id/telemetry/latest