API endpoints

Base URL: https://api.wx.spire.com

Authentication¶

All API requests require the spire-api-key header:

curl 'https://api.wx.spire.com/soil-moisture/region?product=d-mssm' \
  -H 'spire-api-key: ${SPIRE_API_KEY}'

Error responses¶

Status	Description
401	Unauthorized — invalid or missing API key
403	Forbidden — key does not have access to this product
412	Precondition Failed — invalid product/region combination for your token
422	Validation Error — malformed parameters

GET /soil-moisture/region¶

List available regional soil moisture files for the past 180 days.

Region query parameters¶

Parameter	Required	Description	Allowed values
`product`	No	Soil moisture product	d-mssm, d-essm, d-hssm, d-mssm-nrt, d-essm-nrt, d-hssm-nrt, d-mssm-anom, d-essm-anom, d-mssm-nrt-anom, d-essm-nrt-anom
`date`	No	Filter by date (returns files around this date)	ISO 8601 (YYYY-MM-DD)
`region`	No	Geographical domain	global, africa, asia, atlantic, europe, north-america_central-america_caribbean, south-america, south-west_pacific, or custom region
`format`	No	Data format	netcdf, geotiff
`anom_type`	No	Anomaly type (required for anomaly products)	diff, prank
`clim_ref`	No	Climatological reference (required for anomaly products)	10y, 30y
`clim_window`	No	Aggregation window (required for anomaly products)	r7day, r30day

Region response¶

{
  "meta": {
    "count": 5,
    "message": null
  },
  "files": [
    "smi.20260210.t12z.6000m.d-mssm.global.v0201.nc",
    "smi.20260211.t12z.6000m.d-mssm.global.v0201.nc"
  ]
}

Region examples¶

List global D-MSSM netCDF files:

curl 'https://api.wx.spire.com/soil-moisture/region?product=d-mssm&region=global&format=netcdf' \
  -H 'spire-api-key: ${SPIRE_API_KEY}'

List D-MSSM anomaly files for a specific date:

curl 'https://api.wx.spire.com/soil-moisture/region?product=d-mssm-anom&date=2026-02-10&region=global&format=netcdf&anom_type=diff&clim_ref=30y&clim_window=r7day' \
  -H 'spire-api-key: ${SPIRE_API_KEY}'

GET /soil-moisture/region/{file_id}¶

Download a specific regional file by its file ID (as returned by the listing endpoint).

Region file parameters¶

Parameter	Required	Description
`file_id` (path)	Yes	File name from the listing response

Region file response¶

Returns a 303 redirect to a pre-signed download URL.

Region file example¶

curl -OJL 'https://api.wx.spire.com/soil-moisture/region/smi.20260210.t12z.6000m.d-mssm.global.v0201.nc' \
  -H 'spire-api-key: ${SPIRE_API_KEY}'

The -OJL flags tell curl to follow the redirect (-L), save the file with its server-provided name (-J), and write to a file (-O).

GET /soil-moisture/point¶

Retrieve a point time series (synchronous, up to 180 days).

Point query parameters¶

Parameter	Required	Description	Allowed values
`product`	No	Soil moisture product (supports `+` syntax for combined queries)	d-mssm, d-essm, d-hssm, d-mssm-nrt, d-essm-nrt, d-hssm-nrt, d-mssm-fc, d-essm-fc, d-mssm-anom, d-essm-anom, d-mssm-nrt-anom, d-essm-nrt-anom, d-mssm-fc-anom, d-essm-fc-anom, or combined (e.g. d-mssm+d-mssm-nrt+d-mssm-fc)
`start_date`	Yes	Start of time window	ISO 8601 (YYYY-MM-DD)
`end_date`	Yes	End of time window	ISO 8601 (YYYY-MM-DD)
`lat`	Yes	Latitude	-90 to 90 (decimal degrees)
`lon`	Yes	Longitude	-180 to 180 or 0 to 360 (decimal degrees)
`format`	No	Response format (default: JSON)	JSON, CSV
`anom_type`	No	Anomaly type	diff, prank
`clim_ref`	No	Climatological reference	10y, 30y
`clim_window`	No	Aggregation window	r7day, r30day

Point response schemas by product type¶

D-MSSM values: d_mssm, pflag, qflag, data_source_am, data_source_pm, dai, lat, lon, aflag, feed

D-ESSM values: d_essm, eflag, qflag, lat, lon, aflag, feed

D-HSSM values: d_hssm, eflag, qflag, lat, lon, aflag, feed

Forecast products: Same as above plus issuance_time, model, update; feed = "fc"

