Skip to content

Regional Insights API

Beta

The Regional Insights API is in beta. The collections, methods, and outputs are under science review and are subject to change.

The Regional Insights microservice API computes analysis-ready statistics and derived climate indicators over a user-defined region. Given a GeoJSON Feature and a date range, the API loads POWER data for every grid cell in the region, processes the data server-side, and returns cosine-latitude weighted aggregates or one result per grid cell.

Additional Data Specifications:

  • Provides daily data from 1981/01/01 to the current date in Local Solar Time (LST) by default or in Coordinated Universal Time (UTC) on request; the ASHRAE Design Conditions collection uses hourly LST data, and the Zone Difference collection uses UTC data.
  • Accepts a GeoJSON Feature with a Polygon or MultiPolygon geometry as the region of interest.
  • Each request selects one collection, which determines the analysis, the input parameters, and the output properties.
  • Results are returned for the whole region (area) or for each grid cell whose center lies inside the region (grid-cell).

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 climate indicators for a selected collection.
Settings Lists the available collections, their inputs, and their response formats.
HEC-DSS Export Downloads a fixed six-parameter daily data set as a binary HEC-DSS file.
Hovmöller Creates a Hovmöller visualization of a parameter as an annual cycle or a time series.
Styling Demos Return synthetic GeoJSON examples of the cartographic styling applied to Insights responses.

Collections

Collection Description Input Parameters Grid Cell Additional Arguments
variable Weighted mean, minimum, maximum, and standard deviation for each parameter; sum for precipitation parameters. User selected (up to five) Yes parameters, parameter-options
anomaly-detection Request-period outlier screen (3 standard deviations) and linear trend slope, p-value, and r² for each parameter. User selected (up to five) Yes parameters
wind-chill National Weather Service (NWS) wind chill index with a cold-risk category. T2M, WS2M Yes
heat-index NWS heat index (Rothfusz regression with adjustments) with a heat-risk category. T2M, RH2M Yes
freeze-thaw Freeze-thaw day counts (T2M_MAX > 0 °C and T2M_MIN < 0 °C) with annual mean, minimum, maximum, and standard deviation. T2M, T2M_MAX, T2M_MIN Yes
growing-season Growing degree days at a selected base temperature, frost dates, frost-free dates, and growing-season length. T2M_MIN, T2M_MAX Yes gdd-threshold
hvac-degree-days Mean annual heating and cooling degree days, thermal climate zone, dominant load, and an indicative planning note. T2M_MIN, T2M_MAX Yes
zone-difference Thermal and thermal-moisture climate zones for two periods and the difference between them. Degree days and precipitation Yes compare-start, compare-end
energy-drought Wind and solar capacity factors and energy-drought frequency, duration, intensity, and deficit (Wilczak et al., 2024). WS50M, ALLSKY_SFC_SW_DWN Yes
ashrae-design-conditions ASHRAE climate design conditions, including dry-bulb percentiles, degree days, and 5–50-year return-period extremes. 11 hourly parameters Yes

Collection Notes

  • zone-difference returns grid-cell results by default; all other collections default to area.
  • zone-difference expands both periods to complete calendar years and returns thermal zones 0–8 with moisture subtypes encoded as numbers (for example, 3A = 31 and 3B = 32).
  • energy-drought defines a drought day as a daily capacity factor below the 20th percentile of the requested period. When both inputs are available, the combined capacity factor weights wind and solar equally.
  • growing-season accepts gdd-threshold values of 4.4, 7.2, 10 (default), 13.3, and 15.6 °C; frost is defined as T2M_MIN ≤ 0 °C.
  • hvac-degree-days reports HDD18.3 and CDD10 for compatibility with other POWER products and 65 °F-base degree days for the dominant-load label. The planning note is not an equipment or sizing recommendation.
  • anomaly-detection screens outliers within the requested period; it does not compute anomalies against a climatological baseline.

Indicator Interpretation

