EIA data contract | PatchOps Knowledge

Provenance

PublisherEIA

API basehttps://api.eia.gov/

Freshness & coverage

FreshnessFreshness not declared

GeographicNot declared

TemporalNot declared

AuthenticationCredentials required (API key)

Methods (22)

getRoutes

read

List available EIA routes, optionally within a parent route.

Input schema

{
  "type": "object",
  "properties": {
    "route": {
      "type": "string",
      "description": "Optional parent route to inspect."
    }
  },
  "additionalProperties": true
}

getData

read

Query any EIA dataset route with filters, date bounds, and paging.

Required paramsroute

Input schema

{
  "type": "object",
  "properties": {
    "route": {
      "type": "string",
      "description": "EIA dataset route, e.g. electricity/retail-sales."
    },
    "start": {
      "type": "string",
      "description": "Inclusive start date in YYYY-MM-DD format."
    },
    "end": {
      "type": "string",
      "description": "Inclusive end date in YYYY-MM-DD format."
    },
    "frequency": {
      "type": "string",
      "description": "Frequency such as annual, monthly, quarterly, or daily."
    },
    "facets": {
      "type": "object",
      "description": "Facet filters keyed by facet id."
    },
    "sort": {
      "type": "array",
      "description": "Sort descriptors."
    },
    "offset": {
      "type": "number",
      "description": "Result offset."
    },
    "length": {
      "type": "number",
      "description": "Maximum rows to return."
    }
  },
  "required": [
    "route"
  ],
  "additionalProperties": true
}

getFacets
read
Get available filter options (facets) for a dataset
Required paramsroute
getFacetDetails
read
Get available values for a specific facet
Required paramsroutefacetId

getElectricityData

read

Query a curated EIA electricity dataset.

Required paramsdataset

Input schema

{
  "type": "object",
  "properties": {
    "dataset": {
      "type": "string",
      "description": "Electricity dataset slug, e.g. retail-sales."
    },
    "start": {
      "type": "string",
      "description": "Inclusive start date in YYYY-MM-DD format."
    },
    "end": {
      "type": "string",
      "description": "Inclusive end date in YYYY-MM-DD format."
    },
    "frequency": {
      "type": "string",
      "description": "Optional frequency override."
    },
    "facets": {
      "type": "object",
      "description": "Facet filters keyed by facet id."
    },
    "length": {
      "type": "number",
      "description": "Maximum rows to return."
    }
  },
  "required": [
    "dataset"
  ],
  "additionalProperties": true
}

getNaturalGasData

read

Query a curated EIA natural gas dataset.

Required paramsroute1

Input schema

{
  "type": "object",
  "properties": {
    "route1": {
      "type": "string",
      "description": "Natural gas route segment, e.g. summary."
    },
    "route2": {
      "type": "string",
      "description": "Optional second route segment."
    },
    "start": {
      "type": "string",
      "description": "Inclusive start date in YYYY-MM-DD format."
    },
    "end": {
      "type": "string",
      "description": "Inclusive end date in YYYY-MM-DD format."
    },
    "facets": {
      "type": "object",
      "description": "Facet filters keyed by facet id."
    },
    "length": {
      "type": "number",
      "description": "Maximum rows to return."
    }
  },
  "required": [
    "route1"
  ],
  "additionalProperties": true
}

getCoalData
read
Convenience function for coal datasets
Required paramsdataset
getPetroleumData
read
Query petroleum prices, production, stocks, supply, or disposition by dataset.
Required paramsdataset
getSTEOData
read
Get Short-Term Energy Outlook (STEO) data
getAEOData
read
Get Annual Energy Outlook (AEO) data
Required paramsroute1
getIEOData
read
Get International Energy Outlook (IEO) data
Required paramsroute1
getSEDSData
read
Get State Energy Data System (SEDS) data
getTotalEnergyData
read
Get Total Energy data
getCO2EmissionsData
read
Get CO2 Emissions data
Required paramsdataset
getInternationalData
read
Get International energy data
getNuclearOutagesData
read
Get Nuclear Outages data
Required paramsdataset

searchGenerators

read

Form 860 generator-level capacity search with state/fuel/BA/status filters.

