Skip to main content

Enpulse Data API v1 — Developer Docs

All endpoints are served under the base path /api/data/v1 on the host https://enpulse.gep.energy/gep-service.

All endpoints exchange JSON over HTTPS.

Authentication​

The Data API uses API key authentication. Provide a valid API key issued for your customer account in one of the following ways:

  • Request header: X-Api-Key: <your_api_key> (preferred)
  • Authorization header: Authorization: ApiKey <your_api_key>
  • Query parameter: ?api_key=<your_api_key>

If authentication is missing or invalid, the request fails and is not associated with any customer.

Conventions and Limits​

  • Time parameters use ISO-8601 local date-time format (no timezone), for example: 2025-10-05T13:00:00.
  • Timestamps in timeseries responses are epoch milliseconds in the ts field.
  • Period limit for telemetry queries: the difference between from and to must not exceed 24 hours (1 day). Requests exceeding this limit result in 400 Bad Request with message The requested period must not exceed 1 day.
  • Asset scoping: All asset IDs must belong to the authenticated customer, otherwise the request fails with 400 Bad Request and message Asset does not belong to the authenticated customer.
  • Device availability: Assets must have at least one device bound; otherwise telemetry requests fail with 400 Bad Request and message Asset has no devices bound.

Notes on data resolution:

  • Some assets have raw 15-minute resolution (when a metering point is available). Timeseries ts values are aligned to the underlying data; no additional midpoint shift is applied in this API variant.

Error Handling​

Common error responses:

  • 400 Bad Request
    • The requested period must not exceed 1 day
    • Asset does not belong to the authenticated customer
    • Asset has no devices bound
  • 401 Unauthorized
    • Missing API key authentication
    • Invalid authenticated customer ID

Error body format is framework-default (Spring) and may include fields such as timestamp, status, error, message, and path.

Data Types​

  • UUID: 36-character string, for example c6e1e3a3-5b77-4f2c-9e5c-3b2b6b2a9a10.

Models​

  • CustomerAssetModel (response from /assets):

    • id: UUID
    • name: string
    • description: string
    • createdAt: string (ISO-8601 date-time)
    • meteringPointId: string|null
    • connectionPowerFromGrid: number|null
    • connectionPowerToGrid: number|null
    • voltageLevel: string|null
    • supplierTariffModel: object|null
    • longitude: number|null
    • latitude: number|null
    • devices: object — map from DeviceProfile to TbDeviceModel
      • DeviceProfile values include REALTIME, HISTORICAL, METEO
      • TbDeviceModel:
        • id: UUID
        • deviceProfile: string
    • address: string|null
    • city: string|null
    • zipCode: string|null
    • country: string|null
    • state: string|null

  • TimeseriesItemModel:

    • ts: number — epoch milliseconds
    • value: number

Endpoints​

GET /api/data/v1/assets​

Returns all assets belonging to the authenticated customer. Tariff details are minimized in this listing.

  • Authentication: required
  • Query params: none
  • Returns: 200 OK with List<CustomerAssetModel>

Example request:

curl -X GET \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  https://enpulse.gep.energy/gep-service/api/data/v1/assets

Example response:

[
  {
    "id": "f2a4b100-1e4a-4c4b-96e4-2a2aaf3f2a12",
    "name": "Main Facility",
    "description": "HQ site",
    "createdAt": "2025-09-30T08:15:30",
    "meteringPointId": "DK1234567890",
    "connectionPowerFromGrid": 200.0,
    "connectionPowerToGrid": 100.0,
    "voltageLevel": "LV",
    "supplierTariffModel": null,
    "longitude": 12.5683,
    "latitude": 55.6761,
    "devices": {
      "REALTIME": { "id": "80c0b8f2-0e2c-4a0a-a7c1-01d9d23e1a8f", "deviceProfile": "REALTIME" },
      "HISTORICAL": { "id": "b0f3a3d0-0b25-4a5d-9c5c-5d2df0c4a5d2", "deviceProfile": "HISTORICAL" }
    },
    "address": "1 Market St",
    "city": "Copenhagen",
    "zipCode": "2100",
    "country": "DK",
    "state": null
  }
]

Notes:

  • Each asset must have at least one device bound to be usable for telemetry endpoints.

GET /api/data/v1/assets/{assetId}/telemetry/latest​

