Skip to content

Regional Insights API

The Regional Insights API computes summary statistics, derived climate indicators, visualizations, and videos over a geographic region. Given a GeoJSON geometry and date range, the API processes POWER data server-side and returns area-weighted aggregates, interactive plots, or animated videos.

Additional Data Specifications:

  • Regional Insights computes results server-side over the entire region, returning area-weighted aggregates rather than a list of grid points.
  • All data are processed from the POWER daily data stores in Local Solar Time (LST).
  • Geometry is provided as a GeoJSON Feature (Polygon or MultiPolygon).

Where Regional Insights Fits

Regional Insights is the API behind the Insights tool in the Data Access Viewer (DAV). It is also accessible through the get_regional_insights MCP tool.

Services

Services Description
Insights Computes regional statistics and derived indicators over a geographic area for a given time period.
Visualizations Generates Hovmoller diagrams for a region showing parameter variation across latitude and time.
Videos Creates animated MP4 videos of parameter values over a region across a time range.

Formats

Formats Available Services Purpose
JSON Yes Insights, Visualizations GeoJSON FeatureCollection response. This is the default.
HTML Yes Insights, Visualizations Interactive Folium map rendering of the result.
Shapefile Yes Insights ESRI Shapefile download for GIS applications.
Input Data Yes Insights, Visualizations, Videos NetCDF file of the source data used in the computation.
MP4 Yes Videos Animated video file.

Insights Collections

Each insights request specifies a collection that determines the computation performed:

Collection Description Required Parameters
variable Area-weighted mean, median, min, max, and standard deviation for each parameter. Yes
zone-difference Difference between two time periods (climate change indicator). No
energy-drought Concurrent solar and wind energy shortfall analysis. No
freeze-thaw Freeze-thaw cycle counts and durations from daily temperature data. No

Request Structure

  • The request arguments can be in any order after the question mark.
  • A GeoJSON Feature (Polygon or MultiPolygon) is required as the geometry parameter.
  • The collection parameter selects the type of analysis.

To help construct and test API requests, use the API Pages for the POWER Regional Insights API.

Insights

Variable

Returns area-weighted statistics (mean, median, min, max, standard deviation) for one or more parameters over the region.

1
/api/application/insights?collection=variable&community=RE&parameters=T2M,WS10M&start=2024-01-01&end=2024-01-31&geometry={"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-80,35],[-78,35],[-78,37],[-80,37],[-80,35]]]}}&format=json

1
/api/application/insights?collection=variable&community=RE&parameters=T2M,ALLSKY_SFC_SW_DWN&start=2024-06-01&end=2024-06-30&geometry={"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-120,34],[-118,34],[-118,36],[-120,36],[-120,34]]]}}&format=html

1
/api/application/insights?collection=variable&community=RE&parameters=T2M&start=2024-01-01&end=2024-01-31&geometry={"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-80,35],[-78,35],[-78,37],[-80,37],[-80,35]]]}}&units=imperial&format=json

Zone Difference

Returns the difference between two time periods for thermal zone classification, useful for building planning analysis.

1
/api/application/insights?collection=zone-difference&community=RE&start=2000-01-01&end=2009-12-31&compare-start=2010-01-01&compare-end=2019-12-31&geometry={"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-100,30],[-90,30],[-90,40],[-100,40],[-100,30]]]}}&format=json

Energy Drought

Returns concurrent solar and wind energy shortfall statistics based on Wilczak et al. (2024).

1
/api/application/insights?collection=energy-drought&community=RE&start=2020-01-01&end=2020-12-31&geometry={"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-100,30],[-90,30],[-90,40],[-100,40],[-100,30]]]}}&format=json

Freeze-Thaw

Returns freeze-thaw cycle counts and statistics from daily temperature data.

1
/api/application/insights?collection=freeze-thaw&community=RE&start=2023-01-01&end=2023-03-31&geometry={"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-80,38],[-76,38],[-76,42],[-80,42],[-80,38]]]}}&format=json

1
/api/application/insights?collection=freeze-thaw&community=RE&start=2023-01-01&end=2023-03-31&geometry={"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-80,38],[-76,38],[-76,42],[-80,42],[-80,38]]]}}&format=contour-image

Visualizations

Hovmoller

Returns a Hovmoller diagram showing how a parameter varies across latitude (or time) for a region.

1
/api/application/hovmoller?parameter=T2M&community=RE&start=2000-01-01&end=2024-12-31&time-standard=utc&geometry={"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-100,30],[-90,30],[-90,40],[-100,40],[-100,30]]]}}&format=json

1
/api/application/hovmoller?parameter=ALLSKY_SFC_SW_DWN&community=RE&start=2020-01-01&end=2024-12-31&time-standard=utc&timeseries=true&geometry={"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-100,30],[-90,30],[-90,40],[-100,40],[-100,30]]]}}&format=json

1
/api/application/hovmoller?parameter=T2M&community=RE&start=2000-01-01&end=2024-12-31&time-standard=utc&anomalies=true&geometry={"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-100,30],[-90,30],[-90,40],[-100,40],[-100,30]]]}}&format=json

Videos

Returns an animated MP4 video of a parameter over the specified region and time range. The video endpoint defaults to a global extent if no geometry is provided.

1
/api/application/video?parameter=T2M&community=RE&start=2025-01-01&end=2025-01-01&time-standard=utc&temporal=hourly&fps=1

1
/api/application/video?parameter=ALLSKY_SFC_SW_DWN&community=RE&start=2025-01-01&end=2025-01-01&time-standard=utc&temporal=hourly&fps=2&geometry={"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-100,25],[-80,25],[-80,50],[-100,50],[-100,25]]]}}

Styling Demos

The API includes styling demonstration endpoints that illustrate available cartographic rendering options:

Endpoint Description
/api/application/insights/styling-demo/simple-polygon Simple polygon with fill and stroke.
/api/application/insights/styling-demo/equal-interval-choropleth Equal-interval choropleth over a 5x5 grid.
/api/application/insights/styling-demo/quantile-choropleth Quantile choropleth with skewed distribution.
/api/application/insights/styling-demo/jenks-choropleth Jenks natural-breaks choropleth.
/api/application/insights/styling-demo/categorical-zones Categorical styling (zone difference).
/api/application/insights/styling-demo/diverging-anomaly Diverging scale (temperature anomaly).
/api/application/insights/styling-demo/sequential-precip Sequential scale (precipitation).
/api/application/insights/styling-demo/point-markers Point markers with color, size, and symbol.
/api/application/insights/styling-demo/linestring-styling LineString styling (stroke width/opacity/dash).
/api/application/insights/styling-demo/mixed-geometry Mixed geometry FeatureCollection.
/api/application/insights/styling-demo/stroke-only-overlay Stroke-only overlay (transparent fill).
/api/application/insights/styling-demo/opacity-ramp-nodata Data-driven opacity ramp with NoData features.

Limitations

Geometry

  • A GeoJSON Feature with a Polygon or MultiPolygon geometry is required for all insights and visualization endpoints.

Time Range

  • All insights endpoints process daily data. Hourly data are available for the video endpoint only.
  • The zone-difference collection requires both a primary and comparison time range (compare-start, compare-end).

OpenAPI Reference

The authoritative request/response schema for every Regional Insights endpoint is published on the POWER Regional Insights API Pages.

See Also