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)!
    "total_tco2eyear": 0.51, // (20)!
    "annual_agb_tco2eha": { // (21)!
      "agb_tco2eha_mean_2020": 42.1,
      "agb_tco2eha_stddev_2020": 5.1,
      "agb_tco2eha_mean_2021": 44.8,
      "agb_tco2eha_stddev_2021": 5.2,
      "agb_tco2eha_mean_2022": 46.7,
      "agb_tco2eha_stddev_2022": 5.3,
      "agb_tco2eha_mean_2023": 47.2,
      "agb_tco2eha_stddev_2023": 5.4
    },
    "annual_bgb_tco2eha": { // (22)!
      "bgb_tco2eha_mean_2020": 10.5,
      "bgb_tco2eha_stddev_2020": 1.2,
      "bgb_tco2eha_mean_2021": 11.2,
      "bgb_tco2eha_stddev_2021": 1.3,
      "bgb_tco2eha_mean_2022": 11.8,
      "bgb_tco2eha_stddev_2022": 1.4,
      "bgb_tco2eha_mean_2023": 11.7,
      "bgb_tco2eha_stddev_2023": 1.4
    },
    "annual_soc_tco2eha": { // (23)!
      "soc_tco2eha_mean_2020": 4.8,
      "soc_tco2eha_stddev_2020": 0.9,
      "soc_tco2eha_mean_2021": 5.1,
      "soc_tco2eha_stddev_2021": 1.0,
      "soc_tco2eha_mean_2022": 5.4,
      "soc_tco2eha_stddev_2022": 1.1,
      "soc_tco2eha_mean_2023": 5.5,
      "soc_tco2eha_stddev_2023": 1.2
    },
    "annual_emissions_tco2e": { // (24)!
      "luc_tco2e_2020": 0.42,
      "luc_tco2e_2021": 0.45,
      "luc_tco2e_2022": 0.50,
      "luc_tco2e_2023": 0.51,
    },
    "thumbnail_url": "https://storage.googleapis.com/...", // (26)!
    "thumbnail_url_lc": "https://storage.googleapis.com/...", // (27)!
    "metadata": { // (28)!
      "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. Total annual emissions (net flux: LUC + removals) in tonnes CO2e per year
21. JSON object containing annual AGB (Above-Ground Biomass) per hectare statistics. Contains keys with format: agb_tco2eha_mean_YYYY and agb_tco2eha_stddev_YYYY
22. JSON object containing annual BGB (Below-Ground Biomass) per hectare statistics. Contains keys with format: bgb_tco2eha_mean_YYYY and bgb_tco2eha_stddev_YYYY
23. JSON object containing annual SOC (Soil Organic Carbon) per hectare statistics. Contains keys with format: soc_tco2eha_mean_YYYY and soc_tco2eha_stddev_YYYY
24. JSON object containing annual net emissions time series. Primary field for annual emissions tracking. Contains keys with format: luc_tco2e_YYYY
25. JSON object containing annual LUC emissions time series (legacy alias for annual_emissions_tco2e). Contains keys with format: luc_tco2e_YYYY
26. URL to thumbnail image showing biomass/emissions visualization, or null if not available
27. URL to thumbnail image showing land cover visualization, or null if not available
28. 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)!
    "total_tco2eyear": 6.5, // (17)!
    "annual_agb_tco2eha": { // (18)!
      "agb_tco2eha_mean_2020": 42.1,
      "agb_tco2eha_stddev_2020": 5.1,
      "agb_tco2eha_mean_2021": 44.8,
      "agb_tco2eha_stddev_2021": 5.2,
      "agb_tco2eha_mean_2022": 46.7,
      "agb_tco2eha_stddev_2022": 5.3,
      "agb_tco2eha_mean_2023": 47.2,
      "agb_tco2eha_stddev_2023": 5.4
    },
    "annual_bgb_tco2eha": { // (19)!
      "bgb_tco2eha_mean_2020": 10.5,
      "bgb_tco2eha_stddev_2020": 1.2,
      "bgb_tco2eha_mean_2021": 11.2,
      "bgb_tco2eha_stddev_2021": 1.3,
      "bgb_tco2eha_mean_2022": 11.8,
      "bgb_tco2eha_stddev_2022": 1.4,
      "bgb_tco2eha_mean_2023": 11.7,
      "bgb_tco2eha_stddev_2023": 1.4
    },
    "annual_soc_tco2eha": { // (20)!
      "soc_tco2eha_mean_2020": 4.8,
      "soc_tco2eha_stddev_2020": 0.9,
      "soc_tco2eha_mean_2021": 5.1,
      "soc_tco2eha_stddev_2021": 1.0,
      "soc_tco2eha_mean_2022": 5.4,
      "soc_tco2eha_stddev_2022": 1.1,
      "soc_tco2eha_mean_2023": 5.5,
      "soc_tco2eha_stddev_2023": 1.2
    },
    "annual_emissions_tco2e": { // (21)!
      "luc_tco2e_2020": 4.8,
      "luc_tco2e_2021": 5.1,
      "luc_tco2e_2022": 5.4,
      "luc_tco2e_2023": 5.5,
    },
    "aggregate_area": 4567.8, // (23)!
    "aggregate_plot_count": 1250, // (24)!
    "metadata": {} // (25)!
  }
}

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. Total net emissions across all plots (tonnes CO2e/year)
18. JSON object containing aggregated annual AGB (Above-Ground Biomass) per hectare statistics (weighted average by area). Contains keys with format: agb_tco2eha_mean_YYYY and agb_tco2eha_stddev_YYYY
19. JSON object containing aggregated annual BGB (Below-Ground Biomass) per hectare statistics (weighted average by area). Contains keys with format: bgb_tco2eha_mean_YYYY and bgb_tco2eha_stddev_YYYY
20. JSON object containing aggregated annual SOC per hectare statistics (weighted average by area). Contains keys with format: soc_tco2eha_mean_YYYY and soc_tco2eha_stddev_YYYY
21. JSON object containing aggregated annual net emissions time series (sum by area). Contains keys with format: luc_tco2e_YYYY
22. Total area of all plots (hectares)
23. Total number of distinct plots
24. 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_tco2eha, annual_bgb_tco2eha, annual_soc_tco2eha, annual_emissions_tco2e, annual_luc_tco2e) are returned as JSON objects containing summary statistics (mean, std) plus annual time series data with the following key patterns:
• agb_tco2eha_mean_YYYY, agb_tco2eha_stddev_YYYY (Above-Ground Biomass per hectare)
• bgb_tco2eha_mean_YYYY, bgb_tco2eha_stddev_YYYY (Below-Ground Biomass per hectare)
• soc_tco2eha_mean_YYYY, soc_tco2eha_stddev_YYYY (Soil Organic Carbon per hectare)
• annual_emissions_mean_YYYY, annual_emissions_stddev_YYYY (Net annual emissions)
• luc_tco2e_mean_YYYY, luc_tco2e_stddev_YYYY (Land Use Change emissions)
• Negative luc_tco2eyear values indicate carbon loss (emissions), positive values indicate carbon gain (removal)
• annual_emissions_tco2e is the primary field for tracking net annual emissions (LUC + removals combined)
• annual_luc_tco2e is a legacy alias provided for backward compatibility
• The per-hectare annual fields (annual_agb_tco2eha, annual_bgb_tco2eha, annual_soc_tco2eha) provide normalized metrics for area-independent comparisons
• total_tco2eyear represents the sum of all emission components (LUC, biogenic, SOC, removals)
• 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