clj-midas

A Clojure client library for the California Energy Commission's MIDAS API, providing access to electricity rate data, GHG emissions signals, Flex Alerts, and reference lookup tables. Built on a non-official OpenAPI spec derived from the CEC's public documentation.

MIDAS v2.0 (live 2026-06-22): clj-midas 1.0.0 tracks the CEC's breaking v2.0 API and is a v2-only release — v1.0 disappeared from the live service that day. See doc/v2-migration.md for the v1.0→v2.0 upgrade guide.

This is a read-only consumer client. clj-midas is built for consuming MIDAS data. In v2.0 all public GET endpoints are unauthenticated, so you need no credentials — just (create-anonymous-client). The authenticated constructors (create-client / create-auto-client) exist only for utilities that upload rate data to the CEC; that path requires CEC-issued utility credentials and is not exercised by this project.

Features

• Spec-driven HTTP client built on Martian with the bundled OpenAPI spec as the single source of truth
• Two-layer data model: raw API responses (PascalCase, strings) and coerced Clojure entities (namespaced keywords, BigDecimals, java.time types)
• Unauthenticated by default: v2.0 public GET endpoints need no token; uploads (utilities only) get auto-refreshing 10-minute bearer tokens, transparently renewed before expiry
• ZonedDateTime end-to-end — every coerced timestamp is a ZonedDateTime in the client's configured zone (default America/Los_Angeles, MIDAS's native zone); DST-aware by construction
• Metadata preservation: every coerced entity carries the original API data as :midas/raw metadata
• Malli schemas for both raw and coerced data layers
• RIN parsing: decompose a Rate Identification Number into its component fields, with optional annotation from lookup tables
• Signal type helpers: flex-alert?, flex-alert-active?, ghg? for quick classification

Installation

Add to your deps.edn:

{:deps {energy.grid-coordination/clj-midas {:mvn/version "1.0.0"}}}

Quick Start

