Fetch Water Stress

The /fetch_water_stress endpoint retrieves water stress and availability metrics for individual plots or aggregated statistics. This endpoint provides water stress indices, precipitation-to-PET (Potential Evapotranspiration) ratios, soil moisture percentiles, and evapotranspiration anomalies.

Endpoint

GET /fetch_water_stress

Parameters

Parameter	Type	Required	Default	Description
filename	string	No	None	Collection identifier
monitoring_start	string	No	None	Monitoring start date (YYYY-MM-DD)
monitoring_end	string	No	None	Monitoring end date (YYYY-MM-DD)
limit	integer	No	None	Number of plots to fetch. If not provided, returns by default up to 10000 plots for aggregate=False case, or returns the first matching case for aggregate=True case.
aggregate	boolean	No	false	Aggregate results into a single row
plots_only	boolean	No	false	Return plots only without statistics. When true, returns base collection data without any statistical calculations

Dynamic Filtering

You can filter results using any column name from the batch table as a query parameter:

# Filter by plot ID (returns first matching plot, limit=1)
/fetch_water_stress?plotid=12345

# Filter by collection ID
/fetch_water_stress?collection_id=abc123

# Filter by facility ID
/fetch_water_stress?facility_id=xyz789

# Filter by custom metadata fields (e.g., from batch uploads)
# Returns all matching rows across all matching collections (limit=10000)
/fetch_water_stress?clientid=ABC123
/fetch_water_stress?producerid=PROD456

# Combine multiple filters
/fetch_water_stress?collection_id=abc123&monitoring_start=2020-01-01
/fetch_water_stress?clientid=ABC123&plotid=12345

Note on limit behavior: - When filtering by custom metadata fields (like clientid, producerid, partid) that were provided during batch upload, the endpoint returns all matching rows across all matching collections (default limit=10000) - When filtering by fields from the uploaded file (like plotid, uuid, name), the endpoint returns the first matching row (default limit=1) - The filename parameter takes priority - if provided, it queries only that specific collection and ignores custom metadata collection lookup

Response Format

The endpoint returns streaming NDJSON (Newline Delimited JSON) responses. Each line is a complete GeoJSON (Geographic JSON) Feature.

Non-Aggregate Response (aggregate=false)

When aggregate=false (default), the endpoint returns individual plot features with water stress metrics.

Response Structure

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[longitude, latitude], ...]]
  },
  "properties": {
    "uuid": "c0db3327-755f-4078-bb9d-237f76df4aa7", // (1)!
    "plotid": "f881a77f-17f4-5da3-9870-e7730938a6bf", // (2)!
    "collection_id": "abc123", // (3)!
    "facility_id": "xyz789", // (4)!
    "ingestion_date": "2024-01-10T00:00:00+00:00", // (5)!
    "monitoring_start": "2017-01-01T00:00:00+00:00", // (6)!
    "monitoring_end": "2024-01-10T00:00:00+00:00", // (7)!
    "area": 3.945736451658705, // (8)!
    "precipitation_pet_ratio": 0.85, // (9)!
    "soil_moisture_percentile": 0.65, // (10)!
    "evapotranspiration_anomaly": -0.12, // (11)!
    "water_stress_index": 0.45, // (12)!
    "annual_water_stress": { // (13)!
      "mean": 0.45,
      "std": 0.15,
      "2020": 0.42,
      "2021": 0.48,
      "2022": 0.44,
      "2023": 0.46
    },
    "thumbnail_url": "https://storage.googleapis.com/...", // (14)!
    "metadata": { // (15)!
      "area": 1.18,
      "farmerCode": "SCH_BEO_AXE1_BON_BON_0030",
      "farmerId": "d6938606-158a-43d2-be0a-cb6c1eb998ef",
      "farmerName": "KOUADIO Adjoua ",
      "name": "KOUADIO Adjoua",
      "plotArea": 1.18,
      "plotCode": null,
      "plotId": "ec166918-b7a2-47ac-bff4-010776a4a999"
    }
  }
}

1. Unique identifier for the plot
2. Plot identifier from the original collection
3. Collection identifier
4. Facility identifier associated with the plot
5. Date when the plot was ingested into the system (ISO 8601 (International Organization for Standardization) timestamp)
6. Start date of the monitoring period (ISO 8601 timestamp)
7. End date of the monitoring period (ISO 8601 timestamp)
8. Plot area in hectares
9. Ratio of precipitation to PET (Potential Evapotranspiration). Values > 1.0 indicate water surplus, values < 1.0 indicate water deficit.
10. Soil moisture percentile (0.0 to 1.0), indicating how current soil moisture compares to historical conditions. Higher values indicate wetter conditions.
11. Evapotranspiration anomaly, indicating deviation from normal conditions. Negative values indicate below-normal evapotranspiration, positive values indicate above-normal.
12. Composite water stress index (0.0 to 1.0), where higher values indicate greater water stress. This index combines multiple water availability indicators.
13. JSON string containing annual water stress statistics. When parsed, contains: mean (mean annual water stress index 0.0-1.0), std (standard deviation), YYYY (water stress index for specific year, e.g., "2021": 0.48)
14. URL to thumbnail image showing water stress visualization, or null if not available
15. Custom metadata from the original collection upload. This object contains user-provided attributes that were included during batch processing. The structure varies by collection and may include fields like farmerName, plotCode, plotId, farmerId, or any other custom attributes provided during upload.

Aggregate Response (aggregate=true)

When aggregate=true, the endpoint returns a single feature with aggregated water stress statistics across all matching plots.

