Skip to content

Projection API

The Projection microservice API returns analysis-ready climate projection data and visualizations derived from the NASA Earth Exchange Global Daily Downscaled Projections (NEX-GDDP-CMIP6). Data are read directly from the POWER AWS S3 archive for the nearest grid cell to the requested location.

Additional Data Specifications:

  • Provides parameters by day and by month for 2015–2100.
  • Data are provided on a 0.25° x 0.25° global grid; the nearest grid cell is selected without interpolation.
  • Each response includes three Shared Socioeconomic Pathway (SSP) scenarios unless a single scenario is requested.
  • The default model is the multi-model ensemble; individual CMIP6 models can be selected.

Services

Services Description
Daily Point Provides parameters by day for a single point.
Monthly Point Provides parameters by month for a single point.
Daily Plot Provides an interactive time series plot of daily parameters for a single point.
Models Lists the models published in the daily or monthly data store.
Climatology Comparison Compares degree days between two year ranges, including the difference and its uncertainty.
Visualizations Provide thermal zone, line, and bar plots of derived climate indicators.

Scenarios

Value Description
ssp126 SSP1-2.6: sustainable development, low emissions.
ssp245 SSP2-4.5: middle of the road, intermediate emissions.
ssp370 SSP3-7.0: regional rivalry, high emissions.

Tip

Omit scenario to receive all three scenarios in one response. Supplying scenario on the Daily Point, Monthly Point, or Daily Plot services filters the AWS S3 data to that scenario; JSON keys, CSV and ASCII columns, XARRAY coordinates, and plot lines contain only the selected scenario. An unsupported value returns a 422 error.

Models

The model argument defaults to ensemble and accepts the following lowercase CMIP6 model identifiers:

access_cm2, access_esm1_5, bcc_csm2_mr, cesm2, cmcc_esm2, cnrm_cm6_1, cnrm_esm2_1, ec_earth3, fgoals_g3, gfdl_esm4, giss_e2_1_g, inm_cm4_8, inm_cm5_0, ipsl_cm6a_lr, kace_1_0_g, miroc6, miroc_es2l, mpi_esm1_2_hr, mpi_esm1_2_lr, mri_esm2_0, noresm2_lm, noresm2_mm

Model Availability

Not every model is present in every data store. Use the Models service to list the models available for the daily or monthly data store before submitting a request. A model that is absent from the selected store returns a 422 error.

Parameters

Parameter Description Daily Monthly
T2M Temperature at 2 Meters Yes Yes
T2M_MAX Temperature at 2 Meters Maximum Yes Yes
T2M_MIN Temperature at 2 Meters Minimum Yes Yes
RH2M Relative Humidity at 2 Meters Yes Yes
QV2M Specific Humidity at 2 Meters Yes Yes
PRECTOTCORR Precipitation Corrected Yes Yes
WS10M Wind Speed at 10 Meters Yes Yes
ALLSKY_SFC_SW_DWN All Sky Surface Shortwave Downward Irradiance Yes Yes
ALLSKY_SFC_LW_DWN All Sky Surface Longwave Downward Irradiance Yes Yes
HDD18_3 Heating Degree Days Below 18.3 °C Yes Yes
CDD10 Cooling Degree Days Above 10 °C Yes Yes

Degree Days

HDD18_3 and CDD10 are computed on the fly from the mean of T2M_MIN and T2M_MAX. Monthly degree days are computed from monthly extrema; they are not a sum of daily degree days.

HDD18\_3 = \max(0,\ 18.3 - \bar{T}) \qquad CDD10 = \max(0,\ \bar{T} - 10)

Formats

Formats Daily Point Monthly Point Daily Plot Climatology Comparison Visualizations
JSON Yes Yes Yes Yes Yes
CSV Yes Yes No Yes No
ASCII Yes Yes No Yes No
XARRAY Yes Yes No Yes No
HTML No No Yes No Yes
  • JSON is the default format for data and Daily Plot requests; HTML is the default for Visualizations.
  • JSON responses are organized as parameter -> scenario -> date.
  • CSV and ASCII responses use scenario-suffixed columns such as T2M_SSP126.
  • XARRAY responses return a JSON-serialized Xarray data set that retains the scenario coordinate.
  • Plots support theme=light (default) or theme=dark.

Time Standard

The Projection API provides data in Universal Time Coordinated (UTC).

  • Daily and monthly data are available from 2015/01/01 to 2100/12/31, including leap days.
  • Use time-standard=UTC in the API request URL; other time standards are rejected.

Limitations

Spatial Coverage

  • Latitude must be between -59.875 and 89.875; longitude must be between -179.875 and 179.875.
  • The selected grid cell center may differ from the requested coordinates.
  • Spatial coverage does not guarantee values for every model, scenario, parameter, and date. Missing values return -999 in data responses and appear as gaps in plots.

Request Size

The request size is calculated as the number of time steps x the number of parameters x the number of scenarios.

Service Format Maximum Values
Point JSON 250,000
Point XARRAY 125,000
Point CSV, ASCII 500,000
Daily Plot JSON, HTML 100,000

