API Reference
Utilities API
Match utility names and browse the utility catalog via the EIA-backed API.
List Utilities
GET /api/v1/utilities/list
Browse and search available utilities with filters and pagination.
Authentication
Bearer token required. See Authentication.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
state | string | No | Two-letter state code filter |
type | string | No | Ownership type. One of: iou, cooperative, municipal, political_subdivision, state, federal |
query | string | No | Free-text search (max 200 chars) |
limit | number | No | Results per page (1-200, default 50) |
offset | number | No | Pagination offset (default 0) |
Example
curl "https://gridwonk.com/api/v1/utilities/list?state=CA&type=iou&limit=10" \
-H "Authorization: Bearer $GRIDBOOST_API_KEY"Match Utility
POST /api/v1/utilities/match
Match a user-provided utility name to an official EIA (Energy Information Administration) utility record. Matching is deterministic: the route uses database-backed slugs, display names, search aliases, state narrowing, and normalized text comparison. It does not call an LLM.
- Deterministic: The same stored utility input returns the same official record.
- Fast: Common names, aliases, and normalized matches resolve from stored catalog data.
- Capped: Each organization has a daily unique-utility lookup cap for match requests.
Authentication
Bearer token required. See Authentication.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Utility name to match (1–500 characters). Supports common abbreviations (e.g. PG&E, NES, Con Ed). |
state | string | No | Two-letter state code (e.g. NC, CA). Narrows candidates for multi-state utilities. |
Response Shape
{
"match": {
"eiaId": 5416,
"name": "Duke Energy Carolinas, LLC",
"confidence": 0.95
},
"utility": {
"eiaId": 5416,
"name": "Duke Energy Carolinas, LLC",
"ownershipType": "Investor-Owned",
"states": ["NC", "SC"],
"rtoIso": "SERC"
},
"fromCache": false
}Response Fields
| Field | Type | Description |
|---|---|---|
match.eiaId | number | null | EIA utility ID, or null if no match found. |
match.name | string | null | Matched utility name, or null if no match. |
match.confidence | number | Numeric confidence score: 0.95, 0.7, 0.3, or 0. |
utility | object | null | Full utility details when a match is found. null otherwise. |
utility.eiaId | number | EIA utility ID. |
utility.name | string | Official utility name from EIA records. |
utility.ownershipType | string | Ownership classification (e.g. Investor-Owned, Municipal, Cooperative). |
utility.states | string[] | All states where this utility operates. |
utility.rtoIso | string | null | Regional transmission organization or ISO, or null when none is stored. |
fromCache | boolean | Whether the response was served from a stored prior match. |
Confidence Levels
| Score | Meaning |
|---|---|
0.95 | Exact, alias, or high-confidence stored match. |
0.7 | Likely correct, usually from partial or narrowed candidate matching. |
0.3 | Best-effort low-confidence match. Verify before using in workflows. |
0 | No reasonable match found in the EIA dataset. |
Multi-State Utilities
Many utilities operate across multiple states. Providing the state parameter helps disambiguate:
# Without state — could match any Duke Energy entity
curl -X POST https://gridwonk.com/api/v1/utilities/match \
-H "Authorization: Bearer $GRIDBOOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Duke Energy"}'
# With state — narrows to Duke Energy Indiana
curl -X POST https://gridwonk.com/api/v1/utilities/match \
-H "Authorization: Bearer $GRIDBOOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Duke Energy", "state": "IN"}'Example
curl -X POST https://gridwonk.com/api/v1/utilities/match \
-H "Authorization: Bearer $GRIDBOOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "PG&E", "state": "CA"}'