Response Structure

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[longitude, latitude], ...]]
  },
  "properties": {
    // Base collection fields (from original table)
    "collection_id": "abc123",
    "facility_id": "xyz789",
    "ingestion_date": "2024-01-10T00:00:00+00:00",
    "monitoring_start": "2017-01-01",
    "monitoring_end": "2024-01-10",

    // Aggregated water stress statistics
    "precipitation_pet_ratio": 0.82,
    "soil_moisture_percentile": 0.68,
    "evapotranspiration_anomaly": -0.10,
    "water_stress_index": 0.48,

    // Aggregated annual water stress (returned as JSON string, shown here deserialized)
    "annual_water_stress": {
      "mean": 0.45,
      "std": 0.15,
      "2020": 0.42,
      "2021": 0.48,
      "2022": 0.44,
      "2023": 0.46
    },

    // Aggregated area and plot count
    "aggregate_area": 4567.8,
    "aggregate_plot_count": 1250,

    // Custom metadata from original collection (may be empty object {})
    "metadata": {}
  }
}

Field Descriptions

• collection_id (string): Collection identifier
• facility_id (string): Facility identifier
• ingestion_date (timestamp): Most recent ingestion date
• monitoring_start (string): Earliest monitoring start date (YYYY-MM-DD)
• monitoring_end (string): Latest monitoring end date (YYYY-MM-DD)
• precipitation_pet_ratio (float): Average precipitation-to-PET ratio across all plots
• soil_moisture_percentile (float): Average soil moisture percentile across all plots
• evapotranspiration_anomaly (float): Average evapotranspiration anomaly across all plots
• water_stress_index (float): Average water stress index across all plots
• annual_water_stress (string): Aggregated annual water stress statistics (weighted average by area)
• aggregate_area (float): Total area of all plots (hectares)
• aggregate_plot_count (integer): Total number of distinct plots
• metadata (object): Custom metadata from the original collection (may be empty object {}). When aggregating, metadata is typically not included as it varies per plot.

Plots Only Response (plots_only=true)

When plots_only=true, the endpoint returns base collection data without water stress statistics. This is useful when statistics haven't been computed yet or when you only need plot geometries and basic metadata.

Response Structure

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[longitude, latitude], ...]]
  },
  "properties": {
    "uuid": "15bdfb54-e621-40cc-80ce-bb4704562b26", // (1)!
    "plotid": "ec166918-b7a2-47ac-bff4-010776a4a999", // (2)!
    "ingestion_date": "2025-11-18T13:38:23+00:00", // (3)!
    "area": 1.201948, // (4)!
    "metadata": { // (5)!
      "area": 1.18,
      "farmerCode": "SCH_BEO_AXE1_BON_BON_0030",
      "farmerId": "d6938606-158a-43d2-be0a-cb6c1eb998ef",
      "farmerName": "KOUADIO Adjoua ",
      "name": "KOUADIO Adjoua",
      "plotArea": 1.18,
      "plotCode": null,
      "plotId": "ec166918-b7a2-47ac-bff4-010776a4a999"
    }
  }
}

1. Unique identifier for the plot
2. Plot identifier from the original collection
3. Date when the plot was ingested into the system (ISO 8601 timestamp)
4. Plot area in hectares
5. Custom metadata from the original collection upload. This object contains user-provided attributes that were included during batch processing. The structure varies by collection and may include fields like farmerName, plotCode, plotId, farmerId, or any other custom attributes provided during upload. Note: No water stress fields are included when plots_only=true.

Usage Examples

Python Example

import requests
import json

headers = {
    "Authorization": "Bearer <your_token>"
}

# Fetch individual plots with water stress data
response = requests.get(
    "https://epoch-sco2-api.com/fetch_water_stress",
    params={
        "filename": "your_collection_name",
        "monitoring_start": "2017-01-01",
        "monitoring_end": "2024-01-10",
        "limit": 100
    },
    headers=headers,
    stream=True
)

for line in response.iter_lines():
    if line:
        feature = json.loads(line)
        props = feature["properties"]
        print(f"Plot {props['uuid']}: "
              f"Water Stress Index: {props['water_stress_index']}, "
              f"Precipitation/PET Ratio: {props['precipitation_pet_ratio']}")

# Fetch aggregated water stress statistics
response = requests.get(
    "https://epoch-sco2-api.com/fetch_water_stress",
    params={
        "filename": "your_collection_name",
        "monitoring_start": "2017-01-01",
        "monitoring_end": "2024-01-10",
        "aggregate": True
    },
    headers=headers
)

aggregated_data = json.loads(response.text)
props = aggregated_data["properties"]
print(f"Total plots: {props['aggregate_plot_count']}")
print(f"Average water stress index: {props['water_stress_index']}")

cURL Example

# Fetch water stress data for specific plot
curl -X GET "https://epoch-sco2-api.com/fetch_water_stress" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "filename=your_collection_name" \
  -d "plotid=12345" \
  -d "monitoring_start=2017-01-01" \
  -d "monitoring_end=2024-01-10"

# Fetch aggregated water stress statistics
curl -X GET "https://epoch-sco2-api.com/fetch_water_stress" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "filename=your_collection_name" \
  -d "monitoring_start=2017-01-01" \
  -d "monitoring_end=2024-01-10" \
  -d "aggregate=true"

Notes

• All responses are streamed in NDJSON (Newline Delimited JSON) format
• The annual_water_stress field is returned as a JSON string and needs to be parsed
• Water stress metrics are calculated based on land surface temperature and evapotranspiration analysis
• When aggregate=true, the limit parameter defaults to 1 (returns first matching case)
• When aggregate=false and no specific filters are provided, the limit parameter defaults to 10000
• Acronyms: PET (Potential Evapotranspiration)
• Annual water stress data uses weighted averages by area when aggregating
• The water stress index combines multiple indicators to provide a comprehensive assessment of water availability