Anomaly products: lat, lon, diff (or prank), feed

Point examples¶

D-MSSM JSON time series:

curl 'https://api.wx.spire.com/soil-moisture/point?product=d-mssm&start_date=2026-02-01&end_date=2026-02-14&lat=14&lon=100.5&format=JSON' \
  -H 'spire-api-key: ${SPIRE_API_KEY}'

Combined seamless time series:

curl 'https://api.wx.spire.com/soil-moisture/point?product=d-mssm%2Bd-mssm-nrt%2Bd-mssm-fc&start_date=2026-02-01&end_date=2026-02-28&lat=14&lon=100.5&format=JSON' \
  -H 'spire-api-key: ${SPIRE_API_KEY}'

POST /soil-moisture/historical/region¶

Request historical regional data for dates older than 180 days (asynchronous).

Historical region parameters¶

Parameter	Required	Description	Allowed values
`product`	No	Soil moisture product	d-mssm, d-essm, d-hssm, d-mssm-anom, d-essm-anom
`date`	Yes	Target date	ISO 8601 (YYYY-MM-DD)
`region`	Yes	Geographical domain	global, africa, asia, atlantic, europe, north-america_central-america_caribbean, south-america, south-west_pacific, or custom region
`format`	No	Data format	netcdf, geotiff
`anom_type`	No	Anomaly type	diff, prank
`clim_ref`	No	Climatological reference	10y, 30y
`clim_window`	No	Aggregation window	r7day, r30day

Historical region response¶

{
  "job_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "job_status": "CREATED"
}

Historical region example¶

curl -X POST 'https://api.wx.spire.com/soil-moisture/historical/region?product=d-mssm&region=global&date=2024-01-01&format=netcdf' \
  -H 'spire-api-key: ${SPIRE_API_KEY}'

POST /soil-moisture/historical/point¶

Request historical point data for dates older than 180 days (asynchronous).

Historical point parameters¶

Parameter	Required	Description	Allowed values
`product`	No	Soil moisture product	d-mssm, d-essm, d-hssm, d-mssm-anom, d-essm-anom
`start_date`	Yes	Start of time window	ISO 8601 (YYYY-MM-DD)
`end_date`	Yes	End of time window	ISO 8601 (YYYY-MM-DD)
`lat`	Yes	Latitude	-90 to 90
`lon`	Yes	Longitude	-180 to 180 or 0 to 360
`format`	No	Response format	JSON, CSV
`anom_type`	No	Anomaly type	diff, prank
`clim_ref`	No	Climatological reference	10y, 30y
`clim_window`	No	Aggregation window	r7day, r30day

Historical point response¶

{
  "job_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "job_status": "CREATED"
}

Historical point example¶

curl -X POST 'https://api.wx.spire.com/soil-moisture/historical/point?product=d-mssm&start_date=2023-01-01&end_date=2023-06-30&lat=14&lon=100.5&format=JSON' \
  -H 'spire-api-key: ${SPIRE_API_KEY}'

GET /soil-moisture/historical/status/{job_uuid}¶

Check the status of an asynchronous historical data request.

Historical status parameters¶

Parameter	Required	Description
`job_uuid` (path)	Yes	Job identifier returned by the historical request endpoint

Historical status response¶

{
  "job_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "job_status": "PROCESSING"
}

Job status values¶

Status	Description
`CREATED`	Job has been created and is queued
`RESTORING_FILES`	Archived data files are being restored from cold storage
`RESTORE_COMPLETED`	File restoration is complete
`INITIATED`	Processing has been initiated
`PROCESSING`	Data is being processed
`COMPLETED`	Job is complete and data is ready for download
`FAILED`	Job failed (check error details)
`UNKNOWN`	Job status cannot be determined

Historical status example¶

curl 'https://api.wx.spire.com/soil-moisture/historical/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'spire-api-key: ${SPIRE_API_KEY}'

GET /soil-moisture/historical/download/{job_uuid}¶

Download the results of a completed historical data request.

Historical download parameters¶

Parameter	Required	Description
`job_uuid` (path)	Yes	Job identifier for a completed job

Historical download response¶

Region requests: Returns a 303 redirect to a pre-signed download URL
Point requests: Returns the JSON or CSV response body directly

Historical download examples¶

# Region data — follow redirect and save file
curl -OJL 'https://api.wx.spire.com/soil-moisture/historical/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'spire-api-key: ${SPIRE_API_KEY}'

# Point data — returns inline JSON/CSV
curl 'https://api.wx.spire.com/soil-moisture/historical/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'spire-api-key: ${SPIRE_API_KEY}'