{
  "anchors": [
    {
      "about": "2-letter state/jurisdiction code (PD-003).",
      "format": "usps_state",
      "kind": "geography",
      "name": "state",
      "scope": "universal"
    }
  ],
  "capability": "natural_gas.prices",
  "codebooks": {},
  "data_point": {
    "does_not_answer": [
      "plant-level fuel prices or fuel-receipt costs",
      "regional licensed hub indices such as Katy, Houston Ship Channel, or Waha",
      "dollars per MWh, spark spreads, heat rates, or generation costs",
      "conversions between dollars per Mcf and dollars per MMBtu",
      "proxy assignment to any generator or fleet"
    ],
    "grain": "series_period",
    "id": "natural_gas.prices",
    "product_spec": "blocks/natural_gas_prices/card.md",
    "represented_fact": "EIA publishes the daily Henry Hub natural-gas spot price in dollars per MMBtu and monthly state-average natural-gas prices paid by electric-power consumers in dollars per Mcf. The state series is an aggregate of what the state's power sector paid in that month, not a plant-level price. Source-null state-month values remain explicit nulls and revisions remain separate capture vintages.",
    "source_basis": [
      "energy.eia.natural_gas_prices"
    ],
    "source_decisions": [
      "docs/sources/energy/eia/natural_gas_prices/source-decision.md"
    ]
  },
  "input": {
    "controls": [
      "include_records",
      "include_evidence",
      "limit",
      "order_by",
      "top_n",
      "order"
    ],
    "date_range_params": [
      "date_from",
      "date_to"
    ],
    "date_ranges": [
      "date"
    ],
    "filters": [
      "as_of",
      "atom",
      "series_id",
      "state",
      "date",
      "month",
      "price_status"
    ],
    "group_by": [
      "atom",
      "series_id",
      "state",
      "date",
      "price_status",
      "unit"
    ],
    "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": [
          "avg_price",
          "min_price",
          "max_price",
          "reported_price_count",
          "missing_price_count",
          "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"
    ],
    "atoms": {
      "henry_hub_daily_spot": {
        "grain": "trading day",
        "series_id": "RNGWHHD",
        "unit": "$/MMBtu"
      },
      "state_electric_power_monthly": {
        "grain": "state-month aggregate",
        "important": "An average paid by the state's electric-power sector, not a plant-level price.",
        "unit": "$/Mcf"
      }
    },
    "citation_fields": [
      "source_id",
      "source_url",
      "source_file",
      "sheet",
      "source_row",
      "source_col",
      "series_id",
      "period",
      "raw_file_sha256",
      "as_of"
    ],
    "detail_fields": [
      "source_id",
      "atom",
      "sheet_name",
      "source_record_key",
      "report_period",
      "date",
      "source_period",
      "frequency",
      "grain",
      "state",
      "area_name",
      "duoarea",
      "series_id",
      "series_description",
      "product_code",
      "product_name",
      "process_code",
      "process_name",
      "price_raw",
      "price",
      "unit_raw",
      "unit",
      "price_status",
      "source_row_number",
      "as_of",
      "raw_file_sha256",
      "citation"
    ],
    "metric_groups": {
      "price": [
        "avg_price",
        "min_price",
        "max_price"
      ],
      "records": [
        "reported_price_count",
        "missing_price_count",
        "source_record_count"
      ]
    },
    "metric_metadata": {
      "avg_price": {
        "additive_across_groups": false,
        "aggregation": "average",
        "authoritative_total_path": "summary.totals.avg_price",
        "category": "price",
        "definition": "Average, minimum, or maximum EIA price within a single-unit result scope. Mixed $/MMBtu and $/Mcf scopes return null.",
        "display_name": "Average source-unit price",
        "display_precision": "Numeric values are returned at EIA's published precision.",
        "grain": "EIA series-period record",
        "null_handling": "Source-null records are ignored by avg/min/max; a scope with only nulls, no rows, or mixed source units returns null, never zero.",
        "rollup_behavior": "non_additive_measure",
        "row_metric_path": "rows[].metrics.avg_price",
        "source_fields": [
          "value"
        ],
        "unit": "source physical unit"
      },
      "max_price": {
        "additive_across_groups": false,
        "aggregation": "maximum",
        "authoritative_total_path": "summary.totals.max_price",
        "category": "price",
        "definition": "Average, minimum, or maximum EIA price within a single-unit result scope. Mixed $/MMBtu and $/Mcf scopes return null.",
        "display_name": "Maximum source-unit price",
        "display_precision": "Numeric values are returned at EIA's published precision.",
        "grain": "EIA series-period record",
        "null_handling": "Source-null records are ignored by avg/min/max; a scope with only nulls, no rows, or mixed source units returns null, never zero.",
        "rollup_behavior": "non_additive_measure",
        "row_metric_path": "rows[].metrics.max_price",
        "source_fields": [
          "value"
        ],
        "unit": "source physical unit"
      },
      "min_price": {
        "additive_across_groups": false,
        "aggregation": "minimum",
        "authoritative_total_path": "summary.totals.min_price",
        "category": "price",
        "definition": "Average, minimum, or maximum EIA price within a single-unit result scope. Mixed $/MMBtu and $/Mcf scopes return null.",
        "display_name": "Minimum source-unit price",
        "display_precision": "Numeric values are returned at EIA's published precision.",
        "grain": "EIA series-period record",
        "null_handling": "Source-null records are ignored by avg/min/max; a scope with only nulls, no rows, or mixed source units returns null, never zero.",
        "rollup_behavior": "non_additive_measure",
        "row_metric_path": "rows[].metrics.min_price",
        "source_fields": [
          "value"
        ],
        "unit": "source physical unit"
      },
      "missing_price_count": {
        "additive_across_groups": true,
        "aggregation": "conditional count",
        "authoritative_total_path": "summary.totals.missing_price_count",
        "category": "records",
        "definition": "Count of EIA records whose source value is null.",
        "display_name": "Missing price count",
        "display_precision": "Integer.",
        "grain": "result scope",
        "null_handling": "Always an integer count.",
        "rollup_behavior": "additive_partition_metric",
        "row_metric_path": "rows[].metrics.missing_price_count",
        "source_fields": [
          "value"
        ],
        "unit": "count"
      },
      "reported_price_count": {
        "additive_across_groups": true,
        "aggregation": "conditional count",
        "authoritative_total_path": "summary.totals.reported_price_count",
        "category": "records",
        "definition": "Count of EIA records with a numeric value.",
        "display_name": "Reported price count",
        "display_precision": "Integer.",
        "grain": "result scope",
        "null_handling": "Always an integer count.",
        "rollup_behavior": "additive_partition_metric",
        "row_metric_path": "rows[].metrics.reported_price_count",
        "source_fields": [
          "value"
        ],
        "unit": "count"
      },
      "source_record_count": {
        "additive_across_groups": true,
        "aggregation": "count source records",
        "authoritative_total_path": "summary.totals.source_record_count",
        "category": "records",
        "definition": "Count of EIA series-period records in scope.",
        "display_name": "Source record count",
        "display_precision": "Integer.",
        "grain": "result scope",
        "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": [
      "avg_price",
      "min_price",
      "max_price",
      "reported_price_count",
      "missing_price_count",
      "source_record_count"
    ],
    "missingness": "EIA null remains price=null with price_status=source_missing; never zero or imputed.",
    "revision_policy": "Each API capture is an immutable vintage; as_of selects the latest revision at that cut.",
    "summary_fields": [
      "group_count",
      "totals"
    ]
  },
  "primitive": "query_natural_gas_prices_v1",
  "status": "available"
}