(require '[midas.client :as client]
         '[midas.entities :as entities])

;; v2.0: all GET endpoints are unauthenticated — no token needed.
;; This is all a data consumer needs:
(def c (client/create-anonymous-client))

;; The authenticated constructors below are for UTILITIES that upload rate
;; data to the CEC (POST); they require CEC-issued utility credentials and are
;; not needed — or exercised — for read-only consumption.
;; auto-refreshing client (token renews transparently)
(def c (client/create-auto-client "username" "password"))
;; or manually: acquire token, then create client
(def token-info (client/get-token "username" "password"))
(def c (client/create-client token-info))

;; Fetch rate values for a RIN
(def resp (client/get-rate-values c "USCA-TSTS-TTOU-TEST" "alldata"))
(client/success? resp)
;=> true

;; Coerce to idiomatic Clojure entities
(def rate (entities/rate-info resp))

API Endpoints

clj-midas wraps the MIDAS v2.0 endpoints:

Function	Endpoint	Description
get-rin-list	GET /ValueData?SignalType=	List available RINs by signal type (0=All, replaces the removed HistoricalList)
get-rate-values	GET /ValueData?ID=&QueryType=	Fetch rate/price data for a RIN
get-lookup-table	GET /ValueData?LookupTable=	Fetch reference data (codes & descriptions)
get-historical-data	GET /HistoricalData/{rate_id}	Fetch archived rate data by date range (6-month max per call)
register	POST /Registration	Register a new API account (utility uploaders)

Data Model

The library provides two views of the API data:

Raw Layer

Direct from the JSON — PascalCase keys, string values. Useful for debugging or when you need the exact API representation.

(:body resp)
;=> {:RateID "USCA-TSTS-TTOU-TEST"
;    :RateName "CEC TEST24HTOU"
;    :RateType "Time of use"
;    :ValueInformation [{:ValueName "winter off peak"
;                         :DateStart "2023-05-01"
;                         :TimeStart "07:00:00"
;                         :value 0.1006
;                         :Unit "$/kWh"} ...]}

Coerced Layer

Idiomatic Clojure — namespaced keywords, native types. Tick boundaries (:tick/beginning, :tick/end) and parsed datetimes (:midas.rate/system-time, :midas.rin/last-updated, …) are ZonedDateTime in the client's configured zone — see Time and timezones.

(entities/rate-info resp)
;=> #:midas.rate{:id "USCA-TSTS-TTOU-TEST"
;                :name "CEC TEST24HTOU"
;                :type :midas.rate-type/tou
;                :system-time #zoned-date-time "2026-03-19T03:03:46.379-07:00[America/Los_Angeles]"
;                :values [#:midas.value{:name "winter off peak"
;                                       :price 0.1006M
;                                       :unit :midas.unit/dollar-per-kwh
;                                       :day-start :midas.day/monday
;                                       :tick/beginning #zoned-date-time "2026-05-01T00:00-07:00[America/Los_Angeles]"
;                                       :tick/end       #zoned-date-time "2026-05-01T00:59:59-07:00[America/Los_Angeles]"} ...]}

Entities

RateInfo

Key	Type	Description
:midas.rate/id	String	Rate Identification Number (RIN)
:midas.rate/name	String	Rate name
:midas.rate/type	Keyword or String	Rate type (:midas.rate-type/tou, /cpp, /rtp, /ghg, /flex-alert, or passthrough string)
:midas.rate/system-time	ZonedDateTime	Server timestamp (parsed from SystemTime_UTC, displayed in the client's configured zone)
:midas.rate/sector	String or nil	Customer sector
:midas.rate/end-use	String or nil	End use category
:midas.rate/api-url	String or nil	API URL (literal "None" becomes nil)
:midas.rate/rate-plan-url	String or nil	Rate schedule URL
:midas.rate/signup-close	ZonedDateTime or nil	Signup deadline (parsed from a Z-suffixed wire field)
:midas.rate/values	vector	Vector of ValueData maps

ValueData

Key	Type	Description
:midas.value/name	String	Interval description (e.g. "winter off peak")
:midas.value/day-start	Keyword or nil	Day type (:midas.day/monday ... :midas.day/holiday)
:midas.value/day-end	Keyword or nil	Day type
:midas.value/price	BigDecimal	Price or emissions value
:midas.value/unit	Keyword or String	Unit (:midas.unit/dollar-per-kwh, /g-co2-per-kwh, /event, etc.)
:tick/beginning	ZonedDateTime	Interval start as a zone-aware moment, in the client's configured zone (composed from the UTC wire date+time). Present when both wire boundaries exist.
:tick/end	ZonedDateTime	Interval end as a zone-aware moment. Present when both wire boundaries exist.

The interval boundaries are exposed only as zone-aware :tick/* ZonedDateTime values — there are no zone-naive LocalDate/LocalTime boundary fields. A consumer who wants a wall-clock date or time calls (.toLocalDate tick) / (.toLocalTime tick) (optionally after .withZoneSameInstant to a zone of choice). The exact wire strings remain available under :midas/raw.

RinListEntry

Key	Type	Description
:midas.rin/id	String	Rate Identification Number
:midas.rin/signal-type	Keyword or nil	Signal type (:midas.signal-type/rates, /ghg, /flex-alert)
:midas.rin/description	String	Human-readable description
:midas.rin/last-updated	ZonedDateTime or nil	Last data update (v2.0 wire field carries a UTC offset, e.g. +0000; re-expressed in the configured zone)

LookupEntry

Key	Type	Description
:midas.lookup/code	String	Upload code
:midas.lookup/description	String	Human-readable description

ParsedRin

Key	Type	Description
:midas.rin/country	String	Country code (e.g. "US")
:midas.rin/state	String	State code (e.g. "CA")
:midas.rin/distribution	String	Distribution utility code (e.g. "PG")
:midas.rin/energy	String	Energy provider code (e.g. "PG")
:midas.rin/rate	String	Rate schedule identifier (e.g. "TOU4")
:midas.rin/location	String	Location identifier (e.g. "0000")
:midas.rin/distribution-name	String or absent	Human-readable distribution utility name (added by annotate-rin)
:midas.rin/energy-name	String or absent	Human-readable energy provider name (added by annotate-rin)

Type Coercion Summary

Raw (API)	Coerced (Clojure)	Example
ISO datetime with Z	java.time.ZonedDateTime (instant preserved, displayed in client's zone)	"2026-03-19T10:03:46.379Z" → #zoned-date-time "2026-03-19T03:03:46.379-07:00[America/Los_Angeles]"
Datetime with basic UTC offset (LastUpdated, v2.0)	java.time.ZonedDateTime (instant preserved, displayed in client's zone)	"2021-07-14T14:31:55+0000" → #zoned-date-time "2021-07-14T07:31:55-07:00[America/Los_Angeles]"
ValueInformation date + time (UTC) → tick	java.time.ZonedDateTime (UTC instant, displayed in client's zone)	("2026-05-01", "07:00:00") → #zoned-date-time "2026-05-01T00:00-07:00[America/Los_Angeles]"
Number	BigDecimal	0.1006 → 0.1006M
Rate type string	Namespaced keyword	"TOU" (or long-form "Time of use") → :midas.rate-type/tou
Unit string	Namespaced keyword	"$/kWh" → :midas.unit/dollar-per-kwh
Day string	Namespaced keyword	"Monday" → :midas.day/monday

Time and timezones

MIDAS is the California Energy Commission's API and uses America/Los_Angeles as its native zone for window boundaries. In v2.0 the per-interval ValueInformation date/time fields (DateStart/TimeStart/DateEnd/TimeEnd) are delivered as UTC for every signal type — a change from v1.0, where SGIP GHG and Flex Alert signals carried Pacific-Time wire values (an upstream-provider bug the CEC fixed in v2.0). Z-suffixed fields (SystemTime_UTC, SignupCloseDate) remain UTC; the RIN-list LastUpdated field now carries a basic-format UTC offset (e.g. +0000) in v2.0 (it was a bare wall-clock string in v1.0). See midas-api-specs/doc/datetime-and-timezone.md.

clj-midas normalises both styles to a single in-memory representation:

Every coerced datetime is a java.time.ZonedDateTime in the client's configured zone.

The default zone is America/Los_Angeles; override with :zone at client construction:

;; default zone America/Los_Angeles — every coerced moment is re-expressed here
(def c (client/create-anonymous-client))

;; override — accepts a ZoneId or a zone-id string
(def c-utc (client/create-anonymous-client {:zone "UTC"}))
(def c-pt  (client/create-anonymous-client {:zone (java.time.ZoneId/of "America/Los_Angeles")}))

How parsing works

Wire field	Wire form	Coerced as
SystemTime_UTC, SignupCloseDate	ISO 8601 with Z (UTC)	Parsed as OffsetDateTime, re-expressed in the configured zone via .atZoneSameInstant (instant preserved).
DateStart+TimeStart, DateEnd+TimeEnd (ValueInformation)	Bare date + time, UTC (v2.0)	The :tick/beginning / :tick/end moments are composed in UTC then re-expressed in the configured zone via .withZoneSameInstant (instant preserved, DST-correct).
LastUpdated (RIN-list)	ISO 8601 with a basic-format UTC offset, e.g. 2021-07-14T14:31:55+0000 (v2.0)	Parsed as OffsetDateTime (a lenient formatter accepts +0000, +00:00, and Z), re-expressed in the configured zone (instant preserved). A bare no-offset string is still accepted as wall-clock in the zone.

Why ZonedDateTime (and not Instant or OffsetDateTime)

ZonedDateTime carries an IANA zone (America/Los_Angeles) that knows DST rules. .plusDays(1) on a PT timestamp lands on the next PT midnight regardless of spring-forward/fall-back. OffsetDateTime carries a fixed offset and gets DST math wrong; Instant discards wall-clock semantics entirely. For operating-day arithmetic — TOU period boundaries, billing days, "next 24 hours" — ZonedDateTime is the only correct type.

This library is part of an ecosystem-wide ZonedDateTime end-to-end discipline.

Interval boundaries are zone-aware moments

ValueData interval boundaries are exposed only as :tick/beginning and :tick/end — ZonedDateTime values in the client's configured zone. The coercion layer emits no zone-naive LocalDate/LocalTime fields: a bare wall-clock time with no zone is ambiguous, and in v2.0 the wire delivers these fields in UTC. Composing them into a ZonedDateTime (UTC → configured zone, instant preserved) keeps every boundary self-describing. Need a wall-clock date or time? Derive it from the tick: (.toLocalTime tick), or (.toLocalDate (.withZoneSameInstant tick (java.time.ZoneId/of "UTC"))) for the wire-UTC calendar date.

:midas/zone on responses

Each client/get-* fn annotates its response with :midas/zone — the coercion helpers (entities/rate-info, entities/rin-list, entities/historical-data) read it during coercion. If you call those helpers on a synthetic response that lacks :midas/zone, they throw a clear error; for direct coercion you can call the lower-level (entities/->rate-info raw zone) etc. with an explicit ZoneId.

Authentication

MIDAS uses a two-step auth flow:

1. HTTP Basic auth → GET /Token returns a bearer token (valid for 10 minutes)
2. Bearer token → all other endpoints

;; Manual token management
(def token-info (client/get-token "user" "pass"))
;=> {:token "eyJ..." :acquired-at #inst "..." :expires-at #inst "..."}

(client/token-expired? token-info)
;=> false

;; Auto-refreshing client (recommended)
(def c (client/create-auto-client "user" "pass"))
;; Token refreshes transparently — no manual management needed

RIN Parsing

Parse a Rate Identification Number into its component fields:

(entities/parse-rin "USCA-PGPG-TOU4-0000")
;=> {:midas.rin/country "US"
;    :midas.rin/state "CA"
;    :midas.rin/distribution "PG"
;    :midas.rin/energy "PG"
;    :midas.rin/rate "TOU4"
;    :midas.rin/location "0000"}

;; Returns nil for invalid RINs
(entities/parse-rin "not-a-rin")
;=> nil

Add human-readable labels from MIDAS lookup tables:

;; Fetch lookup tables once
(def dist-table (entities/lookup-table (client/get-lookup-table c "Distribution")))
(def energy-table (entities/lookup-table (client/get-lookup-table c "Energy")))
(def lookups {"Distribution" dist-table, "Energy" energy-table})

(entities/annotate-rin (entities/parse-rin "USCA-SDEA-TTOU-0000") lookups)
;=> {:midas.rin/country "US"
;    :midas.rin/state "CA"
;    :midas.rin/distribution "SD"
;    :midas.rin/distribution-name "San Diego Gas and Electric"
;    :midas.rin/energy "EA"
;    :midas.rin/energy-name "Clean Energy Alliance"
;    :midas.rin/rate "TTOU"
;    :midas.rin/location "0000"}

Signal Type Helpers

;; Detect signal type from rate data
(entities/ghg? rate)           ;=> true/false (checks rate-type + unit)
(entities/flex-alert? rate)    ;=> true/false
(entities/flex-alert-active? rate) ;=> true if any value > 0

Metadata

Every coerced entity preserves the original API data as metadata:

(def rate (entities/rate-info resp))

;; Access the original API response
(-> rate meta :midas/raw)
;=> {:RateID "USCA-TSTS-TTOU-TEST" :RateName "CEC TEST24HTOU" ...}

;; Works at every level
(-> rate :midas.rate/values first meta :midas/raw)
;=> {:ValueName "winter off peak" :DateStart "2023-05-01" ...}

Schemas

Malli schemas are published in dedicated namespaces.

midas.entities.schema — Coerced entities (the public contract)

(require '[midas.entities.schema :as schema]
         '[malli.core :as m])

(m/validate schema/RateInfo rate)    ;=> true
(m/validate schema/ValueData value)  ;=> true

;; Available: RateInfo, ValueData, RinListEntry, ParsedRin,
;;            LookupEntry, RateType, SignalType, DayType, UnitType

midas.entities.schema.raw — Raw API shapes

(require '[midas.entities.schema.raw :as raw])

(raw/validate-raw-rate-info (:body resp))    ;=> nil (valid)
(raw/validate-raw-value-data value)          ;=> nil or Malli explanation

;; Available: RateInfo, ValueData, RinListEntry, LookupEntry

API Reference

midas.client

Function	Description
get-token	Authenticate with HTTP Basic, returns token-info map
token-expired?	Check if a token-info is expired (with 30s buffer)
create-anonymous-client	Create an unauthenticated client (v2.0 GET endpoints only)
create-client	Create client with a token string or token-info map
create-auto-client	Create client with auto-refreshing token
token-info	Get current token-info from a client
success?	True if HTTP response is 2xx
body	Extract parsed body from response
get-rin-list	List RINs by signal type (0=All, 1=Rates, 2=GHG, 3=Flex Alert)
get-rate-values	Fetch rate data for a RIN ("alldata" or "realtime")
get-lookup-table	Fetch a reference table (Distribution, Energy, Unit, etc.)
get-historical-data	Fetch archived rate data for a RIN and date range (6-month max)
register	Register a new MIDAS account (auto base64 encodes fields)
routes	List available Martian route names

midas.entities

Function	Description
->rate-info	Coerce a raw RateInfo map (takes raw, zone)
->value-data	Coerce a raw ValueData map (takes raw, zone)
->rin-list-entry	Coerce a raw RIN list entry (takes raw, zone)
->lookup-entry	Coerce a raw LookupEntry
rate-info	Extract + coerce rate info from HTTP response
rin-list	Extract + coerce RIN list from HTTP response
historical-data	Extract + coerce historical rate data
lookup-table	Extract + coerce lookup table entries
ghg?	True if rate-info is a GHG signal
parse-rin	Parse a RIN string into its component fields
annotate-rin	Add human-readable labels from lookup tables to a parsed RIN
flex-alert?	True if rate-info is a Flex Alert
flex-alert-active?	True if a Flex Alert is currently active

REPL Session Example

(require '[midas.client :as client]
         '[midas.entities :as entities]
         '[midas.entities.schema :as schema]
         '[malli.core :as m])

;; Create auto-refreshing client
(def c (client/create-auto-client
         (System/getenv "MIDAS_USERNAME")
         (System/getenv "MIDAS_PASSWORD")))

;; List all rate RINs
(def rin-resp (client/get-rin-list c 1))
(def rins (entities/rin-list rin-resp))
(count rins)
;=> 67266

;; Fetch the test TOU rate
(def rate-resp (client/get-rate-values c "USCA-TSTS-TTOU-TEST" "alldata"))
(def rate (entities/rate-info rate-resp))

(:midas.rate/type rate)
;=> :midas.rate-type/tou

(count (:midas.rate/values rate))
;=> 768

;; Inspect a value interval
(first (:midas.rate/values rate))
;=> #:midas.value{:name "winter off peak"
;                  :price 0.1006M
;                  :unit :midas.unit/dollar-per-kwh
;                  :day-start :midas.day/monday
;                  :day-end :midas.day/monday
;                  :tick/beginning #zoned-date-time "2026-05-01T00:00-07:00[America/Los_Angeles]"
;                  :tick/end       #zoned-date-time "2026-05-01T00:59:59-07:00[America/Los_Angeles]"}

;; Validate against schema
(m/validate schema/RateInfo rate)
;=> true

;; Check Flex Alert status
(def flex-resp (client/get-rate-values c "USCA-FLEX-FXRT-0000" "realtime"))
(def flex (entities/rate-info flex-resp))
(entities/flex-alert? flex)
;=> true
(entities/flex-alert-active? flex)
;=> false  (no active alert)

;; Lookup tables
(def dists (entities/lookup-table (client/get-lookup-table c "Distribution")))
(first dists)
;=> #:midas.lookup{:code "BN" :description "Banning"}

;; Access raw API data via metadata
(-> rate meta :midas/raw :RateType)
;=> "TOU"

Development

Start nREPL

clojure -M:nrepl
# nREPL port written to .nrepl-port

Requires MIDAS_USERNAME and MIDAS_PASSWORD environment variables.

Dev helpers

The dev/user.clj namespace provides REPL convenience functions:

(start!)   ; create auto-refreshing client from env vars

Run tests

# Unit tests only (fast, no network)
clojure -M:test -m kaocha.runner --focus :unit

# Integration tests (hits live API, needs credentials)
clojure -M:test -m kaocha.runner --focus :integration

# All tests
clojure -M:test -m kaocha.runner

Changelog

Release history and behavioral changes are tracked in CHANGELOG.md. The 1.0.0 release tracks the breaking MIDAS v2.0 API — see doc/v2-migration.md.

Contributing

Issues, Discussions, and pull requests are welcome — see CONTRIBUTING.md for the workflow (and the dev commands: tests, integration tests, lint, nREPL). In short:

• Questions, API/design discussion, MIDAS behavior gaps → Discussions
• Confirmed bugs, coercion/schema fixes, doc errors → Issues
• Patches → pull requests; please open a Discussion or Issue first for non-trivial changes (new endpoints, new schema fields, new coercion behavior, time-handling changes)

License

MIT License -- Copyright (c) 2026 Clark Communications Corporation