---
title: "Texas Residential Load Profile (ERCOT)"
method: POST
path: "/api/v1/get-residential-load-profile"
tags: ["data-feed"]
---

# Texas Residential Load Profile (ERCOT)

`POST /api/v1/get-residential-load-profile`

Get the typical residential electricity load curve for any Texas weather zone — averaged from ERCOT's official residential load profiles, in 15-minute resolution. Returns hourly or monthly aggregated kWh by hour-of-day and month-of-year, peak demand, and annual total. Useful for solar designers, battery sizers, AI agents modeling 'what does a typical home in Houston use', and anyone building bill-projection or solar-savings tools without a real customer's meter data.

ERCOT publishes residential load profiles (15-minute kWh values) for each
of its 8 weather zones, broken into 4 residential profile types:

| Profile | Customer type |
|---|---|
| RESHIWR | Residential heating with weather response (default — most common) |
| RESHIDG | Residential heating with distributed generation (solar homes) |
| RESHIPV | Residential heating with PV |
| RESHIWD | Residential without distributed generation |

These curves represent the *typical* home in a zone. They're the same
curves Meter uses internally to model bill projections and solar savings
when a real customer's Smart Meter Texas (SMT) data isn't yet available.

**Inputs:**
Provide either a ZIP code (resolved to weather zone via ZIP-prefix → zone
mapping) OR a weatherZone code directly. Optional profileType + year.
The granularity flag controls payload size:
- `monthly_hourly` (default, 288 entries): typical kWh by month × hour
- `monthly_totals` (12 entries): just monthly kWh totals
- `annual_hourly` (8760 entries): full year of hourly averages

**Why this exists:**
- Solar designers need a typical load curve for every proposal — without
  it, "your panels will save you $X" estimates are guesswork
- Battery sizers need to know when in the day a home draws power
- AI agents modeling Texas electricity bills need a baseline shape when
  the user can't provide their own meter data
- Researchers and energy nerds compare zones (Houston vs DFW summer
  shapes are very different)

**For real customer data**, use `pull_smt_interval_data` (gives the
actual home's usage, not the regional average). This tool is the
"typical home" baseline; SMT is "this specific home."

## Request body

- object
  - `zipCode` string — 5-digit Texas ZIP code. Resolved to ERCOT weather zone via ZIP prefix mapping. Use this OR weatherZone.
  - `weatherZone` 'COAST' | 'EAST' | 'FWEST' | 'NCENT' | 'NORTH' | 'SCENT' | 'SOUTH' | 'WEST' — ERCOT weather zone code. COAST=Houston, NCENT=DFW + central TX, SCENT=Austin, SOUTH=SA/Corpus/RGV, NORTH=Wichita Falls/Lubbock, WEST=Abilene/Big Spring, FWEST=Midland/El Paso, EAST=Tyler. Use this OR zipCode.
  - `profileType` 'RESHIWR' | 'RESHIDG' | 'RESHIPV' | 'RESHIWD' — ERCOT residential profile type. Default RESHIWR (residential heating with weather response — most common). RESHIDG/RESHIPV cover solar homes; RESHIWD covers homes without distributed generation.
  - `year` integer — Profile year. Defaults to most recent year on file (currently 2025).
  - `granularity` 'monthly_hourly' | 'monthly_totals' | 'annual_hourly' — Output detail. `monthly_hourly` (default, 288 entries) = typical kWh by month × hour-of-day. `monthly_totals` (12 entries) = just monthly kWh totals. `annual_hourly` (8760 entries) = full year of hourly averages — largest payload.

## Response `200`

Tool ran successfully.

- object
  - `resolvedWeatherZone` string, required — ERCOT weather zone the request resolved to (matches input or derived from ZIP).
  - `profileType` string, required — ERCOT residential profile type used.
  - `year` number, required — Profile year used.
  - `granularity` string, required — Granularity flag echoed back.
  - `annualTotalKwh` number, required — Total annual kWh for the typical home in this zone.
  - `peakHourlyKw` number, required — Peak hourly demand in kW (highest hourly kWh × 1 — since 1 kWh in 1 hour = 1 kW average).
  - `monthlyTotalsKwh` number[], required — 12-element array of monthly kWh totals (Jan first, Dec last).
  - `intervals` union, required — The actual data, shape depends on granularity. monthly_hourly = 288 entries; monthly_totals = 12 entries; annual_hourly = 8760 entries.
    - object[]
      - `month` number, required — Month 1-12 (1=January).
      - `hour` number, required — Hour 0-23 (0=midnight, 13=1pm).
      - `avgKwh` number, required — Average kWh consumed during this hour-of-day in this month.
    - object[]
      - `month` number, required — Month 1-12.
      - `totalKwh` number, required — Total kWh consumed during the month.
    - object[]
      - `hourOfYear` number, required — Hour-of-year 0-8759.
      - `date` string, required — Date in YYYY-MM-DD format.
      - `hour` number, required — Hour 0-23.
      - `kwh` number, required — kWh consumed in this specific hour.
  - `source` object, required — Metadata about the data source.
    - `provider` string, required
    - `url` string, required
    - `notes` string, required

## Other responses

- `400` — Request body was missing, malformed JSON, or failed input schema validation.
- `500` — Tool execution failed or produced an output that violated the schema.

---

[API](https://skmtc.dev/meterplan/apis/meter-energy-public-api.md) · [All operations](https://skmtc.dev/meterplan/apis/meter-energy-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/meterplan/meter-energy-public-api/revisions/ebf1846a188d/schema)