FAQ

Data access and API¶

For acronym definitions used in this page (for example, API, NRT, and CRS), see the Glossary and acronyms.

How do I get an API key?¶

Book a call with our team to request access. Once provisioned, your API key is passed via the spire-api-key header in all requests.

What is the difference between standard, NRT, and forecast products?¶

The feed field in every API response identifies which tier provided each data point: "standard", "nrt", or "fc".

How do I get a seamless time series without gaps?¶

Use the combined product syntax by joining product names with +:

product=d-mssm+d-mssm-nrt+d-mssm-fc

The API automatically stitches standard, NRT, and forecast data into a single continuous time series. The feed field tells you which tier each data point came from. Remember to URL-encode the + as %2B in the query string.

See Combined product queries for a worked example.

How do I access data older than 180 days?¶

The synchronous endpoints (GET /soil-moisture/region and GET /soil-moisture/point) serve the most recent 180 days. For older data, use the asynchronous historical endpoints:

1. Submit a request via POST /soil-moisture/historical/region or POST /soil-moisture/historical/point

2. Poll the job status via GET /soil-moisture/historical/status/{job_uuid}

3. Download results via GET /soil-moisture/historical/download/{job_uuid} once the status is COMPLETED

Historical jobs may take minutes to hours depending on the data volume and whether files need to be restored from cold storage.

See API endpoints for full parameter details.

What does the feed field mean?¶

The feed field is included in every API response and indicates the data tier:

• "standard" — optimal satellite data ingestion, ~4-day latency

• "nrt" — early delivery with ~1-day latency, superseded by standard data

• "fc" — forecast data, which also includes issuance_time, model, and update metadata

This field is especially useful when using combined product queries to distinguish which tier provided each data point.

Data interpretation¶

How should I filter for quality?¶

The simplest approach is to use the advisory flag:

• aflag = 0 — quality recommended (use the data)

• aflag = 1 — quality not recommended (exclude)

• aflag = 255 — no data (exclude)

For finer control, use the qflag bitmask to filter specific conditions (e.g., water bodies, frozen ground, dense vegetation). The bit definitions differ between D-MSSM and D-ESSM/D-HSSM — see Quality flags and filtering for details.

Why are some pixels set to 255 (no data)?¶

A value of 255 indicates missing or masked data. Common reasons include:

• Pre-masked conditions: Urban areas, water bodies, frozen ground, and snow/ice are automatically masked in the delivered data

• No satellite observation: The gap-filling algorithm had insufficient input data (check dai = 0 for D-MSSM)

• Outside coverage area: The pixel falls outside the product’s spatial extent

These pixels should always be excluded from analysis.

What is the difference between D-MSSM, D-ESSM, and D-HSSM?¶

All three products measure the same quantity — daily surface soil moisture in m³/m³ — but at different spatial resolutions:

D-ESSM and D-HSSM use the same downscaling methodology. Where downscaling cannot be applied (e.g., dense vegetation, water bodies), the pixel is infilled with D-MSSM gridded to the finer resolution — the eflag variable indicates which pixels were enhanced.

What does eflag = 1 (Not enhanced) mean?¶

An eflag value of 1 means the downscaling algorithm could not be applied at that pixel. Instead, the coarser D-MSSM value is used, resampled to the 500 m or 100 m grid. This typically occurs in areas with dense vegetation, urban surfaces, or water bodies where the Sentinel-1 SAR signal does not reliably capture soil moisture variability.

Pixels with eflag = 0 (Enhanced) have been downscaled and represent true high-resolution estimates.

How do I convert raw values to soil moisture?¶

For core products (D-MSSM, D-ESSM, D-HSSM):

soil_moisture = raw_value × 0.005   (m³/m³)

Valid raw values range from 0 to 254 (0.000 to 1.270 m³/m³). A raw value of 255 means no data.

For anomaly products (diff type):

anomaly = raw_value × 0.005   (m³/m³)

Anomaly files use int16 with a fill value of -9999, so negative values are valid and indicate drier-than-normal conditions.

Anomalies and forecasts¶

What is the difference between diff and prank anomalies?¶

• diff (difference) — The absolute difference between the short-term median and the long-term climatological median, in m³/m³. Positive values mean wetter than normal; negative means drier than normal.

• prank (percentile rank) — The position of current conditions within the historical distribution, expressed as a percentile (0–100). A value of 10 means current conditions are drier than 90% of the historical record; a value of 90 means wetter than 90%.

Use diff when you need physical units; use prank for standardized comparisons across regions with different baseline moisture levels.

Which climatological reference should I use (10y vs 30y)?¶

• 10y — Based on the preceding 10 years. More responsive to recent trends, better for detecting short-term shifts in a changing climate.

• 30y — Based on the preceding 30 years. More stable baseline, consistent with WMO climate normal conventions, better for long-term context.

For agricultural monitoring and drought detection, 30y is typically preferred. For applications sensitive to recent land-use changes or shifting baselines, 10y may be more appropriate.

How far ahead does the forecast go?¶

Soil moisture forecasts extend approximately 13 days into the future, driven by Spire’s SOF-D weather model.

The effective horizon varies slightly by region due to local-time matching (products are valid at local noon).

Formats and integration¶

Which file format should I use?¶

NetCDF4 is recommended for most scientific and operational applications as it contains all variables, quality flags, and metadata.

What coordinate system do the products use?¶

All products use WGS 84 (EPSG:4326) with a Plate Carrée (equidistant cylindrical) projection. Coordinates are in decimal degrees (latitude/longitude).

See Grids and coordinate reference system for full details.

How do I contact Spire soil moisture support?¶

For existing customers, reach out to your dedicated account contact or email eo-tech-support@spire.com.