# Toronto Hydro

> Toronto Hydro is the municipally owned local electricity distribution company for the City of Toronto, delivering power to roughly 800,000 residential and business customers. It sits in the wires-and-meters layer of Ontario's electricity value chain — it does not generate power and it does not run the wholesale market (that is IESO) — so the only customer-facing data it owns is smart-meter consumption, billing and account data. Its only API obligation comes from Ontario Regulation 633/21 (Energy Data) under the Electricity Act, 1998, which compelled rate-regulated Ontario electricity and gas utilities to offer Green Button Download My Data and Connect My Data conforming to NAESB REQ.21 ESPI v3.3 by 1 November 2023. Toronto Hydro runs both, and publishes no base URI, no API reference and no first-party specification for either.

Generated by API Evangelist from the Toronto Hydro provider profile. Toronto Hydro does not publish an llms.txt of its own (https://www.torontohydro.com/llms.txt returns HTTP 404 as of 2026-07-27).

## Important caveats for an agent

- There is **no published Toronto Hydro API base URL**. Do not guess one. `api.torontohydro.com`, `docs.torontohydro.com`, `developer.torontohydro.com` and `data.torontohydro.com` do not resolve at all. The ESPI base URI is disclosed only after a private third-party onboarding process.
- The OpenAPI in this profile is **authored by the Green Button Alliance, not by Toronto Hydro**. It describes ESPI 4.0 and its `servers[]` points at the GBA sandbox, while Ontario mandates ESPI v3.3. It is included as the family contract, not as Toronto Hydro's service.
- Access is **gated by application approval**: submit an online application through the third-party portal, complete a connectivity test, and comply with the Third Party Terms — which also require Commercial General Liability, Professional Liability, Property Damage and Workman's Compensation insurance naming Toronto Hydro as an additional insured. There is no self-serve signup, no sandbox, no API key form, no published pricing and no rate-limit document.
- Consent ends three ways: the customer revokes at any time, the customer's account closes (Connect My Data stops on or after that date, including the final billing period), or Toronto Hydro terminates the third party. A `403` is an expected steady state, not necessarily a bug.
- Toronto Hydro publishes **no open market, grid, generation or outage data as a product**. The public outage map is a rendered web map with no documented feed.

## APIs

- [Toronto Hydro Green Button Connect My Data](https://www.torontohydro.com/for-home/green-button): OAuth-style, customer-consented machine-to-machine delivery of a consenting customer's electricity usage, billing and account data in NAESB REQ.21 ESPI XML. Mandated by O. Reg. 633/21. Base URI unpublished; application-approval only.
- [Toronto Hydro Green Button Download My Data](https://www.torontohydro.com/for-home/green-button): the customer-account-gated self-service export of the same data as a standards-conformant Green Button file. No anonymous endpoint, no key, no documented URL pattern — but the file it emits is a real machine-readable energy-data artifact, and it is the practical integration path for anyone unwilling to complete third-party onboarding.

## Specs

- [Green Button API Documentation (ESPI 4.0)](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/openapi/toronto-hydro-green-button-espi-openapi.yml): OpenAPI 3.0.0, 7 read operations over ApplicationInformation, Authorization, UsagePoint and Bulk batch transfer. Harvested verbatim from the Green Button Alliance with provenance; NOT a Toronto Hydro document.

## Docs

- [Green Button at Toronto Hydro](https://www.torontohydro.com/for-home/green-button): what Download My Data and Connect My Data provide, and the three requirements placed on third parties.
- [Third Party Terms and Conditions for Green Button Connect My Data](https://www.torontohydro.com/green-button/third-party-terms): the actual contract — obligations, insurance, purpose limitation, fair use, termination.
- [Green Button Connect My Data Customer Guide (PDF)](https://www.torontohydro.com/documents/d/guest/green-button-connect-my-data-customer-guide): the authorization flow, Option A (sign in) and Option B (alternate consent).
- [Third-party onboarding application](https://torontoonboarding.savagedata.com/): the live registration application, operated by platform vendor Savage Data Systems.
- [Manage your Green Button connections](https://www.torontohydro.com/my-account/green-button-connections): where a customer reviews and revokes third-party connections (account login required).
- [Download your Green Button data](https://www.torontohydro.com/my-account/green-button-data): the Download My Data surface (account login required).
- [Reporting of energy consumption (EWRB)](https://www.torontohydro.com/for-business/reporting-of-energy-consumption): the business bulk-data path — ENERGY STAR Portfolio Manager data exchange, or an emailed PDF request form with a four-week turnaround.

## Regulation

- [Ontario Regulation 633/21 (Energy Data)](https://www.ontario.ca/laws/regulation/210633): the instrument that compels Green Button in Ontario.
- [Green Button Ontario](https://greenbuttonontario.ca/): the provincial programme page.
- [Green Button Alliance testing and certification](https://www.greenbuttonalliance.org/testing): the standard's certification programme.

## Artifacts

- [apis.yml](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/apis.yml)
- [review.yml](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/review.yml): the full probe record, including what could and could not be verified.
- [authentication](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/authentication/toronto-hydro-authentication.yml)
- [oauth scopes](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/scopes/toronto-hydro-scopes.yml)
- [conventions](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/conventions/toronto-hydro-conventions.yml)
- [conformance](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/conformance/toronto-hydro-conformance.yml)
- [error catalog](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/errors/toronto-hydro-problem-types.yml)
- [lifecycle](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/lifecycle/toronto-hydro-lifecycle.yml)
- [data model](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/data-model/toronto-hydro-data-model.yml)
- [packages](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/packages/toronto-hydro-packages.yml)
- [well-known probe](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/well-known/toronto-hydro-well-known.yml)
- [domain security](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/security/toronto-hydro-domain-security.yml)
- [agent skills](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/skills/_index.yml)
- [overlay](https://raw.githubusercontent.com/api-evangelist/toronto-hydro/refs/heads/main/overlays/toronto-hydro-green-button-espi-overlay.yaml)

## Optional

- [Toronto Hydro outage map](https://outagemap.torontohydro.com/): a rendered public outage web map. No documented data feed, no terms, no stability commitment — recorded as the only live operational status surface, not as an API.
- [Community: toronto-hydro-green-button](https://pypi.org/project/toronto-hydro-green-button/): a 2019 third-party Python tool that drives the customer portal with Selenium to export Green Button XML. Not Toronto Hydro software; included because its README independently records that Toronto Hydro "does not offer programmatic API access".