{
  "anchors": [],
  "capability": "power.demand_rollup",
  "codebooks": {
    "respondent": {
      "codes": {
        "CAL": {
          "label": "California",
          "level": "region"
        },
        "CAR": {
          "label": "Carolinas",
          "level": "region"
        },
        "CENT": {
          "label": "Central",
          "level": "region"
        },
        "FLA": {
          "label": "Florida",
          "level": "region"
        },
        "MIDA": {
          "label": "Mid-Atlantic",
          "level": "region"
        },
        "MIDW": {
          "label": "Midwest",
          "level": "region"
        },
        "NE": {
          "label": "New England",
          "level": "region"
        },
        "NW": {
          "label": "Northwest",
          "level": "region"
        },
        "NY": {
          "label": "New York",
          "level": "region"
        },
        "SE": {
          "label": "Southeast",
          "level": "region"
        },
        "SW": {
          "label": "Southwest",
          "level": "region"
        },
        "TEN": {
          "label": "Tennessee",
          "level": "region"
        },
        "TEX": {
          "label": "Texas",
          "level": "region"
        },
        "US48": {
          "label": "United States Lower 48",
          "level": "national"
        }
      },
      "coverage": "complete_for_gated_eia930_rollup_rows",
      "note": "EIA's published demand respondents: US48 (the Lower-48 national total) and the 13 EIA regions. demand_mw is already each respondent's published total, so summing across respondents double-counts (US48 contains the 13 regions) \u2014 group_by respondent for the per-respondent series; a multi-respondent result carries a respondent_aggregation note. An EIA region is a grid grouping, not a state. A region named like a state is not guaranteed to equal it: TEX ('Texas') is the ERCOT grid alone \u2014 ~90% of Texas load \u2014 while non-ERCOT El Paso, the Panhandle, and East Texas fall in OTHER EIA regions. Some regions span several states (NE = New England's six; CAR = the Carolinas; MIDA \u2248 the PJM footprint); others nearly match their namesake (NY \u2248 New York via NYISO). Use respondent for a region/grid total and a state-grain source (power.retail_sales) for a jurisdiction. When a phrase like 'Texas demand' is ambiguous between the EIA region and the state, report both readings rather than guessing (PD-035).",
      "semantics": "eia930_published_demand_respondent",
      "source": "EIA-930 reference table Regions sheet (the block's sha-pinned reference input)."
    }
  },
  "data_point": {
    "does_not_answer": [
      "balancing-authority-level demand (that is power.demand / EIA-930 BALANCE; this block serves only EIA's published US48 + region rollups)",
      "summing demand across respondents \u2014 US48 already contains the 13 regions, so a national+region sum double-counts (refused with a scope note, never computed)",
      "demand before 2019-01-01 (this API route's history floor; power.demand reaches 2015 H2 at BA grain)",
      "the raw (un-Adjusted) demand series \u2014 the route publishes the Adjusted series only",
      "plant, generator, county, state, or lat/lon attribution (structural \u2014 the rollup carries no such IDs)",
      "installed capacity (EIA-860M), monthly plant generation (EIA-923), retail sales (EIA-861), prices, transmission",
      "long-horizon demand forecasts (the EIA forecast is day-ahead only)",
      "finality (the most recent hours are preliminary and continuously revised)"
    ],
    "grain": "respondent_hourly",
    "id": "power.demand_rollup",
    "note": "This is EIA's OWN published rollup total per respondent (US48 = national, the 13 EIA regions = sub-national), the Adjusted series served verbatim \u2014 it closes power.demand's PD-021 refusal of national/region totals. It is NOT additive across respondents: US48 already contains the regions.",
    "product_spec": "blocks/power_demand_rollup/card.md",
    "represented_fact": "EIA-930 reports hourly observed electricity demand (MW) as EIA's OWN published rollup totals \u2014 US48 (the Lower-48 national total) and the 13 EIA regions \u2014 the Adjusted series (same canonical definition as power.demand's demand_mw, verified against imputed hours), plus the same hour's day-ahead demand forecast. This is EIA's published total served verbatim as a cited atom, NOT a sum exascale computed and NOT the BA series \u2014 it closes power.demand's PD-021 refusal of national/region totals. History begins 2019-01-01 (this API route is ~3.5 years shorter than power.demand's BA history).",
    "source_basis": [
      "energy.eia.eia930_rollup"
    ],
    "source_decisions": [
      "docs/sources/energy/eia/eia930_rollup/build-plan.md"
    ]
  },
  "input": {
    "controls": [
      "include_records",
      "include_evidence",
      "limit",
      "order_by",
      "top_n",
      "order",
      "rollup_other"
    ],
    "date_range_params": [
      "data_date_from",
      "data_date_to"
    ],
    "date_ranges": [
      "data_date"
    ],
    "field_metadata": {},
    "filters": [
      "as_of",
      "respondent",
      "data_date",
      "hour_number"
    ],
    "group_by": [
      "respondent",
      "respondent_level",
      "data_date",
      "hour_number",
      "datetime_utc"
    ],
    "ranking": {
      "no_ranking": "Omit order_by and top_n to return all groups in group-key order.",
      "order": {
        "default": "desc",
        "valid_values": [
          "desc",
          "asc"
        ]
      },
      "order_by": {
        "accepts": "one of output.metrics",
        "note": "Ranks the groups by a metric (a measure). Not a group_by dimension \u2014 rows already come back grouped by each group_by field.",
        "requires": [
          "group_by"
        ],
        "valid_values": [
          "demand_mw",
          "demand_forecast_mw",
          "source_record_count"
        ]
      },
      "top_n": {
        "note": "Keeps the top N groups by order_by; the rest fold into one (other) remainder (additive metrics sum into it, non-additive ones are nulled) so the result still reconciles to summary.totals.",
        "requires": [
          "group_by",
          "order_by"
        ],
        "type": "positive integer"
      }
    }
  },
  "output": {
    "aggregate_citation_fields": [
      "source_id",
      "publisher",
      "source_url",
      "source_file",
      "raw_file_sha256",
      "as_of",
      "source_rows_count",
      "source_rows_sample",
      "verify",
      "lineage_filter"
    ],
    "citation_fields": [
      "source_id",
      "source_url",
      "source_file",
      "sheet",
      "source_row",
      "raw_file_sha256",
      "as_of"
    ],
    "detail_fields": [
      "source_id",
      "sheet_name",
      "source_record_key",
      "report_period",
      "respondent",
      "respondent_level",
      "data_date",
      "hour_number",
      "datetime_utc",
      "demand_mw",
      "demand_forecast_mw",
      "source_row_number",
      "as_of",
      "raw_file_sha256",
      "citation"
    ],
    "metric_groups": {
      "demand_mw": [
        "demand_mw",
        "demand_forecast_mw"
      ],
      "records": [
        "source_record_count"
      ]
    },
    "metric_metadata": {
      "demand_forecast_mw": {
        "additive_across_groups": false,
        "aggregation": "sum",
        "authoritative_total_path": "summary.totals.demand_forecast_mw",
        "category": "demand_mw",
        "definition": "EIA's published day-ahead hourly demand forecast (MW) for the same respondent-hour.",
        "description": "The same respondent-hour's day-ahead demand forecast \u2014 forecast-vs-actual misses need no second query. Same inverted non-additivity as demand_mw (it is itself a published total).",
        "display_name": "Day-ahead demand forecast",
        "display_precision": "MW values are rounded to 6 decimal places in JSON to remove binary floating-point noise.",
        "grain": "respondent hour",
        "null_handling": "Null source values are ignored by the sum; a matched group with only null source values returns null; an empty-query summary returns zero.",
        "rollup_behavior": "non_additive_measure",
        "row_metric_path": "rows[].metrics.demand_forecast_mw",
        "source_fields": [
          "demand_forecast_mw"
        ],
        "unit": "MW"
      },
      "demand_mw": {
        "additive_across_groups": false,
        "aggregation": "sum",
        "authoritative_total_path": "summary.totals.demand_mw",
        "category": "demand_mw",
        "definition": "EIA's published hourly demand total (MW, Adjusted series) for the respondent in scope \u2014 US48 (the Lower-48 national total) or one of the 13 EIA regions.",
        "description": "EIA's OWN published demand total per respondent-hour (the Adjusted series \u2014 same definition as power.demand's demand_mw \u2014 served verbatim, NOT a sum exascale computed). This closes power.demand's PD-021 refusal of national/region totals. NOT additive across respondents: US48 already equals the sum of the 13 regions, so a result spanning more than one respondent carries a respondent_aggregation scope note and ranking remainders omit the demand metrics \u2014 filter respondent=US48 for the national total, or group_by respondent for the per-respondent series.",
        "display_name": "Demand (published total)",
        "display_precision": "MW values are rounded to 6 decimal places in JSON to remove binary floating-point noise.",
        "grain": "respondent hour",
        "null_handling": "A respondent-hour EIA did not publish is absent (a gap, flagged), never zero; an empty-query summary returns zero.",
        "rollup_behavior": "non_additive_measure",
        "row_metric_path": "rows[].metrics.demand_mw",
        "source_fields": [
          "demand_mw"
        ],
        "unit": "MW"
      },
      "source_record_count": {
        "additive_across_groups": true,
        "aggregation": "count source records",
        "authoritative_total_path": "summary.totals.source_record_count",
        "category": "records",
        "definition": "Count of normalized source records (respondent-hours) contributing to the current result scope.",
        "description": "Number of normalized EIA region-data source records (respondent-hours) contributing to the value.",
        "display_name": "Source record count",
        "display_precision": "Integer.",
        "grain": "source row",
        "null_handling": "Always an integer count.",
        "rollup_behavior": "additive_partition_metric",
        "row_metric_path": "rows[].metrics.source_record_count",
        "source_fields": [
          "source_record_key"
        ],
        "unit": "count"
      }
    },
    "metrics": [
      "demand_mw",
      "demand_forecast_mw",
      "source_record_count"
    ],
    "summary_fields": [
      "group_count",
      "totals"
    ]
  },
  "primitive": "query_power_demand_rollup_v1",
  "status": "available"
}