smartmeter Developer Reference

smartmeter Data Dictionary & API Reference

Complete specification of API types (REST, Data Lake, Graph), schemas, data types, supported operations, and IEC CIM mappings.

On this page API Types & Protocols Data Dictionary & Schemas REST API Explorer Standards Mapping (IEC CIM / BSC) Webhooks & Alerts Sandbox & Offline Verifier

1. Supported API Types & Categories

smartmeter exposes 3 distinct API categories tailored for web applications, high-performance data lakes, and topological graph analytics:

REST API (HTTP/JSON)

REST Ingestion & Verification API

Supported Operations: POST, GET
Standard HTTP JSON API for smart meter ingestion (`/v1/etp/ingest`), daily Merkle checkpoint verification (`/v1/etp/query/verify`), and proof pack downloads (`/v1/etp/checkpoint`).

DATA LAKE API (gRPC / Arrow Flight)

Zero-Copy Data Lake Stream API

Supported Operations: gRPC Stream, ANSI SQL SELECT
High-throughput zero-copy stream API (Port 8889) reading compressed Parquet directly into PyArrow/Pandas RecordBatch streams with zero JSON serialization overhead.

GRAPH API (Apache AGE / openCypher)

Topology Graph API

Supported Operations: POST (openCypher), GET
Executes openCypher graph traversals (`MATCH (a)-[r]->(b)`) over the IEC CIM grid hierarchy (`GSP → Substation → Feeder → Meter`) to pinpoint common feeder causes during outages.

2. Data Dictionary & Schema Reference

Official schema definition for silver_ami_readings (deduplicated, conformed half-hourly smart meter readings in open Apache Iceberg format).

silver_ami_readings PUBLISHED SCHEMA

Deduplicated half-hourly meter readings · Table Owner: AMI Engineering Team · Format: Apache Iceberg (Parquet)

Field	Type	Supported Filters / Operations	Meaning & Standard Mapping
mpan	string	`=`, `IN (...)`	Metering Point Administration Number · IEC 61968 UsagePoint
hh_start	timestamp	`>=`, `<=`, `BETWEEN`	Settlement period start time (UTC) · aligned to the Elexon BSC half-hourly settlement periods (1–48)
kwh	double	`SUM`, `AVG`, `MIN`, `MAX`	Active energy consumed / exported (kWh) · IEC 61968 ReadingType
feeder_id	string	`=`, `IN (...)`	Network electrical element identifier · CIM ACLineSegment
etp_verify_status	string	`= 'VERIFIED'`, `= 'ESTIMATED'`	Verification boundary status (`VERIFIED`, `ESTIMATED`, `REPLAY_REJECTED`)
merkle_root	string	`=` (Exact SHA-256 match)	SHA-256 Merkle root digest for daily proof pack validation

3. REST API Explorer & Payload Inspector

Test endpoints, inspect cURL commands, and review JSON response payloads:

GET /v1/readings?feeder=F-4471&limit=50

cURL Command

curl -X GET "https://zerocopy.meldra.ai/v1/readings?feeder=F-4471&limit=50" -H "Authorization: Bearer mld_live_8f3a921"

HTTP Response Payload

{ "status": "200 OK", "latency": "24ms", "feeder": "F-4471", "total_records": 48, "data": [ { "mpan": "1019283746", "hh_start": "2026-09-12T22:00:00Z", "kwh": 14.82, "status": "Substantiated" } ] }

4. International Standards Mapping

smartmeter maps internal schema attributes directly to global energy standards:

Standard Body	Standard Reference	Mapped Attribute / Entity
IEC 61968	Application Integration for Electric Utilities	`UsagePoint` → `mpan`, `MeterReading` → `kwh`
IEC 61970 (CIM)	Common Information Model (Grid Topology)	`ACLineSegment` → `feeder_id`, `Substation` → `substation_id`
UK Elexon BSC	Balancing and Settlement Code	Data mapping only: half-hourly settlement periods 1 to 48 (UTC boundary offset). Not an Elexon certification or schema.
W3C PROV-O	Provenance Data Model	`prov:wasDerivedFrom` snapshot ID tracking for settlement audit trails

5. Webhooks & Automated Event Triggers

Configure real-time webhooks to trigger downstream billing or operational workflows when key events occur:

omission.sequence_gap_detected: Triggered when monotonic sequence gaps (e.g. missing settlement periods 24–29) are ingested.
vee.boundary_estimated: Triggered when values are flagged as ESTIMATED by VEE routines.
settlement.dispute_pack_ready: Triggered when a 60-second BSC dispute pack is generated and ready for export.

6. Sandbox Instance & Offline Verifier Guide

Test smartmeter features in an isolated sandbox environment or run offline verification on your local computer.

Offline Verification in 4 Simple Steps

Export Proof Pack: Export a .json Proof Pack bundle from the portal or API.
Download Verifier Binary: Download the standalone verifier (etp_verifier.exe or Python CLI script).
Execute Verification: Open your terminal and run:
```
etp_verifier proof_pack_2026_09_22.json
```

Review Output: Check the fail-closed verification result:

[SUCCESS] Proof Pack Verification Passed!
• Meter Point (MPAN): 1200000000001
• Observed Periods: 48/48 (100% Complete)
• Status: Cryptographically Valid & Unaltered

Evaluating smartmeter for your utility? Read the Business Case Guide or contact your solution team.