Tariffs & Utilities¶

The Tariffs API provides access to a comprehensive database of utility rate schedules, tariff details, and bill calculation tools. It also includes utility company lookup and search. Endpoints are grouped under /tariffs, /utilities, and /calculate.

Tariffs¶

GET /tariffs/search¶

Search the tariff database with flexible filters.


Auth required	Yes

Query Parameters¶

Parameter	Type	Default	Description
`zip_code`	string	-	5-digit ZIP code to find tariffs serving that area
`state`	string	-	Two-letter state code
`utility_name`	string	-	Partial match on utility name
`sector`	string	-	`residential`, `commercial`, `industrial`, `agricultural`, `lighting`
`rate_type`	string	-	`flat`, `tiered`, `tou` (time-of-use), `demand`, `real_time`
`has_tou`	boolean	-	Filter for time-of-use rates
`has_demand`	boolean	-	Filter for demand charges
`has_net_metering`	boolean	-	Filter for net metering eligibility
`page`	integer	`1`	Page number
`per_page`	integer	`20`	Items per page (max 100)

Example Request¶

curl "https://app.meterbase.io/api/v1/tariffs/search?zip_code=90001&sector=commercial&has_tou=true&per_page=5" \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

{
  "items": [
    {
      "id": "trf_sce_tou_gs1",
      "name": "SCE TOU-GS-1",
      "utility_id": "util_sce",
      "utility_name": "Southern California Edison",
      "state": "CA",
      "sector": "commercial",
      "rate_type": "tou",
      "has_tou": true,
      "has_demand": false,
      "has_net_metering": true,
      "effective_date": "2026-01-01",
      "description": "Small commercial time-of-use, demand < 20 kW"
    },
    {
      "id": "trf_sce_tou_gs2",
      "name": "SCE TOU-GS-2",
      "utility_id": "util_sce",
      "utility_name": "Southern California Edison",
      "state": "CA",
      "sector": "commercial",
      "rate_type": "tou",
      "has_tou": true,
      "has_demand": true,
      "has_net_metering": true,
      "effective_date": "2026-01-01",
      "description": "Medium commercial time-of-use, demand 20-200 kW"
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 5,
  "pages": 1
}

GET /tariffs/{id}¶

Retrieve full tariff details including all rate components, time-of-use periods, demand charges, fixed charges, and riders.


Auth required	Yes

Path Parameters¶

Parameter	Type	Description
`id`	string	Tariff ID

Example Request¶

curl https://app.meterbase.io/api/v1/tariffs/trf_sce_tou_gs2 \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

{
  "id": "trf_sce_tou_gs2",
  "name": "SCE TOU-GS-2",
  "utility_id": "util_sce",
  "utility_name": "Southern California Edison",
  "state": "CA",
  "sector": "commercial",
  "rate_type": "tou",
  "has_tou": true,
  "has_demand": true,
  "has_net_metering": true,
  "effective_date": "2026-01-01",
  "expiration_date": null,
  "description": "Medium commercial time-of-use, demand 20-200 kW",
  "eligibility": "Demand between 20 kW and 200 kW",
  "energy_rates": [
    {
      "period": "summer_on_peak",
      "months": [6, 7, 8, 9],
      "hours": "16:00-21:00",
      "days": "Mon-Fri",
      "rate_per_kwh": 0.28453
    },
    {
      "period": "summer_mid_peak",
      "months": [6, 7, 8, 9],
      "hours": "08:00-16:00, 21:00-23:00",
      "days": "Mon-Fri",
      "rate_per_kwh": 0.17892
    },
    {
      "period": "summer_off_peak",
      "months": [6, 7, 8, 9],
      "hours": "23:00-08:00",
      "days": "All days",
      "rate_per_kwh": 0.11234
    },
    {
      "period": "winter_mid_peak",
      "months": [1, 2, 3, 4, 5, 10, 11, 12],
      "hours": "08:00-21:00",
      "days": "Mon-Fri",
      "rate_per_kwh": 0.16543
    },
    {
      "period": "winter_off_peak",
      "months": [1, 2, 3, 4, 5, 10, 11, 12],
      "hours": "21:00-08:00",
      "days": "All days",
      "rate_per_kwh": 0.10123
    }
  ],
  "demand_rates": [
    {
      "period": "summer",
      "months": [6, 7, 8, 9],
      "type": "facility",
      "rate_per_kw": 18.42
    },
    {
      "period": "summer_on_peak",
      "months": [6, 7, 8, 9],
      "type": "tou",
      "rate_per_kw": 22.75
    },
    {
      "period": "winter",
      "months": [1, 2, 3, 4, 5, 10, 11, 12],
      "type": "facility",
      "rate_per_kw": 18.42
    }
  ],
  "fixed_charges": [
    {
      "name": "Customer Charge",
      "amount": 125.00,
      "frequency": "monthly"
    }
  ],
  "riders": [
    {
      "name": "Wildfire Fund Charge",
      "rate_per_kwh": 0.00580,
      "description": "AB 1054 Wildfire Fund non-bypassable charge"
    },
    {
      "name": "Public Purpose Programs",
      "rate_per_kwh": 0.01234,
      "description": "Funds energy efficiency and low-income programs"
    }
  ],
  "source_url": "https://www.sce.com/regulatory/tariff-books",
  "last_updated": "2026-01-15T00:00:00Z"
}

Error Cases¶

Status	Detail	Cause
`404`	`"Tariff not found"`	Invalid tariff ID

GET /tariffs/stats¶

Retrieve statistics about the tariff database.


Auth required	Yes

Example Request¶

curl https://app.meterbase.io/api/v1/tariffs/stats \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

{
  "total_tariffs": 12847,
  "total_utilities": 3421,
  "states_covered": 50,
  "sectors": {
    "residential": 5234,
    "commercial": 4102,
    "industrial": 2311,
    "agricultural": 842,
    "lighting": 358
  },
  "rate_types": {
    "flat": 3920,
    "tiered": 4215,
    "tou": 3512,
    "demand": 1043,
    "real_time": 157
  },
  "last_updated": "2026-03-20T00:00:00Z"
}

GET /tariffs/by-utility/{utility_id}¶

List all tariffs offered by a specific utility.


Auth required	Yes

Path Parameters¶

Parameter	Type	Description
`utility_id`	string	Utility ID

Query Parameters¶

Parameter	Type	Default	Description
`sector`	string	-	Filter by sector
`page`	integer	`1`	Page number
`per_page`	integer	`20`	Items per page (max 100)

Example Request¶

curl "https://app.meterbase.io/api/v1/tariffs/by-utility/util_sce?sector=commercial" \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

{
  "items": [
    {
      "id": "trf_sce_tou_gs1",
      "name": "SCE TOU-GS-1",
      "sector": "commercial",
      "rate_type": "tou",
      "has_demand": false,
      "effective_date": "2026-01-01"
    },
    {
      "id": "trf_sce_tou_gs2",
      "name": "SCE TOU-GS-2",
      "sector": "commercial",
      "rate_type": "tou",
      "has_demand": true,
      "effective_date": "2026-01-01"
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 20,
  "pages": 1
}

Error Cases¶

Status	Detail	Cause
`404`	`"Utility not found"`	Invalid utility ID

Utilities¶

GET /utilities/search¶

Search for utility companies by name or state.


Auth required	Yes

Query Parameters¶

Parameter	Type	Default	Description
`q`	string	-	Search query (partial name match)
`state`	string	-	Two-letter state code
`page`	integer	`1`	Page number
`per_page`	integer	`20`	Items per page (max 100)

Example Request¶

curl "https://app.meterbase.io/api/v1/utilities/search?q=southern+california&state=CA" \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

{
  "items": [
    {
      "id": "util_sce",
      "name": "Southern California Edison",
      "abbreviation": "SCE",
      "state": "CA",
      "type": "investor_owned",
      "website": "https://www.sce.com",
      "tariff_count": 48
    },
    {
      "id": "util_socal_gas",
      "name": "Southern California Gas Company",
      "abbreviation": "SoCalGas",
      "state": "CA",
      "type": "investor_owned",
      "website": "https://www.socalgas.com",
      "tariff_count": 22
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 20,
  "pages": 1
}

GET /utilities/{id}¶

Retrieve details for a specific utility.


Auth required	Yes

Path Parameters¶

Parameter	Type	Description
`id`	string	Utility ID

Example Request¶

curl https://app.meterbase.io/api/v1/utilities/util_sce \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

{
  "id": "util_sce",
  "name": "Southern California Edison",
  "abbreviation": "SCE",
  "state": "CA",
  "type": "investor_owned",
  "website": "https://www.sce.com",
  "phone": "1-800-655-4555",
  "service_territory": "Central, coastal, and southern California (excluding LA and some municipalities)",
  "customers_served": 5000000,
  "tariff_count": 48,
  "zip_codes_served": 234
}

Error Cases¶

Status	Detail	Cause
`404`	`"Utility not found"`	Invalid utility ID

GET /utilities/by-zip/{zip_code}¶

Look up which utilities serve a given ZIP code.


Auth required	Yes

Path Parameters¶

Parameter	Type	Description
`zip_code`	string	5-digit ZIP code

Example Request¶

curl https://app.meterbase.io/api/v1/utilities/by-zip/90001 \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

[
  {
    "id": "util_sce",
    "name": "Southern California Edison",
    "abbreviation": "SCE",
    "state": "CA",
    "type": "investor_owned",
    "tariff_count": 48
  },
  {
    "id": "util_socal_gas",
    "name": "Southern California Gas Company",
    "abbreviation": "SoCalGas",
    "state": "CA",
    "type": "investor_owned",
    "tariff_count": 22
  }
]

Error Cases¶

Status	Detail	Cause
`404`	`"No utilities found for ZIP code"`	No utility service in that ZIP
`422`	`"Invalid ZIP code format"`	Not a valid 5-digit ZIP

Bill Calculation¶

POST /calculate¶

Calculate a hypothetical bill for a given tariff and usage profile.


Auth required	Yes

Request Body¶

Field	Type	Required	Description
`tariff_id`	string	Yes	Tariff ID to calculate under
`usage_kwh`	number	Yes	Total energy usage in kWh
`demand_kw`	number	No	Peak demand in kW (required for demand tariffs)
`month`	integer	No	Month of the year (1-12) for seasonal rate selection (default: current month)
`solar_generation_kwh`	number	No	Solar generation in kWh (for net metering calculations)
`usage_profile`	object	No	Hourly or TOU-period breakdown (see below)

Usage Profile Object (optional, for TOU tariffs):

Field	Type	Description
`on_peak_kwh`	number	Usage during on-peak hours
`mid_peak_kwh`	number	Usage during mid-peak hours
`off_peak_kwh`	number	Usage during off-peak hours

Tip

If you provide usage_kwh without a usage_profile, the system distributes usage across TOU periods using typical load profiles for the property sector.

Example Request¶

curl -X POST https://app.meterbase.io/api/v1/calculate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tariff_id": "trf_sce_tou_gs2",
    "usage_kwh": 16200,
    "demand_kw": 48.5,
    "month": 7,
    "usage_profile": {
      "on_peak_kwh": 4050,
      "mid_peak_kwh": 6480,
      "off_peak_kwh": 5670
    }
  }'

Example Response¶

200 OK

{
  "tariff_id": "trf_sce_tou_gs2",
  "tariff_name": "SCE TOU-GS-2",
  "month": 7,
  "season": "summer",
  "total_cost": 4287.34,
  "line_items": [
    {
      "category": "energy",
      "name": "On-Peak Energy (4,050 kWh x $0.28453)",
      "amount": 1152.35
    },
    {
      "category": "energy",
      "name": "Mid-Peak Energy (6,480 kWh x $0.17892)",
      "amount": 1159.40
    },
    {
      "category": "energy",
      "name": "Off-Peak Energy (5,670 kWh x $0.11234)",
      "amount": 636.97
    },
    {
      "category": "demand",
      "name": "Facility Demand (48.5 kW x $18.42)",
      "amount": 893.37
    },
    {
      "category": "demand",
      "name": "TOU On-Peak Demand (48.5 kW x $22.75)",
      "amount": 1103.38
    },
    {
      "category": "fixed",
      "name": "Customer Charge",
      "amount": 125.00
    },
    {
      "category": "rider",
      "name": "Wildfire Fund Charge (16,200 kWh x $0.00580)",
      "amount": 93.96
    },
    {
      "category": "rider",
      "name": "Public Purpose Programs (16,200 kWh x $0.01234)",
      "amount": 199.91
    }
  ],
  "summary": {
    "energy_charge": 2948.72,
    "demand_charge": 1996.75,
    "fixed_charge": 125.00,
    "riders": 293.87,
    "taxes_estimate": 0.0,
    "effective_rate_per_kwh": 0.2647
  }
}

Error Cases¶

Status	Detail	Cause
`404`	`"Tariff not found"`	Invalid `tariff_id`
`422`	`"demand_kw required for demand tariffs"`	Missing demand for a demand tariff
`422`	`"month must be between 1 and 12"`	Invalid month

POST /calculate/compare¶

Compare estimated bills across multiple tariffs for the same usage profile.


Auth required	Yes

Request Body¶

Field	Type	Required	Description
`tariff_ids`	array	Yes	Array of tariff IDs to compare (max 10)
`usage_kwh`	number	Yes	Total energy usage in kWh
`demand_kw`	number	No	Peak demand in kW
`month`	integer	No	Month (1-12, default: current)
`usage_profile`	object	No	TOU period breakdown

Example Request¶

curl -X POST https://app.meterbase.io/api/v1/calculate/compare \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tariff_ids": ["trf_sce_tou_gs1", "trf_sce_tou_gs2", "trf_sce_tou_gs3"],
    "usage_kwh": 16200,
    "demand_kw": 48.5,
    "month": 7
  }'

Example Response¶

200 OK

{
  "usage_kwh": 16200,
  "demand_kw": 48.5,
  "month": 7,
  "results": [
    {
      "tariff_id": "trf_sce_tou_gs3",
      "tariff_name": "SCE TOU-GS-3",
      "total_cost": 3890.12,
      "effective_rate_per_kwh": 0.2401,
      "rank": 1
    },
    {
      "tariff_id": "trf_sce_tou_gs2",
      "tariff_name": "SCE TOU-GS-2",
      "total_cost": 4287.34,
      "effective_rate_per_kwh": 0.2647,
      "rank": 2
    },
    {
      "tariff_id": "trf_sce_tou_gs1",
      "tariff_name": "SCE TOU-GS-1",
      "total_cost": 4650.00,
      "effective_rate_per_kwh": 0.2870,
      "rank": 3
    }
  ],
  "cheapest": "trf_sce_tou_gs3",
  "potential_savings": {
    "vs_most_expensive": 759.88,
    "vs_most_expensive_percent": 16.3
  }
}

Error Cases¶

Status	Detail	Cause
`422`	`"tariff_ids must contain at least 2 items"`	Fewer than 2 tariffs
`422`	`"tariff_ids must contain at most 10 items"`	More than 10 tariffs
`404`	`"Tariff not found: trf_xxx"`	One or more invalid tariff IDs