Daily Plot requests are limited to five parameters.

Visualization Parameters

  • Climatology Comparison and Bar plots support CDD10 and HDD18_3.
  • Line plots support CDD10, HDD18_3, and TMAX_DAYS_35C (annual count of days with a maximum temperature above 35 °C).
  • Zone plots support t_zone (thermal zones) and tm_zone (thermal-moisture zones), calculated with a four-year rolling window.

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'.
  • Daily requests use YYYYMMDD dates, monthly requests use YYYYMM dates, and comparison and visualization requests use YYYY years.

Examples

Daily Point

1
/api/projection/daily/point?parameters=T2M&community=SB&longitude=-104.99&latitude=39.74&start=20500101&end=20501231&format=JSON&time-standard=UTC

1
/api/projection/daily/point?parameters=T2M,PRECTOTCORR&community=AG&longitude=-104.99&latitude=39.74&start=20500101&end=20501231&format=CSV&time-standard=UTC&scenario=ssp245

1
/api/projection/daily/point?parameters=T2M_MAX,T2M_MIN&community=RE&longitude=-104.99&latitude=39.74&start=20500101&end=20501231&format=JSON&time-standard=UTC&model=cesm2

Monthly Point

1
/api/projection/monthly/point?parameters=T2M&community=SB&longitude=-104.99&latitude=39.74&start=201501&end=210012&format=JSON&time-standard=UTC

1
/api/projection/monthly/point?parameters=HDD18_3,CDD10&community=SB&longitude=-104.99&latitude=39.74&start=201501&end=210012&format=CSV&time-standard=UTC

1
/api/projection/monthly/point?parameters=T2M&community=SB&longitude=-104.99&latitude=39.74&start=201501&end=210012&format=JSON&time-standard=UTC&scenario=ssp370

Daily Plot

1
/api/projection/daily/plot?parameters=T2M&community=SB&longitude=-104.99&latitude=39.74&start=20500101&end=20501231&format=HTML&time-standard=UTC&theme=light

1
/api/projection/daily/plot?parameters=T2M&community=SB&longitude=-104.99&latitude=39.74&start=20500101&end=20501231&format=JSON&time-standard=UTC

Models

1
/api/projection/models?temporal=daily

Climatology Comparison

1
/api/projection/climatology/comparison?parameter=hdd18_3&longitude=-104.99&latitude=39.74&period_one_start=2015&period_one_end=2025&period_two_start=2090&period_two_end=2100&format=JSON

Visualizations

1
/api/projection/visualization/zones?parameter=t_zone&longitude=-104.99&latitude=39.74&start=2015&end=2100&format=HTML&theme=light

1
/api/projection/visualization/line?parameter=tmax_days_35c&longitude=-104.99&latitude=39.74&start=2015&end=2100&format=HTML&theme=light

1
/api/projection/visualization/bar?parameter=cdd10&longitude=-104.99&latitude=39.74&period_one_start=2015&period_one_end=2025&period_two_start=2090&period_two_end=2100&format=HTML&theme=dark

Deprecated Routes

Legacy Namespace

Routes under /api/projection/legacy/ serve the previous NASA-site data products and return deprecation headers. These routes select the nearest processed NASA site instead of the nearest grid cell and will be removed in a future release. New applications should use the routes documented above.

Route Description
/api/projection/legacy/daily/point Precomputed single-model, single-scenario NASA-site daily data. Defaults to model=ensemble and scenario=ssp126.
/api/projection/legacy/daily/plot Precomputed single-scenario NASA-site plot when scenario is supplied; otherwise returns the Daily Plot service.
/api/projection/legacy/annual/point Stored NASA-site annual data.
/api/projection/legacy/climatology/comparison Site-based climatology comparison.
/api/projection/legacy/visualization/zones Site-based thermal zone plots.
/api/projection/legacy/visualization/line Site-based line plots, including site-only thematic parameters.
/api/projection/legacy/visualization/bar Site-based bar plots, including site-only thematic parameters.
/api/projection/legacy/utilities/sites GeoJSON list of processed NASA sites.
/api/projection/legacy/utilities/site-grids GeoJSON grid cells for processed NASA sites.
/api/projection/legacy/utilities/nearest-site GeoJSON for the NASA site nearest to the requested coordinates.

Legacy Daily Point and Plot Differences

  • Precomputed requests use a site-based model catalog that differs from the Models service.
  • JSON responses are organized as parameter -> date for the single selected scenario and report the selected NASA-site coordinates and elevation.
  • CSV and ASCII columns are not scenario-suffixed, and XARRAY responses contain time, lat, and lon dimensions without a scenario dimension.
  • Switching to the Daily Point or Daily Plot service changes the data source, location selection, and response structure.
1
/api/projection/legacy/daily/point?parameters=T2M&community=SB&longitude=-104.99&latitude=39.74&start=20240101&end=20240131&format=JSON&time-standard=UTC&model=ensemble&scenario=ssp245