GridX API Specifications

Machine-readable specifications for the GridX Calculate APIs, which provide dynamic retail pricing and related energy data for California IOUs.

Disclaimer

These are not official GridX artifacts. The OpenAPI specifications and JSON Schemas in this repository were derived from the publicly available GridX developer documentation and are provided here on a best-effort basis. They may be incomplete, inaccurate, or out of date relative to the actual API behavior.

In an ideal world, API providers would publish machine-readable specifications alongside their documentation — enabling client code generation, automated testing, and robust integrations. Since GridX has not yet seen fit to do so, we have done it for them. You're welcome, GridX.

Repository Layout

apis/
  pricing/
    pge/               # PG&E Pricing API
      openapi.yaml     # OpenAPI 3.1 spec
      schemas/         # JSON Schema (draft 2020-12) files
      examples/        # Sample responses
      data/            # Reference data (circuit ID mapping)
    sce/               # SCE Pricing API
      openapi.yaml     # OpenAPI 3.1 spec
      schemas/         # JSON Schema (draft 2020-12) files
      examples/        # Sample responses
  openadr/             # OpenADR API (authenticated) — not yet specified
  customer-usage/      # Customer Info & Usage API (authenticated) — not yet specified

Each utility's pricing directory follows the same convention:

File/Dir	Purpose
openapi.yaml	OpenAPI 3.1 spec for the utility's pricing endpoint
schemas/	Standalone JSON Schema files for reuse by client libraries and tooling
examples/	Sample request/response JSON for testing

API Overview

API	Auth	Status	Description
Pricing (PG&E)	None (public)	Specified	Dynamic retail prices for PG&E rate schedules
Pricing (SCE)	None (public)	Specified	Dynamic retail prices for SCE rate schedules
OpenADR	Token	Planned	Programs and subscription management for automated price feeds
Customer Usage	Token	Planned	Customer account info and usage data

See the GridX documentation for the upstream API docs:

• PG&E Pricing
• SCE Pricing

Utility Differences

The PG&E and SCE pricing APIs share the same response structure (meta/data/priceHeader/priceDetails/priceComponents) but differ in parameters and component vocabulary:

Aspect	PG&E	SCE
API Base URL	pge-pe-api.gridx.com or pe-api.gridx.com	pe-api.gridx.com
Utility param	PGE	SCE
Circuit param	representativeCircuitId (9-digit feeder IDs; see circuit locations)	representativeCircuitId (substation names, e.g. "System")
Rate names	AG-A1, B6, EELEC, EV2AS, ...	TOU-GS-1, TOU-EV-9S, TOU-PRIME, ...
Components	3: cld, mec, mgcc	8: abank, bbank, circuitpricecurve, mec, nbc, ppf, ramp, transmissionpricecurve
Price types	generation, distribution	generation, distribution, nonbypassablecharge, transmission
CCA support	Yes (optional cca param)	No
Data available from	2024-06-01	2025-07-01

PG&E Circuit ID Mapping

PG&E's representativeCircuitId is a 9-digit distribution feeder identifier that encodes region, division, substation, and feeder number. PG&E presents customers with a dropdown of these opaque numbers with no explanation of what or where they are.

The file apis/pricing/pge/data/pge-circuit-locations.json maps all 98 known circuit IDs to their locations. Examples:

Circuit ID	Region	Division	Substation	Feeder
013532223	Bay Area	Diablo	LAKEWOOD	2223
082031112	South Bay and Central Coast	De Anza	MOUNTAIN VIEW	1112
252051104	Central Valley	Fresno	ASHLAN AVENUE	1104

Of the 98 circuits, 59 are confirmed available via the GridX API; the remaining 39 (all Sacramento-area) are from the CPUC filing but have not been verified against the API and are marked inGridxEnum: false.

Sources:

• PG&E 2022 Grid Needs Assessment (CPUC filing 496629893, Appendix D)
• Priicer community cross-reference

Known GridX Documentation Errors

The following discrepancies were discovered between the GridX SCE developer docs and the actual API behavior (verified 2026-03-21):

• Circuit parameter name: The docs list the SCE query parameter as representativeCircuit, but the API actually requires representativeCircuitId (same as PG&E). Requests using representativeCircuit return a 400 error: "Representative Circuit ID cannot be empty."
• SCE-specific hostname: The docs show sce-api-prod.gridx.com as the base URL, but this hostname does not resolve in DNS. SCE requests work on the shared pe-api.gridx.com hostname (same as PG&E), differentiated by the utility=SCE query parameter.

Our specs reflect the actual API behavior, not the documentation.

Validation

# Lint the PG&E OpenAPI spec
npx @redocly/cli lint apis/pricing/pge/openapi.yaml

# Lint the SCE OpenAPI spec
npx @redocly/cli lint apis/pricing/sce/openapi.yaml

# Validate PG&E sample JSON against the JSON Schema (Python)
pip install jsonschema referencing
python -c "
import json
from pathlib import Path
from referencing import Registry, Resource
from jsonschema import Draft202012Validator

schema_dir = Path('apis/pricing/pge/schemas')
store = {}
for f in schema_dir.glob('*.schema.json'):
    schema = json.loads(f.read_text())
    store[schema['\$id']] = Resource.from_contents(schema)

registry = Registry().with_resources(store.items())
response_schema = json.loads((schema_dir / 'gridx-pricing-response.schema.json').read_text())
sample = json.loads(Path('apis/pricing/pge/examples/pge-pricing-response-sample.json').read_text())

validator = Draft202012Validator(response_schema, registry=registry)
validator.validate(sample)
print('PG&E: OK')
"

# Validate SCE sample JSON against the JSON Schema (Python)
python -c "
import json
from pathlib import Path
from referencing import Registry, Resource
from jsonschema import Draft202012Validator

schema_dir = Path('apis/pricing/sce/schemas')
store = {}
for f in schema_dir.glob('*.schema.json'):
    schema = json.loads(f.read_text())
    store[schema['\$id']] = Resource.from_contents(schema)

registry = Registry().with_resources(store.items())
response_schema = json.loads((schema_dir / 'gridx-pricing-response.schema.json').read_text())
sample = json.loads(Path('apis/pricing/sce/examples/sce-pricing-response-sample.json').read_text())

validator = Draft202012Validator(response_schema, registry=registry)
validator.validate(sample)
print('SCE: OK')
"

License

MIT License — Copyright (c) 2026 Clark Communications Corporation