Skip to content

Fetch Biodiversity

The /fetch_biodiversity endpoint retrieves biodiversity metrics for individual plots or aggregated statistics. This endpoint provides diversity scores, canopy height measurements, and related uncertainty estimates.

Endpoint

GET /fetch_biodiversity

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_biodiversity?plotid=12345

# Filter by collection ID
/fetch_biodiversity?collection_id=abc123

# Filter by facility ID
/fetch_biodiversity?facility_id=xyz789

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

# Combine multiple filters
/fetch_biodiversity?collection_id=abc123&monitoring_start=2020-01-01
/fetch_biodiversity?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 biodiversity 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)!
    "diversity_score": 0.65, // (9)!
    "uncertainty_sd": 9.48, // (10)!
    "annual_chm": { // (11)!
      "mean": 15.2,
      "std": 4.1,
      "2020": 14.8,
      "2021": 15.1,
      "2022": 15.4,
      "2023": 15.5
    },
    "thumbnail_url": "https://storage.googleapis.com/...", // (12)!
    "metadata": { // (13)!
      "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. Biodiversity diversity score (0.0 to 1.0, where higher values indicate greater diversity). This score is based on canopy height heterogeneity and landscape connectivity as proxies for species diversity.
  10. Standard deviation of biodiversity uncertainty
  11. JSON string containing annual CHM (Canopy Height Model) statistics. When parsed, contains: mean (mean annual canopy height in meters), std (standard deviation), YYYY (canopy height for specific year in meters, e.g., "2021": 15.1)
  12. URL to thumbnail image showing biodiversity visualization, or null if not available
  13. 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 biodiversity statistics across all matching plots.

Response Structure

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[longitude, latitude], ...]]
  },
  "properties": {
    "collection_id": "abc123", // (1)!
    "facility_id": "xyz789", // (2)!
    "ingestion_date": "2024-01-10T00:00:00+00:00", // (3)!
    "monitoring_start": "2017-01-01", // (4)!
    "monitoring_end": "2024-01-10", // (5)!
    "diversity_score": 0.68, // (6)!
    "uncertainty_sd": 125.4, // (7)!
    "annual_chm": { // (8)!
      "mean": 15.2,
      "std": 4.1,
      "2020": 14.8,
      "2021": 15.1,
      "2022": 15.4,
      "2023": 15.5
    },
    "aggregate_area": 4567.8, // (9)!
    "aggregate_plot_count": 1250, // (10)!
    "metadata": {} // (11)!
  }
}
  1. Collection identifier
  2. Facility identifier
  3. Most recent ingestion date (ISO 8601 timestamp)
  4. Earliest monitoring start date (YYYY-MM-DD)
  5. Latest monitoring end date (YYYY-MM-DD)
  6. Weighted average diversity score across all plots (0.0 to 1.0)
  7. Sum of uncertainty values across all plots
  8. Aggregated annual CHM statistics (weighted average by area)
  9. Total area of all plots (hectares)
  10. Total number of distinct plots
  11. 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 biodiversity 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 biodiversity fields are included when plots_only=true.

Usage Examples

Python Example

import requests
import json

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

# Fetch individual plots with biodiversity data
response = requests.get(
    "https://epoch-sco2-api.com/fetch_biodiversity",
    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"]
        annual_chm = json.loads(props["annual_chm"])
        print(f"Plot {props['uuid']}: "
              f"Diversity Score: {props['diversity_score']}, "
              f"Mean Canopy Height: {annual_chm['mean']} m")

# Fetch aggregated biodiversity statistics
response = requests.get(
    "https://epoch-sco2-api.com/fetch_biodiversity",
    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 diversity score: {props['diversity_score']}")

cURL Example

# Fetch biodiversity data for specific plot
curl -X GET "https://epoch-sco2-api.com/fetch_biodiversity" \
  -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 biodiversity statistics
curl -X GET "https://epoch-sco2-api.com/fetch_biodiversity" \
  -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_chm field is returned as a JSON string and needs to be parsed
  • Acronyms: CHM (Canopy Height Model)
  • The diversity_score is calculated based on canopy height heterogeneity and landscape connectivity as proxies for species diversity
  • 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
  • Annual canopy height data uses weighted averages by area when aggregating