Request Type
New documentation topic
Description
Summary
Request to add historical energy data retrieval to the SPAN API so that
integrators and panel owners can programmatically access the same historical
data that is already visible in the SPAN mobile app.
Context
The mobile app exposes historical energy data in several views (Today, Week,
Month, Year) and provides a "Download data" button that produces a CSV export.
The CSV export is useful but limited in two ways:
-
Single metric. The export contains only aggregated home consumption.
The app UI clearly computes and displays additional values — solar
production, grid import, and (for battery owners) battery flow — in the
"Where you got your energy" visualization. These component streams are
not present in the export.
-
Downsampled by view. The export granularity tracks the selected UI
view rather than the underlying data resolution:
- Year view export: 2-day buckets
- Month view export: 4-hour buckets
- Week / Today: finer, but still display-layer rollups
The local API, as currently documented, does not expose historical data at
all — only current state and recent buffers.
Request
Add endpoints (local API, cloud API, or local-API-proxied-to-cloud — whichever
fits SPAN's architecture) for historical retrieval of:
- Grid import and grid export, separately
- Solar production
- Home consumption
- Per-circuit consumption, for all monitored circuits
With standard querying semantics:
- Time range parameters (
start, end)
- Selectable aggregation interval (e.g. 15m, 1h, 1d) down to whatever
native resolution SPAN retains
- JSON response, consistent with existing API conventions
On rate limiting
This does not need to be high-frequency or high-throughput access. Historical
data changes slowly by definition. Reasonable rate limits — per-panel request
caps, daily query budgets, response size limits, mandatory aggregation above
some resolution, whatever makes sense for SPAN's infrastructure — are all
acceptable. The goal is access, not real-time streaming.
Use cases
- NEM 2.0 analysis. Separated grid import/export by time-of-use period
is the economically meaningful breakdown for California solar customers,
and it isn't derivable from home-consumption totals alone.
- Long-term energy analytics. Correlating consumption patterns across
seasons, year-over-year comparisons, retrofit/appliance-change impact
analysis.
- Home Assistant and other integrations. Backfilling historical data
into long-term storage (e.g. HA's LTSS, InfluxDB) when a user first
installs an integration, or after a storage reset.
- Data portability. Giving owners a clean path to move their own data
between tools without screen-scraping the app.
Alignment with data access obligations
Beyond the product value, this feature would directly support data access
commitments that SPAN already makes to its customers. SPAN's Supplemental
CCPA Privacy Notice acknowledges California residents' rights to know and
access the specific pieces of personal information collected about them,
and similar access and portability rights apply under other state privacy
laws (Colorado CPA, Virginia VCDPA, Connecticut CTDPA, and a growing list
of others). Residential energy telemetry tied to a specific account and
home falls within the personal information covered by these frameworks.
An API endpoint for historical data would let SPAN satisfy these access
expectations programmatically and at scale, in a format customers can
readily use — which is a materially better outcome for both SPAN and its
customers than handling requests through ad-hoc manual exports. It also
gives SPAN's privacy team a clean, self-service answer for California and
multi-state access requests as the regulatory landscape continues to
evolve.
Why this seems tractable
The data is already retained server-side (the app's visualizations are
evidence of that) and the rollup tiers visible in the mobile export suggest
a tiered aggregation store is already in place. Exposing query endpoints
over that existing store is a smaller lift than, for example, shipping a
new data product.
Happy to contribute to schema design discussion if useful, or to test
against a beta endpoint.
Thanks for considering.
Request Type
New documentation topic
Description
Summary
Request to add historical energy data retrieval to the SPAN API so that
integrators and panel owners can programmatically access the same historical
data that is already visible in the SPAN mobile app.
Context
The mobile app exposes historical energy data in several views (Today, Week,
Month, Year) and provides a "Download data" button that produces a CSV export.
The CSV export is useful but limited in two ways:
Single metric. The export contains only aggregated home consumption.
The app UI clearly computes and displays additional values — solar
production, grid import, and (for battery owners) battery flow — in the
"Where you got your energy" visualization. These component streams are
not present in the export.
Downsampled by view. The export granularity tracks the selected UI
view rather than the underlying data resolution:
The local API, as currently documented, does not expose historical data at
all — only current state and recent buffers.
Request
Add endpoints (local API, cloud API, or local-API-proxied-to-cloud — whichever
fits SPAN's architecture) for historical retrieval of:
With standard querying semantics:
start,end)native resolution SPAN retains
On rate limiting
This does not need to be high-frequency or high-throughput access. Historical
data changes slowly by definition. Reasonable rate limits — per-panel request
caps, daily query budgets, response size limits, mandatory aggregation above
some resolution, whatever makes sense for SPAN's infrastructure — are all
acceptable. The goal is access, not real-time streaming.
Use cases
is the economically meaningful breakdown for California solar customers,
and it isn't derivable from home-consumption totals alone.
seasons, year-over-year comparisons, retrofit/appliance-change impact
analysis.
into long-term storage (e.g. HA's LTSS, InfluxDB) when a user first
installs an integration, or after a storage reset.
between tools without screen-scraping the app.
Alignment with data access obligations
Beyond the product value, this feature would directly support data access
commitments that SPAN already makes to its customers. SPAN's Supplemental
CCPA Privacy Notice acknowledges California residents' rights to know and
access the specific pieces of personal information collected about them,
and similar access and portability rights apply under other state privacy
laws (Colorado CPA, Virginia VCDPA, Connecticut CTDPA, and a growing list
of others). Residential energy telemetry tied to a specific account and
home falls within the personal information covered by these frameworks.
An API endpoint for historical data would let SPAN satisfy these access
expectations programmatically and at scale, in a format customers can
readily use — which is a materially better outcome for both SPAN and its
customers than handling requests through ad-hoc manual exports. It also
gives SPAN's privacy team a clean, self-service answer for California and
multi-state access requests as the regulatory landscape continues to
evolve.
Why this seems tractable
The data is already retained server-side (the app's visualizations are
evidence of that) and the rollup tiers visible in the mobile export suggest
a tiered aggregation store is already in place. Exposing query endpoints
over that existing store is a smaller lift than, for example, shipping a
new data product.
Happy to contribute to schema design discussion if useful, or to test
against a beta endpoint.
Thanks for considering.