Input schema

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "description": "Two-letter state code, e.g. TX."
    },
    "fuelType": {
      "description": "Energy source code (NG, COL, NUC, WND, SUN, ...) or array.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "primeMover": {
      "description": "Prime mover code (CT, ST, GT, IC, ...) or array.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "balancingAuthority": {
      "description": "Balancing authority code (ERCO, CISO, MISO, PJM, ...) or array.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "status": {
      "type": "string",
      "description": "Operating status: OP (default), SB, OS, OA. Empty string disables filter."
    },
    "sector": {
      "type": "string",
      "description": "Sector slug (electric-utility, industrial-chp, ...)."
    },
    "minCapacityMw": {
      "type": "number",
      "description": "Filter to generators with nameplate capacity >= this value."
    },
    "start": {
      "type": "string",
      "description": "Inclusive start month YYYY-MM."
    },
    "end": {
      "type": "string",
      "description": "Inclusive end month YYYY-MM."
    },
    "length": {
      "type": "number",
      "description": "Page size (max 5000)."
    },
    "offset": {
      "type": "number",
      "description": "Page offset."
    }
  },
  "additionalProperties": true
}

getPlantGeneration

read

Form 923 monthly net generation and fuel use for a single plant.

Required paramsplantIdstartend

Input schema

{
  "type": "object",
  "properties": {
    "plantId": {
      "description": "Plant ID (EIA plant code).",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        }
      ]
    },
    "start": {
      "type": "string",
      "description": "Start month YYYY-MM."
    },
    "end": {
      "type": "string",
      "description": "End month YYYY-MM."
    },
    "fuelType": {
      "description": "Optional fuel filter (NG, COL, ALL, ...) or array.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "primeMover": {
      "description": "Optional prime mover filter (ST, CT, ALL, ...) or array.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "frequency": {
      "type": "string",
      "enum": [
        "monthly",
        "quarterly",
        "annual"
      ],
      "description": "Default monthly."
    },
    "length": {
      "type": "number",
      "description": "Page size (max 5000)."
    },
    "offset": {
      "type": "number",
      "description": "Page offset."
    }
  },
  "required": [
    "plantId",
    "start",
    "end"
  ],
  "additionalProperties": true
}

searchPlants

read

One row per plant from Form 860 generators, sorted by total nameplate MW.

Input schema

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string"
    },
    "balancingAuthority": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "fuelType": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "status": {
      "type": "string"
    },
    "sector": {
      "type": "string"
    },
    "limit": {
      "type": "number",
      "description": "Max plants to return (default 50)."
    },
    "start": {
      "type": "string",
      "description": "Snapshot month YYYY-MM."
    },
    "end": {
      "type": "string",
      "description": "Snapshot end month YYYY-MM."
    }
  },
  "additionalProperties": true
}

getRetirementSchedule

read

Generators with planned-retirement-year-month set, sorted ascending.

Input schema

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string"
    },
    "fuelType": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "year": {
      "type": "number",
      "description": "Filter to retirement YYYY."
    },
    "start": {
      "type": "string",
      "description": "Snapshot start month YYYY-MM."
    },
    "end": {
      "type": "string",
      "description": "Snapshot end month YYYY-MM."
    },
    "length": {
      "type": "number",
      "description": "Page size (max 5000)."
    },
    "offset": {
      "type": "number",
      "description": "Page offset."
    }
  },
  "additionalProperties": true
}

getFuelMix

read

Form 923 generation by fuel type for a state or national aggregate.

Required paramstime

Input schema

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string"
    },
    "balancingAuthority": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "time": {
      "type": "string",
      "description": "Period in YYYY-MM (or YYYY for annual)."
    },
    "frequency": {
      "type": "string",
      "enum": [
        "monthly",
        "quarterly",
        "annual"
      ]
    },
    "length": {
      "type": "number"
    }
  },
  "required": [
    "time"
  ],
  "additionalProperties": true
}

getServiceInfo
read
Form 860/923 routes, facets, enum values, date format, and pagination cap.
Input schema
```
{
  "type": "object",
  "properties": {},
  "additionalProperties": true
}
```

EIA

Provenance

Freshness & coverage

Methods (22)

getRoutes

getData

getFacets

getFacetDetails

getElectricityData

getNaturalGasData

getCoalData

getPetroleumData

getSTEOData

getAEOData

getIEOData

getSEDSData

getTotalEnergyData

getCO2EmissionsData

getInternationalData

getNuclearOutagesData

searchGenerators

getPlantGeneration

searchPlants

getRetirementSchedule

getFuelMix

getServiceInfo