Returns the latest datapoint for the specified telemetry keys on a single asset.

  • Authentication: required
  • Path params:
    • assetId: UUID — must belong to the authenticated customer
  • Query params (required):
    • keys: string[] — one or more telemetry keys, e.g. keys=power,energy
  • Returns: 200 OK with Map<string, TimeseriesItemModel>; keys are the telemetry names

Example request:

curl -G \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  --data-urlencode "keys=power" \
  --data-urlencode "keys=energy" \
  https://enpulse.gep.energy/gep-service/api/data/v1/assets/80c0b8f2-0e2c-4a0a-a7c1-01d9d23e1a8f/telemetry/latest

Example response:

{
  "power": { "ts": 1728144000000, "value": 123.45 },
  "energy": { "ts": 1728144000000, "value": 6789.0 }
}

Validation and errors:

  • keys must be non-empty (400 Bad Request if empty)
  • assetId must belong to your customer; otherwise 400 Bad Request
  • Asset must have at least one device; otherwise 400 Bad Request with Asset has no devices bound

POST /api/data/v1/assets/telemetry/latest​

Returns latest datapoints for multiple assets in a single request.

  • Authentication: required
  • Body: JSON object LatestBatchRequest
    • assetIds: UUID[] (required, non-empty)
    • keys: string[] (required, non-empty)
  • Returns: 200 OK with Map<UUID, Map<string, TimeseriesItemModel>>

Example request:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -d '{
        "assetIds": [
          "80c0b8f2-0e2c-4a0a-a7c1-01d9d23e1a8f",
          "b0f3a3d0-0b25-4a5d-9c5c-5d2df0c4a5d2"
        ],
        "keys": ["power", "energy"]
      }' \
  https://enpulse.gep.energy/gep-service/api/data/v1/assets/telemetry/latest

Example response:

{
  "80c0b8f2-0e2c-4a0a-a7c1-01d9d23e1a8f": {
    "power": { "ts": 1728144000000, "value": 120.1 },
    "energy": { "ts": 1728144000000, "value": 6780.0 }
  },
  "b0f3a3d0-0b25-4a5d-9c5c-5d2df0c4a5d2": {
    "power": { "ts": 1728144005000, "value": 15.2 },
    "energy": { "ts": 1728144005000, "value": 100.0 }
  }
}

Validation and errors:

  • All assetIds must belong to the authenticated customer; the request fails if any do not
  • assetIds and keys must be non-empty
  • Each asset must have at least one device; otherwise the request fails with 400 Bad Request

GET /api/data/v1/assets/{assetId}/telemetry​

Returns a timeseries for the given telemetry keys between the from and to timestamps.

  • Authentication: required
  • Path params:
    • assetId: UUID — asset must belong to the authenticated customer
  • Query params (all required):
    • keys: string[] — one or more telemetry keys
    • from: string (ISO-8601 local date-time) — inclusive start
    • to: string (ISO-8601 local date-time) — exclusive end; to - from <= 24h
  • Returns: 200 OK with Map<string, List<TimeseriesItemModel>>

Behavioral notes:

  • If the asset has a metering point (raw 15-minute resolution available), the API returns raw datapoints at that resolution for the requested period.
  • The ts in each TimeseriesItemModel is the exact epoch millisecond timestamp of the datapoint.

Example request:

curl -G \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  --data-urlencode "keys=power" \
  --data-urlencode "from=2025-10-05T00:00:00" \
  --data-urlencode "to=2025-10-05T06:00:00" \
  https://enpulse.gep.energy/gep-service/api/data/v1/assets/80c0b8f2-0e2c-4a0a-a7c1-01d9d23e1a8f/telemetry

Example response:

{
  "power": [
    { "ts": 1728097200000, "value": 100.0 },
    { "ts": 1728100800000, "value": 110.5 },
    { "ts": 1728104400000, "value": 98.2 }
  ]
}

Validation and errors:

  • keys must be non-empty
  • from and to must be valid ISO-8601 date-times; to must be after from
  • The requested period must not exceed 24 hours; otherwise 400 Bad Request
  • Asset must have a bound device; otherwise 400 Bad Request

Device Selection Logic​

When requesting telemetry for an asset, the API resolves the primary device to query:

  • Prefer device with DeviceProfile.REALTIME if present
  • Otherwise, use the first available device for the asset

If an asset has no devices, the API responds with 400 Bad Request and Asset has no devices bound.

Best Practices​

  • Always prefer the X-Api-Key header for authentication.
  • Keep keys arrays minimal to reduce payload and latency.
  • For large time ranges, segment your requests into multiple windows not exceeding 24 hours.