NatLabRockies · harish-panneerselvam · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026
diff --git a/.env.example b/.env.example
@@ -0,0 +1,10 @@
+# EIA Open Data API key (required for zipcode-based fuel price lookups)
+# Register at https://www.eia.gov/opendata/register.php
+# When a US zipcode is set in the Config region column, T3CO auto-discovers
+# the latest AEO publication year and fetches region-specific fuel prices.
+T3CO_EIA_API_KEY=your_api_key_here
+
+# SSL verification for EIA API requests.
+# Set to "false" to disable (e.g. behind a corporate proxy with SSL inspection),
+# or set to a path to a custom CA bundle file.
+# T3CO_SSL_VERIFY=false
diff --git a/.gitignore b/.gitignore
@@ -28,6 +28,7 @@
 *.Rhistory
 *venv*
 *.DS_Store
+.env
 t3co/resources/T3CO_Config_Local.csv
 /site
 /tco_results

diff --git a/README.md b/README.md
@@ -114,6 +114,35 @@ Point the `--config` argument to the `T3COConfig.csv` file path (either the src/
 
 Additional information on the inputs, the Batch Mode feature, other CLI arguments, and description of T3CO results are mentioned in the [Quick Start Guide](./docs/quick_start.md)
 
+### EIA Fuel Price Projections
+
+T3CO can fetch fuel price projections directly from the [EIA Annual Energy Outlook (AEO)](https://www.eia.gov/outlooks/aeo/) API instead of relying on the static `FuelPrices.csv` file. When a US zipcode is provided in the `region` column of the Config file (or in the Scenario file), T3CO automatically:
+
+1. Discovers the **latest** AEO publication year available from the EIA API (e.g. AEO 2025)
+2. Identifies the **reference case** scenario for that year
+3. Resolves the zipcode to the corresponding **US Census division** (e.g. `90210` → Pacific)
+4. Fetches region-specific fuel price projections for diesel, gasoline, electricity, and CNG
+5. Falls back to `FuelPrices.csv` for hydrogen (not available in AEO)
+
+To enable this feature:
+
+1. Register for a free API key at [eia.gov/opendata/register.php](https://www.eia.gov/opendata/register.php)
+2. Create a `.env` file in your project root (see `.env.example`):
+   ```
+   T3CO_EIA_API_KEY=your_api_key_here
+   ```
+3. Set the `region` column in `T3COConfig.csv` to a US zipcode (e.g. `90210`)
+4. Ensure the `eia_fuel_prices` toggle is enabled in `cost_toggles.json` (default: `true`)
+
+To pin a specific AEO year instead of using the latest, set `eia_aeo_year` and `eia_aeo_case` in the Config CSV or via CLI:
+```bash
+python -m t3co.cli.sweep --analysis-id=5 --eia-aeo-year=2023 --eia-aeo-case=aeo2022ref
+```
+
+If no zipcode is provided or the toggle is disabled, T3CO uses the static `FuelPrices.csv` as before.
+
+Fuel price override workflows that use `--fuel-prices-json` and `--fuel-prices-zipcode` resolve the source fuel-price region from the installed `zipcodes` dependency instead of repository-maintained ZIP range tables.
+
 ## Acknowledgements
 
 This tool was developed with funding support from the US Department of Energy's Office of Energy Efficiency and Renewable Energy (EERE)'s Vehicle Technology Office.
@@ -128,4 +157,4 @@ DOE NREL Software Record: [SWR-21-54](https://doi.org/10.11578/dc.20240806.4)
 ## Contact Us
 To reach out to the NREL developer team with feedback, feature requests, or to explore partnership opportunities, please email at [T3CO@nrel.gov](mailto:T3CO@nrel.gov)
 
-This tool is developed and maintained by the Commercial Vehicle Technologies (CVT) team in NREL's Center for Integrated Mobility Sciences.
+This tool is developed and maintained by the Commercial Vehicle Technologies (CVT) team in NREL's Center for Integrated Mobility Sciences.
diff --git a/docs/T3CO_Overview.md b/docs/T3CO_Overview.md
@@ -16,7 +16,8 @@ Generally speaking, T3CO can be used in two ways:
 
 There are a few main components of a vehicle's total cost of ownership: MSRP (the cost of the vehicle at time of purchase), fuel costs (based on $ per gallon of gasoline equivalent for every operational year's fuel used, other operating costs maintenance [\$/mile\]), fueling dwell time labor [\$/hr], opportunity cost for payload loss and downtime, and resale value at end of ownership.
 
-Fuel costs are computed after determining the vehicle energy efficiency (e.g. miles per gallon of fuel) and factoring in the annual miles driven and the fuel price for each year and region where the vehicle operates.
+Fuel costs are computed after determining the vehicle energy efficiency (e.g. miles per gallon of fuel) and factoring in the annual miles driven and the fuel price for each year and region where the vehicle operates. Fuel prices can be sourced from a static CSV file or fetched dynamically from the [EIA Annual Energy Outlook (AEO)](https://www.eia.gov/outlooks/aeo/) API when a US zipcode is provided in the Config or Scenario `region` field. When using the EIA API, T3CO auto-discovers the latest AEO publication year and retrieves region-specific price projections for diesel, gasoline, electricity, and CNG.
+
 The performance metrics estimated for the vehicle are: miles of range, acceleration time, and gradeability.
 
 More details on performance metrics are included below under [optimization flow](#optimization-flow). If the analysis does not include optimization, these metrics are simply reported in the results.

diff --git a/docs/pages/config_inputs_descriptions.md b/docs/pages/config_inputs_descriptions.md
@@ -224,6 +224,34 @@
             <td>Override boolean switch for   maintenance and repair downtime opportunity cost calculations- if left blank,   T3CO uses selection specific switch</td>
             <td>bool</td>
         </tr>
+        <tr>
+            <td>fuel_prices_file</td>
+            <td>Fuel Prices Filepath</td>
+            <td></td>
+            <td>Filepath to auxiliary fuel prices CSV file, either absolute or relative to /resources/ folder</td>
+            <td>string</td>
+        </tr>
+        <tr>
+            <td>region</td>
+            <td>Fuel Price Region or Zipcode</td>
+            <td></td>
+            <td>Region identifier for fuel prices. If set to a 5-digit US zipcode (e.g. 90210) and the <code>eia_fuel_prices</code> toggle is enabled, T3CO fetches fuel price projections from the EIA AEO API for the corresponding census division. If left blank, T3CO uses the scenario-level region to look up prices from the static FuelPrices.csv file.</td>
+            <td>string/int</td>
+        </tr>
+        <tr>
+            <td>eia_aeo_year</td>
+            <td>EIA AEO Publication Year</td>
+            <td></td>
+            <td>AEO publication year to query from the EIA API (e.g. &quot;2023&quot;, &quot;2025&quot;). If left blank, T3CO auto-discovers the latest available AEO year.</td>
+            <td>string</td>
+        </tr>
+        <tr>
+            <td>eia_aeo_case</td>
+            <td>EIA AEO Scenario Case</td>
+            <td></td>
+            <td>AEO scenario case ID to query (e.g. &quot;aeo2023ref&quot;). If left blank, T3CO auto-discovers the reference case for the resolved AEO year.</td>
+            <td>string</td>
+        </tr>
     </tbody>
 </table>
 </div>
diff --git a/docs/pages/cost_and_tool_features.md b/docs/pages/cost_and_tool_features.md
@@ -18,6 +18,10 @@
 - *Fueling Dwell Labor cost*
 - All operating costs are discounted year over year to account for time value of money
 
+#### EIA Fuel Price Projections
+
+When a US zipcode is provided in the Config or Scenario `region` field, T3CO can fetch fuel price projections from the EIA Annual Energy Outlook (AEO) API. The system auto-discovers the latest AEO publication year and reference scenario, resolves the zipcode to a US Census division, and retrieves region-specific nominal prices for diesel, gasoline, electricity, and CNG. Hydrogen prices fall back to the static `FuelPrices.csv`. This feature requires a free EIA API key and is controlled by the `eia_fuel_prices` toggle in `cost_toggles.json`.
+
 ### Opportunity Cost Components
 
 - *Lost Payload Capacity Cost*: Cost of fractionally additional advanced powertrain vehicles needed to carry the same payload as a conventional one (only for Class 8)
@@ -48,5 +52,5 @@
 - Labor Cost as an operating cost component
 - Grants incentives, registration, title, and recurring fees added as Capital and Operating Cost components
 - Battery replacement and battery degradation accounted for in Operating Costs and Energy calculations
-- Regionalized fuel, registration, and labor cost inputs
+- ~~Regionalized fuel, registration, and labor cost inputs~~ (fuel prices: available via EIA API integration)
 - Option to run RouteE for Energy calculations
diff --git a/docs/quick_start.md b/docs/quick_start.md
@@ -58,73 +58,58 @@ Use the command below to get a list of all CLI arguments:
 python -m t3co.cli.sweep --help
 ```
 
+### EIA Fuel Price Projections
+
+T3CO can fetch fuel price projections directly from the EIA Annual Energy Outlook (AEO) API. This replaces the static `FuelPrices.csv` data with the latest AEO projections for a region matching the provided US zipcode.
+
+**Setup:**
+1. Get a free EIA API key from [eia.gov/opendata/register.php](https://www.eia.gov/opendata/register.php)
+2. Add it to a `.env` file in your project root:
+   ```
+   T3CO_EIA_API_KEY=your_api_key_here
+   ```
+
+**Usage:** Set the `region` column in `T3COConfig.csv` to a 5-digit US zipcode. T3CO will auto-discover the latest AEO year, resolve the zipcode to a US Census division, and fetch fuel prices for that region.
+
+```bash
+python -m t3co.cli.sweep --analysis-id=5
+```
+
+The same zipcode-based resolution also works at the Scenario level — if a scenario's `region` field contains a zipcode and the config didn't already resolve one, T3CO fetches EIA data for that scenario.
+
+To override the AEO year or scenario (instead of using the latest):
+```bash
+python -m t3co.cli.sweep --analysis-id=5 --eia-aeo-year=2023 --eia-aeo-case=aeo2022ref
+```
+
+The `eia_fuel_prices` toggle in `cost_toggles.json` controls whether EIA lookups are enabled (default: `true`). If the toggle is `false` or no zipcode is provided, T3CO falls back to the static `FuelPrices.csv`.
+
+### Fuel Price Overrides
+
+For fuel-price sensitivity work, `--fuel-prices-json` accepts a JSON string or file path with `zipcode` and `fuel_prices` keys. T3CO uses the installed `zipcodes` package to resolve that ZIP code into the base fuel-price region before cloning and overriding the matching rows in `FuelPrices.csv`.
+
+```bash
+python -m t3co.cli.sweep \
+  --analysis-id=0 \
+  --fuel-prices-json='{"zipcode":"80302","fuel_prices":{"diesel_dol_per_gal":{"2025":4.25}}}'
 ```
-$ python -m t3co.cli.sweep --help
-usage: SWEEP [-h] [--config CONFIG] [--analysis-id ANALYSIS_ID] [--vehicles VEHICLES] [--scenarios SCENARIOS] [--selections [SELECTIONS ...]] [--drive-cycle [DRIVE_CYCLE ...]]
-             [--eng-curves ENG_CURVES] [--lw-curves LW_CURVES] [--aero-curves AERO_CURVES] [--look-for LOOK_FOR] [--skip-all-opt] [--skip-input-validation] [--exclude [EXCLUDE ...]]
-             [--algorithms [ALGORITHMS ...]] [--dst-dir DST_DIR] [--dir-mark DIR_MARK] [--file-mark FILE_MARK] [--skip-save-veh] [--x-tol X_TOL] [--f-tol F_TOL] [--n-max-gen N_MAX_GEN]
-             [--pop-size POP_SIZE] [--nth-gen NTH_GEN] [--n-last N_LAST] [--range-overshoot-tol RANGE_OVERSHOOT_TOL] [---missed-trace-correction] [--max-time-dilation MAX_TIME_DILATION]
-             [--min-time-dilation MIN_TIME_DILATION] [--time-dilation-tol TIME_DILATION_TOL] [--write-tsv WRITE_TSV] [--run-multi] [--n-processors N_PROCESSORS]
-
-The sweep.py module is the main script to run T3CO
-
-options:
-  -h, --help            show this help message and exit
-  --config CONFIG       Input Config file (default: ./src/t3co/resources/T3COConfig.csv)
-  --analysis-id ANALYSIS_ID
-                        Analysis key from input Config file - 'config.analysis_id' (default: 0)
-  --vehicles VEHICLES   Input file for Vehicle models (default: ./src/t3co/resources/inputs/Demo_FY22_vehicle_model_assumptions.csv)
-  --scenarios SCENARIOS
-                        Input file for Scenario models (default: ./src/t3co/resources/inputs/Demo_FY22_scenario_assumptions.csv)
-  --selections [SELECTIONS ...]
-                        Selections desired to run. Selections can be an int, or list of ints, or range expression. Ex: --selections 234 or --selections "[234,236,238]" or --selections
-                        "range(234, 150, 2)" (default: None)
-  --drive-cycle [DRIVE_CYCLE ...]
-                        Override drive_cycle from scenario with a composite cycle, or an individual cycle, or a folder of cycles. File paths should be relative to the resources folder (default:
-                        None)
-  --eng-curves ENG_CURVES
-                        Input file for engine efficiency improvement cost curves (default: ./src/t3co/resources/auxiliary/EngineEffImprovementCostCurve.csv)
-  --lw-curves LW_CURVES
-                        Input file for lightweighting improvement cost curves (default: ./src/t3co/resources/auxiliary/LightweightImprovementCostCurve.csv)
-  --aero-curves AERO_CURVES
-                        Input file for aerodynamics improvement curves (default: ./src/t3co/resources/auxiliary/AeroDragImprovementCostCurve.csv)
-  --look-for LOOK_FOR   A string for string matching, example --look_for 'FCEV' or -look_for '["FCEV", "HEV"]' (default: )
-  --skip-all-opt, --skopt
-                        If --skip_all_opt used, all runs skip optimization (default: False)
-  --skip-input-validation, --skiv
-                        If --skip_input_validation used, no pre-validation of inputs is run before sweep commences (default: True)
-  --exclude [EXCLUDE ...]
-                        Overrides -look_for. a string for string matching to exclude runs, example -exclude 'FCEV' or -look_for '["FCEV", "HEV"]' (default: >{-<>-}<)
-  --algorithms [ALGORITHMS ...], --algos [ALGORITHMS ...], --algo [ALGORITHMS ...]
-                        Enter algorithm or list of algorithms, or "ensemble" to use all, to use for optimization: ex: -algos PatternSearch | -algos '["PatternSearch", "NSGA2"]' | -algos
-                        "ensemble" (default: NSGA2)
-  --dst-dir DST_DIR     Directory to store T3CO results (default: ./src/results)
-  --dir-mark DIR_MARK   Name for results directory in addition to timestamp (default: )
-  --file-mark FILE_MARK
-                        Prefix to add to the result file names (default: )
-  --skip-save-veh       Toggle result vehicle model YAML file saving off (default: False)
-  --x-tol X_TOL         Parameter space tolerance for optimization (default: 0.001)
-  --f-tol F_TOL         Objective space tolerance for optimization (default: 0.001)
-  --n-max-gen N_MAX_GEN
-                        Max number of optimizer iterations regardless of algorithm (default: 1000)
-  --pop-size POP_SIZE   population of each generation (default: 25)
-  --nth-gen NTH_GEN     Period of generations in which to evaluate if convergence happens during optimization (default: 1)
-  --n-last N_LAST       Number of generations to look back for establishing convergence during optimization (default: 5)
-  --range-overshoot-tol RANGE_OVERSHOOT_TOL
-                        Range overshoot tolerance, example '0.20' allows 20% range overshoot. Default of 'None' does not constrain overshoot. (default: None)
-  ---missed-trace-correction
-                        Activate FASTSim time-dilation to correct missed trace (default: False)
-  --max-time-dilation MAX_TIME_DILATION
-                        Maximum time dilation factor to 'catch up' with trace (default: 10)
-  --min-time-dilation MIN_TIME_DILATION
-                        Minimum time dilation to let trace 'catch up' (default: 0.1)
-  --time-dilation-tol TIME_DILATION_TOL
-                        Convergence criteria for time dilation (default: 0.001)
-  --write-tsv WRITE_TSV
-                        Boolean toggle to save intermediary .TSV cost results files (default: False)
-  --run-multi           Boolean switch to select multiprocessing version (default: False)
-  --n-processors N_PROCESSORS
-                        Number of processors to use for multiprocessing (default: 9)
+
+Selected CLI arguments related to EIA fuel price data fetching:
+
+```
+  --eia-api-key EIA_API_KEY
+                        EIA API key (prefer setting T3CO_EIA_API_KEY in .env file instead).
+  --eia-aeo-year EIA_AEO_YEAR
+                        AEO publication year to query (e.g. '2023', '2025').
+                        Default: auto-discover latest.
+  --eia-aeo-case EIA_AEO_CASE
+                        AEO scenario case ID (e.g. 'aeo2023ref').
+                        Default: auto-discover reference case.
+```
+
+For the full list of CLI arguments, run:
+```bash
+python -m t3co.cli.sweep --help
 ```
 
 ## T3CO Results
@@ -149,4 +134,4 @@ The [`t3co.visualization.charts`](https://github.com/NREL/T3CO/tree/main/t3co/vi
 <img src="https://raw.githubusercontent.com/NREL/T3CO/refs/heads/main/docs/violinplot_sample.png" alt="violinplot" width="400"/>
 
 
-The user can provide other input parameters specific to each visualization method to further customize the plots.
+The user can provide other input parameters specific to each visualization method to further customize the plots.