Introduction

tou.tools resolves a U.S. address or ZIP code to its electric utility, then reports the active Time-of-Use (TOU) period — on-peak, off-peak, and everything between — along with when the next period begins.

The scope is deliberately narrow: period names, boundaries, and schedules only. tou.tools does not return ¢/kWh prices — those vary by tariff rider, customer class, and baseline allowance, and are out of scope. What you get is the timing layer: which period is active, and exactly when it changes.

Two ways to integrate

• REST API — plain HTTP GET requests returning JSON. Best for apps, dashboards, and backend services.
• MCP server — a Model Context Protocol endpoint that AI agents can call as a native tool, with no integration code. See MCP integration.

Base URL

All REST endpoints are served under a single versioned base path:

https://tou.tools/api/v1

Authentication

Requests authenticate with an API key passed as a bearer token in the Authorization header. Keys are issued from your dashboard under API keys, and are prefixed tou_.

Authorization: Bearer tou_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Quickstart

Ask whether power is peak or off-peak at a ZIP code right now. This is the single most common call:

# current period for ZIP 94103 (San Francisco)
curl https://tou.tools/api/v1/query/current?zip_code=94103 \
  -H "Authorization: Bearer tou_YOUR_API_KEY"

The response lists every active TOU rate plan for that location, each with its current period and the timestamp of the next change. See Current period for the full shape.

Current period

Returns the live TOU period for every active rate plan serving a location. If the ZIP maps to more than one utility, every candidate is returned — tou.tools never silently guesses.

Query parameters

Example response

{
  "zip_code": "94103",
  "confidence": "unique",
  "resolved_by": "zip",
  "customer_class": "residential",
  "as_of": "2026-05-16T11:30:00-07:00",
  "results": [
    {
      "rate_plan": {
        "id": "8f3a2c10-4b6d-4e9a-9f12-7c5e1d8a0b34",
        "utility_number": 14328,
        "utility_name": "Pacific Gas & Electric Co",
        "code": "E-TOU-C",
        "name": "Residential Time-of-Use",
        "customer_class": "residential",
        "timezone": "America/Los_Angeles",
        "is_closed": false,
        "effective_from": "2024-01-01",
        "effective_to": null,
        "last_verified_at": "2026-04-30T18:22:00Z",
        "provider": null
      },
      "period": "off_peak",
      "next_change_at": "2026-05-16T16:00:00-07:00"
    }
  ]
}

Response fields

Full schedule

Returns the complete rule set for a single rate plan — every period window, season bound, and weekday mask. Use it to render a calendar or precompute upcoming periods client-side.

Query parameters

Example response

{
  "rate_plan": { /* same shape as in /query/current */ },
  "rules": [
    {
      "period_name": "on_peak",
      "season_start_md": "06-01",
      "season_end_md": "09-30",
      "season_start_anchor": null,
      "season_end_anchor": null,
      "days_of_week": 31,
      "time_start": "16:00:00",
      "time_end": "21:00:00",
      "excluded_holidays": ["Independence Day"],
      "holidays_as_dow": null,
      "priority": 0
    }
  ]
}

Rule fields

Forward schedule

Resolves the schedule into a concrete period timeline for every active rate plan at a location — contiguous segments, each with a period name and exact start/end timestamps, covering the next hours hours. Seasons, weekday masks, holidays, and priorities are already applied, so a battery dispatcher or EV charger can plan against it directly instead of re-implementing the rules from /query/schedule.

Query parameters

Takes the same location parameters as /query/current — zip_code (required), customer_class, street, city, state — plus:

Plan horizons

How far ahead you can resolve is set by your plan — the forward schedule horizon:

Example response

{
  "zip_code": "94103",
  "confidence": "unique",
  "resolved_by": "zip",
  "customer_class": "residential",
  "as_of": "2026-06-11T09:00:00Z",
  "until": "2026-06-12T09:00:00Z",
  "hours": 24,
  "results": [
    {
      "rate_plan": { /* same shape as in /query/current */ },
      "timeline": [
        { "period": "off_peak", "start_at": "2026-06-11T02:00:00-07:00", "end_at": "2026-06-11T16:00:00-07:00" },
        { "period": "on_peak",  "start_at": "2026-06-11T16:00:00-07:00", "end_at": "2026-06-11T21:00:00-07:00" },
        { "period": "off_peak", "start_at": "2026-06-11T21:00:00-07:00", "end_at": "2026-06-12T02:00:00-07:00" }
      ]
    }
  ]
}

