Skip to content

Fetch Biomass Emissions

The /fetch_biomass_emissions endpoint retrieves biomass and LUC (Land Use Change) emissions data for individual plots or aggregated statistics. This endpoint provides comprehensive emissions data including AGB (Above-Ground Biomass), BGB (Below-Ground Biomass), SOC (Soil Organic Carbon), and removal estimates.

Endpoint

GET /fetch_biomass_emissions

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

# Filter by collection ID
/fetch_biomass_emissions?collection_id=abc123

# Filter by facility ID
/fetch_biomass_emissions?facility_id=xyz789

# Combine multiple filters
/fetch_biomass_emissions?collection_id=abc123&monitoring_start=2020-01-01

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 biomass emissions data.

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": "2020-01-01T00:00:00+00:00", // (6)!
    "monitoring_end": "2024-01-10T00:00:00+00:00", // (7)!
    "area": 3.945736451658705, // (8)!
    "luc_tco2eyear": -2.12, // (9)!
    "luc_tco2ehayear": -1.06, // (10)!
    "luc_uncertainty_sd": 8.47, // (11)!
    "biogenic_tco2eyear": 0.25, // (12)!
    "biogenic_tco2ehayear": 0.13, // (13)!
    "biogenic_uncertainty_sd": 0.12, // (14)!
    "soc_tco2eyear": 0.15, // (15)!
    "soc_tco2ehayear": 0.08, // (16)!
    "removal_tco2eyear": 0.13, // (17)!
    "removal_tco2ehayear": 0.07, // (18)!
    "removal_uncertainty_sd": 0.05, // (19)!
    "annual_agb": { // (20)!
      "mean": 45.2,
      "std": 12.3,
      "2020": 42.1,
      "2021": 44.8,
      "2022": 46.7,
      "2023": 47.2
    },
    "annual_bgb": { // (21)!
      "mean": 11.3,
      "std": 3.1,
      "2020": 10.5,
      "2021": 11.2,
      "2022": 11.8,
      "2023": 11.7
    },
    "annual_soc": { // (22)!
      "mean": 5.2,
      "std": 1.3,
      "2020": 4.8,
      "2021": 5.1,
      "2022": 5.4,
      "2023": 5.5
    },
    "annual_lc": { // (23)!
      "2020": 1,
      "2021": 1,
      "2022": 1,
      "2023": 1
    },
    "thumbnail_url": "https://storage.googleapis.com/...", // (24)!
    "thumbnail_url_lc": "https://storage.googleapis.com/...", // (25)!
    "metadata": { // (26)!
      "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. LUC (Land Use Change) emissions in tonnes CO2e (Carbon Dioxide Equivalent) per year (negative values indicate carbon loss/emissions, positive values indicate carbon gain/removal)
  10. LUC emissions per hectare per year (tonnes CO2e/ha/year)
  11. Standard deviation of LUC emissions uncertainty
  12. Non-LUC biogenic emissions in tonnes CO2e per year
  13. Non-LUC biogenic emissions per hectare per year (tonnes CO2e/ha/year)
  14. Standard deviation of biogenic emissions uncertainty
  15. SOC (Soil Organic Carbon) emissions in tonnes CO2e per year
  16. SOC emissions per hectare per year (tonnes CO2e/ha/year)
  17. Carbon removal in tonnes CO2e per year (positive values indicate carbon sequestration)
  18. Carbon removal per hectare per year (tonnes CO2e/ha/year)
  19. Standard deviation of removal uncertainty
  20. JSON string containing annual AGB (Above-Ground Biomass) statistics. When parsed, contains: mean (mean annual AGB in tonnes CO2e/ha), std (standard deviation), YYYY (AGB for specific year, e.g., "2021": 44.8)
  21. JSON string containing annual BGB (Below-Ground Biomass) statistics. When parsed, contains: mean (mean annual BGB in tonnes CO2e/ha), std (standard deviation), YYYY (BGB for specific year, e.g., "2021": 11.2)
  22. JSON string containing annual SOC statistics. When parsed, contains: mean (mean annual SOC in tonnes CO2e/ha), std (standard deviation), YYYY (SOC for specific year, e.g., "2021": 5.1)
  23. JSON string containing annual land cover classification. When parsed, contains: YYYY (land cover class code for specific year as integer values)
  24. URL to thumbnail image showing biomass/emissions visualization, or null if not available
  25. URL to thumbnail image showing land cover visualization, or null if not available
  26. 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 biomass emissions 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": "2020-01-01", // (4)!
    "monitoring_end": "2024-01-10", // (5)!
    "luc_tco2eyear": -125.4, // (6)!
    "luc_tco2ehayear": -0.027, // (7)!
    "luc_uncertainty_sd": 125.4, // (8)!
    "biogenic_tco2eyear": 15.2, // (9)!
    "biogenic_tco2ehayear": 0.003, // (10)!
    "biogenic_uncertainty_sd": 8.5, // (11)!
    "soc_tco2eyear": 8.7, // (12)!
    "soc_tco2ehayear": 0.002, // (13)!
    "removal_tco2eyear": 8.7, // (14)!
    "removal_tco2ehayear": 0.002, // (15)!
    "removal_uncertainty_sd": 3.2, // (16)!
    "annual_agb": { // (17)!
      "mean": 45.2,
      "std": 12.3,
      "2020": 42.1,
      "2021": 44.8,
      "2022": 46.7,
      "2023": 47.2
    },
    "annual_bgb": { // (18)!
      "mean": 11.3,
      "std": 3.1,
      "2020": 10.5,
      "2021": 11.2,
      "2022": 11.8,
      "2023": 11.7
    },
    "annual_soc": { // (19)!
      "mean": 5.2,
      "std": 1.3,
      "2020": 4.8,
      "2021": 5.1,
      "2022": 5.4,
      "2023": 5.5
    },
    "aggregate_area": 4567.8, // (20)!
    "aggregate_plot_count": 1250, // (21)!
    "metadata": {} // (22)!
  }
}
  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. Total LUC emissions across all plots (tonnes CO2e/year)
  7. Weighted average LUC emissions per hectare per year (tonnes CO2e/ha/year)
  8. Sum of LUC uncertainty values across all plots
  9. Total biogenic emissions across all plots (tonnes CO2e/year)
  10. Weighted average biogenic emissions per hectare per year (tonnes CO2e/ha/year)
  11. Sum of biogenic uncertainty values across all plots
  12. Total SOC emissions across all plots (tonnes CO2e/year)
  13. Weighted average SOC emissions per hectare per year (tonnes CO2e/ha/year)
  14. Total carbon removal across all plots (tonnes CO2e/year)
  15. Weighted average carbon removal per hectare per year (tonnes CO2e/ha/year)
  16. Sum of removal uncertainty values across all plots
  17. Aggregated annual AGB statistics (weighted average by area)
  18. Aggregated annual BGB statistics (weighted average by area)
  19. Aggregated annual SOC statistics (weighted average by area)
  20. Total area of all plots (hectares)
  21. Total number of distinct plots
  22. 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 biomass emissions 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 biomass emissions fields are included when plots_only=true.