wind-chill, heat-index, freeze-thaw, and energy-drought are computed from daily mean or daily extreme values. These indicators do not represent sub-daily peak exposure, hub-height wind, or plant-specific energy yield. Each response includes the years used, coverage, and method caveats where applicable.

Spatial Aggregation

Value Geometry Features
area The input Polygon or MultiPolygon. One feature containing cosine-latitude weighted statistics for the whole region.
grid-cell One unclipped pixel polygon for each selected grid cell. One feature per grid cell whose center lies inside the region, with lat and lon properties.

Tip

When a region is smaller than a single grid cell and contains no grid-cell center, the API uses the nearest grid cell and reports the fallback in the response properties.

Formats

Formats Insights HEC-DSS Export Hovmöller Description
JSON Yes No Yes GeoJSON FeatureCollection with styled properties. This is the default.
HTML Yes No Yes Interactive map or plot.
SHAPEFILE Yes No No ESRI Shapefile download for GIS applications.
INPUT-DATA Yes No No Link to a NetCDF file of the source data used in the computation.
CONTOUR Yes No No GeoJSON contour bands clipped to the region.
CONTOUR-IMAGE Yes No No PNG contour image with the region boundary overlay.
DSS No Yes No Binary HEC-DSS file.
  • contour and contour-image are available for the freeze-thaw collection only.
  • input-data is not available for the ashrae-design-conditions collection.
  • GeoJSON responses follow the simplestyle specification (fill, stroke, title, description) so that web maps render the results without additional styling.
  • Use units=metric (default) or units=imperial; some outputs, such as capacity factors and zone codes, are unitless.

Time Standard

The Insights API provides data in Local Solar Time (LST) by default. Use the time-standard argument to select lst (default) or utc.

Collection or Service Time Standard
variable, anomaly-detection, wind-chill, heat-index, freeze-thaw, growing-season, hvac-degree-days, energy-drought lst (default) or utc
ashrae-design-conditions lst only (hourly data)
zone-difference utc only
Hovmöller lst (default) or utc
  • Data are available from 1981/01/01 to the current date. Individual source products may have narrower availability.
  • Dates use the YYYY-MM-DD format, and both start and end are inclusive.
  • The selected time standard also applies to the input-data NetCDF file, whose name includes LST or UTC.

Hovmöller Default Change

The Hovmöller service now defaults to time-standard=lst; it previously defaulted to utc. Send time-standard=utc to keep the previous behavior.

Limitations

Geometry

  • A GeoJSON Feature with a Polygon or MultiPolygon geometry is required. Supply the Feature as a URL-encoded geometry value for GET requests or as the request body for POST requests.
  • Grid-cell rectangles represent full source pixels and are not clipped to the region boundary.
  • Large regions and long date ranges increase processing time and response size.

Collection Constraints

  • The variable and anomaly-detection collections accept a maximum of five parameters.
  • The zone-difference collection requires compare-start and compare-end.
  • The ashrae-design-conditions collection requires at least two years of data and limits grid-cell requests to 16 grid cells.
  • The parameter-options argument is supported by the variable collection only.
  • The ashrae-design-conditions collection accepts time-standard=lst only, and the zone-difference collection accepts time-standard=utc only; requesting the other standard returns HTTP 422.

HEC-DSS Export

  • Returns six fixed daily parameters in metric units: T2M_MAX, T2M_MIN, T2MDEW, RH2M, WS2M, and ALLSKY_SFC_SW_DWN.
  • Does not accept collection, parameters, units, or format.
  • area writes one series per parameter; grid-cell writes one series per grid cell and parameter. Missing values are written as -999.0.

Request Structure

  • The request arguments can be in any order after the question mark.
  • A single parameter or a list of parameters can be selected with one of the following list separators: ',' or '%2C'.
  • The geometry argument must be a URL-encoded GeoJSON Feature for GET requests; POST requests send the Feature in the request body with the same query arguments.
  • The community argument accepts RE, SB, AG, or HY.

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