Segments tile the window exactly: the first starts at as_of, the last ends at until, and each segment begins where the previous one ended (timestamps are returned in the rate plan's local timezone). The same timeline is available for a single known plan via /query/schedule's hours parameter.

Coverage

Lists every utility with at least one active rate plan, the states it serves, and which customer classes are covered. Public — no key required.

{
  "summary": {
    "total_utilities": 1000,
    "total_states": 51,
    "total_rate_plans": 0,
    "last_verified_at": "2026-04-30T18:22:00Z"
  },
  "utilities": [ /* one object per covered utility */ ]
}

Health

A liveness probe — no auth, no parameters.

{ "status": "ok" }

TOU periods

Every period in a response is one of the names below. off_peak is the implicit default — it is returned whenever no schedule rule matches the queried moment.

Customer classes

A single ZIP may have different TOU schedules for a home, a storefront, and a factory. The customer_class parameter selects which set of rate plans to evaluate.

• residential — homes and apartments. The default.
• commercial — offices, retail, and other small-to-medium businesses.
• industrial — large-load industrial sites.
• agricultural — farms and irrigation accounts.
• ev — dedicated electric-vehicle charging rate plans.

Retail providers

In most of the U.S., one regulated utility both delivers power and sets the TOU schedule, so every rate_plan.provider is null. In deregulated Texas (ERCOT), the wires company (the "TDU" — e.g. Oncor, CenterPoint) only delivers, while a competitive Retail Electric Provider (REP) authors the plan and its TOU schedule. For those plans provider is populated and the utility_number/utility_name identify the delivering TDU, not the seller.

{
  "rep_id": "38a88ef1-4d17-40d0-bdb2-b0f929a51838",
  "name": "Reliant Energy Retail Services",
  "puct_number": 10007,
  "url": "https://www.reliant.com"
}

Location resolution

U.S. electric service territories do not follow ZIP boundaries. A ZIP can fall entirely inside one utility, straddle two, or land in an area with no mapped retail utility. tou.tools reports this honestly with the confidence field:

• unique — the ZIP maps to exactly one utility.
• ambiguous — the ZIP overlaps multiple utilities; every candidate is returned.
• no_coverage — no mapped retail utility for that ZIP.

When a ZIP is ambiguous, pass street (plus optionally city and state) and tou.tools will geocode the address to narrow candidates to the territory that actually contains the point. The result's resolved_by becomes address when that lookup ran. If geocoding fails or the point lands outside every candidate territory, the full ambiguous result is returned unchanged — coverage is never silently dropped.

Errors

Errors use standard HTTP status codes with a JSON body carrying a detail message.

{ "detail": "`at` must include a timezone offset" }

Period-change events

Instead of polling /query/current on a timer, register a webhook endpoint and tou.tools will POST a signed event to your server the moment a TOU period changes for a location you watch — the off-peak → on-peak flip, and every other boundary, pushed as it happens.

How it works

1. Create an endpoint with your destination URL. You'll get a signing secret (tousec_…), shown once — store it.
2. Add the (ZIP, customer_class) locations that endpoint should watch.
3. tou.tools evaluates each watch on a schedule. When a plan's period changes versus the last value it saw, it sends an event. (The first observation of each plan is recorded silently — you only get events on real transitions.)
4. Your server responds 2xx to acknowledge. Non-2xx or a timeout is retried with backoff: immediately, then 1 min, 5 min, 30 min, 2 h, after which the delivery is marked failed.

Event payload

Each delivery is a single tou.period.changed event for one rate plan at one watched location:

{
  "id": "evt_8f3a2c104b6d4e9a9f12",
  "type": "tou.period.changed",
  "created_at": "2026-05-16T16:00:00-07:00",
  "zip_code": "94103",
  "customer_class": "residential",
  "previous_period": "off_peak",
  "period": "on_peak",
  "next_change_at": "2026-05-16T21:00:00-07:00",
  "rate_plan": {
    "id": "8f3a2c10-4b6d-4e9a-9f12-7c5e1d8a0b34",
    "utility_number": 14328,
    "utility_name": "Pacific Gas & Electric Co",
    "code": "E-TOU-C",
    "name": "Residential Time-of-Use"
  }
}

A watched ZIP that resolves to several rate plans sends one event per plan that changed. previous_period / period use the same vocabulary as the REST API — see TOU periods.

Request headers

Verifying a delivery

Recompute the signature with your stored secret and compare it to the Tou-Signature header (use a constant-time comparison):

# Flask-style handler
import hashlib, hmac, time

SECRET = "tousec_…"

def verify(request):
    ts = request.headers["Tou-Timestamp"]
    sig = request.headers["Tou-Signature"]
    body = request.get_data(as_text=True)  # raw bytes/string, unmodified
    # reject anything older than 5 minutes
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(
        SECRET.encode(), f"{ts}.{body}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

MCP integration

tou.tools ships as a Model Context Protocol server, so any MCP-capable AI client — Claude Code, Cursor, Windsurf, Cline, Continue, Zed, Claude Desktop, ChatGPT, and others — can query TOU data as a native tool with no SDK or glue code. The server speaks streamable HTTP at:

https://tou.tools/mcp

Available tools

Option A — API key (desktop and CLI clients)

For local clients — Claude Code, Cursor, Windsurf, Cline, Continue, Zed, Claude Desktop, and similar — connect with an Authorization: Bearer tou_… header (the same API key you use for REST). Mint one on the API Keys page, then add tou.tools to your client's MCP server config.

Most clients accept the standard mcpServers JSON shape below:

{
  "mcpServers": {
    "tou": {
      "url": "https://tou.tools/mcp",
      "headers": { "Authorization": "Bearer tou_…" }
    }
  }
}

Where this config lives differs by client — check your client's MCP docs for the right file or UI (e.g. ~/.cursor/mcp.json for Cursor, claude_desktop_config.json for Claude Desktop, the in-app Settings panel for Windsurf, an .mcp.json in your project root for Claude Code). The block above is portable across all of them.

Option B — OAuth 2.1 (browser-hosted clients)

Browser-hosted clients like Claude Web and ChatGPT only accept MCP servers behind OAuth 2.1 with discovery. Add tou.tools as a custom connector and the client handles the full flow — discovery, dynamic client registration, PKCE, the consent screen, token refresh. You just point and sign in.

1. In your client (Claude Web, ChatGPT, etc.), open the connector / custom integration settings and choose Add custom connector (or the equivalent).
2. Server URL: https://tou.tools/mcp
3. The client redirects you to tou.tools to sign in (use your dashboard email + password). You'll see a consent screen showing the four tools — click Allow.
4. Done. The four tools appear in your client's tool list and bill against your account just like REST calls do.

Ready to build? Get a free API key or review plans & limits.