Usage Examples

Python Example

import requests
import json

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

# Fetch individual plots with biomass emissions data
response = requests.get(
    "https://epoch-sco2-api.com/fetch_biomass_emissions",
    params={
        "filename": "your_collection_name",
        "monitoring_start": "2020-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"LUC Emissions: {props['luc_tco2eyear']} tCO2e/year, "
              f"Removal: {props['removal_tco2eyear']} tCO2e/year")

# Fetch aggregated biomass emissions statistics
response = requests.get(
    "https://epoch-sco2-api.com/fetch_biomass_emissions",
    params={
        "filename": "your_collection_name",
        "monitoring_start": "2020-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"Total LUC emissions: {props['luc_tco2eyear']} tCO2e/year")
print(f"Total carbon removal: {props['removal_tco2eyear']} tCO2e/year")

cURL Example

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

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

Notes

  • All responses are streamed in NDJSON (Newline Delimited JSON) format
  • JSON fields (annual_agb, annual_bgb, annual_soc, annual_lc) are returned as JSON strings and need to be parsed
  • Negative luc_tco2eyear values indicate carbon loss (emissions), positive values indicate carbon gain (removal)
  • Acronyms: LUC (Land Use Change), CO2e (Carbon Dioxide Equivalent), SOC (Soil Organic Carbon), AGB (Above-Ground Biomass), BGB (Below-Ground Biomass)
  • 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 data fields use weighted averages by area when aggregating