Examples

Insights

1
/api/application/insights?collection=variable&community=RE&parameters=T2M,PRECTOTCORR&start=2024-01-01&end=2024-01-31&spatial-aggregation=area&format=JSON&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}
1
/api/application/insights?collection=anomaly-detection&community=RE&parameters=T2M&start=2020-01-01&end=2021-12-31&spatial-aggregation=grid-cell&format=JSON&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}
1
/api/application/insights?collection=wind-chill&community=RE&start=2024-01-01&end=2024-01-31&time-standard=utc&format=JSON&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}
1
/api/application/insights?collection=heat-index&community=RE&start=2024-07-01&end=2024-07-31&units=imperial&format=HTML&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}
1
/api/application/insights?collection=freeze-thaw&community=RE&start=2020-01-01&end=2020-12-31&format=CONTOUR-IMAGE&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}
1
/api/application/insights?collection=growing-season&community=AG&start=2020-01-01&end=2024-12-31&gdd-threshold=10&format=JSON&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}
1
/api/application/insights?collection=hvac-degree-days&community=SB&start=2020-01-01&end=2024-12-31&format=JSON&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}
1
/api/application/insights?collection=zone-difference&community=SB&start=2004-01-01&end=2008-12-31&compare-start=2020-01-01&compare-end=2024-12-31&format=JSON&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}
1
/api/application/insights?collection=energy-drought&community=RE&start=2020-01-01&end=2020-12-31&format=JSON&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}
1
/api/application/insights?collection=ashrae-design-conditions&community=SB&start=2020-01-01&end=2021-12-31&format=JSON&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}

Settings

1
/api/application/insights/settings

HEC-DSS Export

1
/api/application/insights/export/dss?community=RE&start=2024-01-01&end=2024-01-31&spatial-aggregation=area&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}
1
/api/application/insights/export/dss?community=RE&start=2024-01-01&end=2024-01-31&spatial-aggregation=grid-cell&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-83.5,39.5],[-82.0,39.5],[-82.0,40.5],[-83.5,40.5],[-83.5,39.5]]]}}

Hovmöller

1
/api/application/insights/hovmoller?parameter=T2M&community=RE&start=2000-01-01&end=2024-12-31&time-standard=lst&format=HTML&theme=light&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-100,30],[-90,30],[-90,40],[-100,40],[-100,30]]]}}
1
/api/application/insights/hovmoller?parameter=ALLSKY_SFC_SW_DWN&community=RE&start=2020-01-01&end=2024-12-31&time-standard=lst&timeseries=true&format=JSON&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-100,30],[-90,30],[-90,40],[-100,40],[-100,30]]]}}
1
/api/application/insights/hovmoller?parameter=T2M&community=RE&start=2000-01-01&end=2024-12-31&time-standard=lst&anomalies=true&format=HTML&theme=dark&geometry={"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-100,30],[-90,30],[-90,40],[-100,40],[-100,30]]]}}

Styling Demos

The styling demo routes return synthetic GeoJSON that illustrates the cartographic options applied to Insights responses. List all routes with /api/application/insights/styling-demo/.

Route Description
simple-polygon Simple polygon with fill and stroke.
contour-lines Topographic elevation contour lines.
bathymetry-depth-bands Irregular ocean depth-zone polygons.
river-network River network styled by Strahler stream order.
hydropower-reservoir MultiPolygon reservoir with buffer zones.
hex-tessellation Hexagonal tessellation of wind capacity factor.
watershed-basins Irregular watershed sub-basins styled by annual runoff.
point-markers Point markers with color, size, and symbol.
linestring-styling LineString stroke width, opacity, and dash styling.
mixed-geometry Mixed geometry FeatureCollection.
stroke-only-overlay Stroke-only overlay with a transparent fill.
opacity-ramp-nodata Data-driven opacity ramp with NoData features.
1
/api/application/insights/styling-demo/hex-tessellation

OpenAPI Reference

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

See Also