Retrieve Meter Readings for Consumer and Producer Contracts

Overview

Meter readings represent individual timestamped measurements from physical meters attached to consumer or producer contracts. Each reading captures an energy value in Wh along with metadata such as the measurement reason, data quality classification, OBIS number, and cancellation status. Readings are retrieved per contract and support rich filtering so you can query specific time windows, devices, or modification events. Base URL: https://api.lumenaza.de/ · Test URL: https://api.test.lumenaza.de/

A meter reading is uniquely identified by the combination of its timestamp, obis_number, and device_identification. Avoid treating any single field alone as a unique key.

Consumer Meter Readings

GET /v3/consumers/{userID}/contracts/{contractID}/meter_readings/

Returns a paginated list of meter readings for a specific consumer contract.

Path Parameters

Parameter	Type	Description
`userID`	string	The unique ID of the consumer user.
`contractID`	string	The unique ID of the consumer contract.

Query Filters

All filter parameters are optional. Date/time filters accept ISO 8601 datetime strings.

Parameter	Description
`created`	Exact match on the record creation datetime.
`created__gte`	Records created on or after this datetime.
`created__lte`	Records created on or before this datetime.
`modified`	Exact match on the last modification datetime.
`modified__gte`	Records modified on or after this datetime.
`modified__lte`	Records modified on or before this datetime.
`timestamp`	Exact match on the reading’s measurement timestamp.
`timestamp__gte`	Readings measured on or after this datetime.
`timestamp__lte`	Readings measured on or before this datetime.
`device_identification`	Filter to a specific meter device by its identification string.

Response Fields

Each reading in the results array contains:

Field	Type	Description
`device_identification`	string	Identifier of the meter device that produced this reading.
`timestamp`	string	ISO 8601 datetime when the measurement was taken.
`reason`	string	Reason for this reading (e.g., periodic, contract start/end).
`quality`	string	Data quality classification. See Quality Values below.
`value`	integer	Energy reading value in Wh.
`obis_number`	string	OBIS code identifying the measured quantity (e.g., `1-0:1.8.0`).
`is_cancelled`	boolean	Whether the meter operator has cancelled this reading. See note below.
`created`	string	ISO 8601 datetime when this record was first created in the system.
`modified`	string	ISO 8601 datetime when this record was last modified.

Cancellation

When is_cancelled is true, the meter operator has marked this reading as invalid. Readings can only be modified when they are in a cancelled state. Non-cancelled readings are considered finalized and locked.

Quality Values

The quality field uses the following German-language classifications:

Value	Meaning
`Abgelesener Wert`	Directly read value (highest confidence).
`Ersatzwert - geschätzt`	Estimated substitute value.
`Vorschlagswert`	Suggested/proposed value.
`Nicht verwendbarer Wert`	Non-usable value (rejected reading).
`Prognosewert`	Forecast/projected value.
`Energiemenge summiert`	Aggregated energy total.

Example: Filter by Timestamp Range

curl -X GET "https://api.lumenaza.de/v3/consumers/USR-4821/contracts/CON-9934/meter_readings/?timestamp__gte=2024-03-01T00:00:00Z&timestamp__lte=2024-03-31T23:59:59Z" \
  -H "Authorization: Bearer <token>"

Example Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "device_identification": "1ESY1160052874",
      "timestamp": "2024-03-01T00:00:00Z",
      "reason": "Turnusablesung",
      "quality": "Abgelesener Wert",
      "value": 10482300,
      "obis_number": "1-0:1.8.0",
      "is_cancelled": false,
      "created": "2024-03-04T08:12:45Z",
      "modified": "2024-03-04T08:12:45Z"
    },
    {
      "device_identification": "1ESY1160052874",
      "timestamp": "2024-03-15T00:00:00Z",
      "reason": "Stichtagsablesung",
      "quality": "Ersatzwert - geschätzt",
      "value": 10619700,
      "obis_number": "1-0:1.8.0",
      "is_cancelled": false,
      "created": "2024-03-17T10:05:30Z",
      "modified": "2024-03-18T14:22:10Z"
    },
    {
      "device_identification": "1ESY1160052874",
      "timestamp": "2024-03-31T23:59:59Z",
      "reason": "Turnusablesung",
      "quality": "Abgelesener Wert",
      "value": 10784500,
      "obis_number": "1-0:1.8.0",
      "is_cancelled": true,
      "created": "2024-04-02T07:48:00Z",
      "modified": "2024-04-03T09:15:00Z"
    }
  ]
}

Producer Meter Readings

GET /v3/producers/{userID}/contracts/{contractID}/meter_readings/

Returns a paginated list of meter readings for a specific producer contract. The response structure and all filter parameters are identical to the consumer endpoint.

Path Parameters

Parameter	Type	Description
`userID`	string	The unique ID of the producer user.
`contractID`	string	The unique ID of the producer contract.

Supported Filters

All filters available on the consumer endpoint apply here as well. The device_identification filter is particularly useful for producers with multiple meters or generation units on a single contract.

Example Request

curl -X GET "https://api.lumenaza.de/v3/producers/USR-7703/contracts/CON-1105/meter_readings/?device_identification=1ESY1160099321" \
  -H "Authorization: Bearer <token>"

The response follows the same paginated structure:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "device_identification": "1ESY1160099321",
      "timestamp": "2024-04-01T00:00:00Z",
      "reason": "Turnusablesung",
      "quality": "Abgelesener Wert",
      "value": 5823400,
      "obis_number": "1-0:2.8.0",
      "is_cancelled": false,
      "created": "2024-04-03T11:00:00Z",
      "modified": "2024-04-03T11:00:00Z"
    }
  ]
}

Get Started

Core Concepts

Guides

Data & Analytics

Retrieve Meter Readings for Consumer and Producer Contracts

Overview

Consumer Meter Readings

GET /v3/consumers/{userID}/contracts/{contractID}/meter_readings/

Path Parameters

Query Filters

Response Fields

Cancellation

Quality Values

Example: Filter by Timestamp Range

Example Response

Producer Meter Readings

GET /v3/producers/{userID}/contracts/{contractID}/meter_readings/

Path Parameters

Supported Filters

Example Request

​Overview

​Consumer Meter Readings

​GET /v3/consumers/{userID}/contracts/{contractID}/meter_readings/

​Path Parameters

​Query Filters

​Response Fields

​Cancellation

​Quality Values

​Example: Filter by Timestamp Range

​Example Response

​Producer Meter Readings

​GET /v3/producers/{userID}/contracts/{contractID}/meter_readings/

​Path Parameters

​Supported Filters

​Example Request

Overview

Consumer Meter Readings

GET /v3/consumers/{userID}/contracts/{contractID}/meter_readings/

Path Parameters

Query Filters

Response Fields

Cancellation

Quality Values

Example: Filter by Timestamp Range

Example Response

Producer Meter Readings

GET /v3/producers/{userID}/contracts/{contractID}/meter_readings/

Path Parameters

Supported Filters

Example Request