Soil Moisture - Spire Weather API Documentation

Land surface and agricultural Soil Moisture data products.

Endpoints¶

Method	Endpoint	Description
GET	`/soil-moisture/region`	List regional soil moisture files
GET	`/soil-moisture/region/{file_id}`	Download regional file
GET	`/soil-moisture/point`	Get soil moisture at a point
GET	`/soil-moisture/historical/point`	Historical point data
GET	`/soil-moisture/historical/region`	Historical regional data
GET	`/soil-moisture/historical/status/{job_uuid}`	Check historical job status
GET	`/soil-moisture/historical/download/{job_uuid}`	Download historical data

List Regional Files¶

GET /soil-moisture/region

Retrieve a list of available regional soil moisture files.

Example Request¶

Shell

Python

Node.js

curl -X GET \
  'https://api.wx.spire.com/soil-moisture/region' \
  -H 'spire-api-key: YOUR_API_KEY'

Response¶

{
  "meta": {
    "count": 10
  },
  "files": [
    "soil-moisture.20240115.global.nc",
    "soil-moisture.20240114.global.nc"
  ]
}

Download Regional File¶

GET /soil-moisture/region/{file_id}

Download a specific soil moisture regional file.

Path Parameters¶

Parameter	Type	Required	Description
`file_id`	string	Yes	Filename to download

Example Request¶

Shell

Python

Node.js

curl -OJL -X GET \
  'https://api.wx.spire.com/soil-moisture/region/soil-moisture.20240115.global.nc' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/soil-moisture/region/soil-moisture.20240115.global.nc",
    headers={"spire-api-key": "YOUR_API_KEY"},
    allow_redirects=True,
)

with open("soil-moisture.20240115.global.nc", "wb") as f:
    f.write(response.content)

import { createWriteStream } from "fs";
import { Readable } from "stream";

const response = await fetch(
  "https://api.wx.spire.com/soil-moisture/region/soil-moisture.20240115.global.nc",
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);

const fileStream = createWriteStream("soil-moisture.20240115.global.nc");
Readable.fromWeb(response.body).pipe(fileStream);

Point Soil Moisture¶

GET /soil-moisture/point

Retrieve current soil moisture data for a specific location.

Parameters¶

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude (-90 to 90)
`lon`	number	Yes	Longitude (-180 to 180)
`time`	string	No	ISO 8601 timestamp

Example Request¶

Shell

Python

Node.js

curl -X GET \
  'https://api.wx.spire.com/soil-moisture/point?lat=40.0&lon=-95.0' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/soil-moisture/point",
    params={"lat": 40.0, "lon": -95.0},
    headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()

Response¶

{
  "data": [
    {
      "location": {
        "lat": 40.0,
        "lon": -95.0
      },
      "time": "2024-01-15T00:00:00Z",
      "values": {
        "soil_moisture_0_10cm": 0.35,
        "soil_moisture_10_40cm": 0.38,
        "soil_moisture_40_100cm": 0.42,
        "soil_temperature_0_10cm": 275.5
      }
    }
  ]
}

Historical Point Data¶

GET /soil-moisture/historical/point

Request historical soil moisture data for a point.

Parameters¶

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude
`lon`	number	Yes	Longitude
`start_time`	string	Yes	Start of time range (ISO 8601)
`end_time`	string	Yes	End of time range (ISO 8601)

Example Request¶

Shell

Python

Node.js

curl -X GET \
  'https://api.wx.spire.com/soil-moisture/historical/point?lat=40.0&lon=-95.0&start_time=2023-06-01T00:00:00Z&end_time=2023-06-30T00:00:00Z' \
  -H 'spire-api-key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.wx.spire.com/soil-moisture/historical/point",
    params={
        "lat": 40.0,
        "lon": -95.0,
        "start_time": "2023-06-01T00:00:00Z",
        "end_time": "2023-06-30T00:00:00Z",
    },
    headers={"spire-api-key": "YOUR_API_KEY"},
)
data = response.json()

const params = new URLSearchParams({
  lat: "40.0",
  lon: "-95.0",
  start_time: "2023-06-01T00:00:00Z",
  end_time: "2023-06-30T00:00:00Z",
});
const response = await fetch(
  `https://api.wx.spire.com/soil-moisture/historical/point?${params}`,
  { headers: { "spire-api-key": "YOUR_API_KEY" } }
);
const data = await response.json();

Historical Regional Data¶

GET /soil-moisture/historical/region

Request historical soil moisture data for a region.

Parameters¶

Parameter	Type	Required	Description
`region`	string	Yes	Region identifier
`start_time`	string	Yes	Start of time range (ISO 8601)
`end_time`	string	Yes	End of time range (ISO 8601)

Response¶

{
  "job_uuid": "abc123-def456-789xyz",
  "status": "pending"
}

Check Historical Job Status¶

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

Check the status of a historical data retrieval job.

Path Parameters¶

Parameter	Type	Required	Description
`job_uuid`	string	Yes	Job identifier

Response¶

{
  "job_uuid": "abc123-def456-789xyz",
  "status": "complete"
}

Download Historical Data¶

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

Download data from a completed historical job.

Path Parameters¶

Parameter	Type	Required	Description
`job_uuid`	string	Yes	Job identifier

Available Variables¶

Variable	Description	Units
`soil_moisture_0_10cm`	Surface layer moisture	m³/m³
`soil_moisture_10_40cm`	Shallow root zone	m³/m³
`soil_moisture_40_100cm`	Deep root zone	m³/m³
`soil_temperature_0_10cm`	Surface soil temperature	K

Use Cases¶

Agriculture¶

Monitor soil conditions for:

Irrigation scheduling
Planting decisions
Drought monitoring
Crop yield estimation

Hydrology¶

Assess soil saturation for:

Flood forecasting
Runoff modeling
Groundwater recharge

Example: Time Series Analysis¶

import requests
import pandas as pd

headers = {'spire-api-key': 'YOUR_API_KEY'}

# Get historical data
params = {
    'lat': 40.0,
    'lon': -95.0,
    'start_time': '2023-06-01T00:00:00Z',
    'end_time': '2023-06-30T00:00:00Z'
}

response = requests.get(
    'https://api.wx.spire.com/soil-moisture/historical/point',
    headers=headers,
    params=params
)

data = response.json()['data']
df = pd.DataFrame([
    {
        'time': d['time'],
        **d['values']
    }
    for d in data
])

df['time'] = pd.to_datetime(df['time'])
print(df.describe())