Technical Reference

API Reference

REST endpoints for Virginia grid carbon intensity, code energy estimation, and emission analysis. Base URL: https://eight04hacks-api.onrender.com/api/v1

Carbon Intensity

GET /carbon/intensity

Get current Virginia (DOM zone) carbon intensity in lb CO₂/MWh and g CO₂/kWh.

GET /carbon/intensity

Returns the latest real-time carbon intensity for the Virginia Dominion zone.

Query real_time (boolean, default: true)

Response

{
  "timestamp": "2026-10-18T14:21:57.690923Z",
  "carbon_intensity_lb_per_mwh": 761.5,
  "carbon_intensity_g_per_kwh": 345.4,
  "region": "VA-DOM",
  "source": "fallback_estimate",
  "is_real_time": false
}
Historical Data

GET /carbon/intensity/history

Retrieve historical carbon intensity at 5-minute intervals.

GET /carbon/intensity/history
Query hours (integer, 1–168, default: 24)

Example

GET /carbon/intensity/history?hours=24
Forecast

GET /carbon/forecast

Get carbon intensity forecast for the next 24–72 hours.

GET /carbon/forecast
Query hours (integer, 1–72, default: 24)
Hourly Intensity

GET /carbon/hourly

24-hour carbon intensity from 1 AM through 12 AM, with scheduling summary.

GET /carbon/hourly

Response

{
  "region": "VA-DOM",
  "current_hour": {
    "hour": 5,
    "label": "5 AM",
    "carbon_intensity_g_per_kwh": 301.0
  },
  "summary": {
    "now_g_per_kwh": 301.0,
    "best_window_start": 5,
    "best_window_end": 11,
    "best_window_avg_g_per_kwh": 292.0,
    "cleaner_by_percent": 3.0,
    "dirtiest_hour": 18,
    "dirtiest_hour_g_per_kwh": 361.0,
    "data_points": 24
  },
  "hours": [
    {
      "hour": 1,
      "label": "1 AM",
      "carbon_intensity_g_per_kwh": 280.5
    }
  ]
}
Generation Mix

GET /carbon/generation-mix

Get current Virginia grid fuel mix percentages from EIA.

GET /carbon/generation-mix

Response

{
  "natural_gas": 42.0,
  "nuclear": 33.0,
  "coal": 12.0,
  "solar": 6.0,
  "wind": 3.0,
  "hydro": 2.0,
  "other": 2.0
}
Code Analysis

POST /code/analyze

Estimate energy consumption and CO₂ emissions for a code snippet across 11 languages.

POST /code/analyze

Request Body

{
  "code": "def fib(n): return n if n<=1 else fib(n-1)+fib(n-2)",
  "language": "python",
  "runtime_seconds": 5,
  "cpu_utilization": 0.5,
  "memory_mb": 256
}

Response

{
  "estimated_energy_kwh": 1e-6,
  "estimated_emissions_g_co2": 0.0004,
  "carbon_intensity_used_g_per_kwh": 345.4,
  "breakdown": {
    "cpu_wh": 0.001,
    "memory_wh": 0.0,
    "idle_wh": 0.0,
    "total_wh": 0.001,
    "language": "python"
  },
  "timestamp": "2026-10-18T14:21:45.896309Z"
}
Code Analysis (File Upload)

POST /code/analyze-file

Upload a source code file to estimate its energy consumption and CO₂ emissions.

POST /code/analyze-file

Upload a source code file (.py, .js, .ts, .java, .go, .rs, .cpp, .c, .cs, .rb, .php). The API reads the file and returns its carbon footprint using real-time Virginia grid intensity.

Form Data file (required) — source code file
Form Data language (optional, default: python)

curl Example

curl -X POST https://eight04hacks-api.onrender.com/api/v1/code/analyze-file \
  -F "file=@main.py" \
  -F "language=python"

Response

{
  "estimated_energy_kwh": 1e-6,
  "estimated_emissions_g_co2": 0.0004,
  "carbon_intensity_used_g_per_kwh": 345.4,
  "breakdown": {
    "cpu_wh": 0.001,
    "total_wh": 0.001,
    "language": "python"
  },
  "timestamp": "2026-10-18T14:21:45.896309Z"
}
Comparison

GET /carbon/compare

Compare current intensity against historical percentiles.

GET /carbon/compare
Query days (integer, 1–365, default: 30)

Response

{
  "current_intensity_g_per_kwh": 386.7,
  "historical_avg_g_per_kwh": 374.6,
  "historical_min_g_per_kwh": 337.7,
  "historical_max_g_per_kwh": 416.1,
  "percentile": 79.8,
  "period": "last_30_days",
  "data_points": 8640
}
Grid Status

GET /grid/status

Complete grid snapshot: current intensity, forecast, and generation mix.

GET /grid/status
Equivalents

GET /carbon/equivalents

Translate grams of CO₂ into relatable equivalents.

GET /carbon/equivalents
Query grams_co2 (float, default: 1000)

Response

{
  "grams_co2": 1000,
  "equivalents": {
    "miles_driven_avg_car": 2.48,
    "smartphone_charges": 117.6,
    "led_bulb_hours": 22222.2,
    "tree_days_to_sequester": 45.66,
    "coal_grams_burned": 413.2,
    "natural_gas_cubic_feet": 18.38
  }
}