Fetch Plots¶

The /fetch_plots endpoint retrieves plot-level environmental data for uploaded and processed collections. This endpoint streams individual plot data that can be visualized on maps, stored in databases, or used for further analysis.

Overview¶

The /fetch_plots endpoint provides access to plot-specific environmental metrics including: - Deforestation detection (EUDR compliance) - Land Use Change emissions (LUC) - Biodiversity metrics - Corporate Forest Transparency (CFT) data

This endpoint retrieves plot data for visualization and analysis.

Parameters¶

Required Parameters¶

Parameter	Type	Description
`filename`	string	Collection identifier
`Authorization`	Header	Bearer token for authentication

Optional Parameters¶

Parameter	Type	Default	Description
`stats`	string	`"eudr_deforestation,luc_emissions,biodiversity,water,cft"`	Comma-separated statistics to fetch. Set to empty string or omit to return plots only without statistics
`stat_type`	string	None	Statistical region type to use as reference (default is 'admin_area')
`overlap_threshold`	float	0.5	Overlap threshold for statistical regions
`monitoring_start`	string	None	Monitoring start date (YYYY-MM-DD)
`monitoring_end`	string	None	Monitoring end date (YYYY-MM-DD)

Dynamic Filtering¶

Any additional query parameters will be used to filter the data:

# Filter by specific plot ID
/fetch_plots?filename=collection123&plotid=abc123

# Filter by collection ID
/fetch_plots?filename=collection123&collection_id=xyz789

# Multiple filters
/fetch_plots?filename=collection123&plotid=abc123&monitoring_start=2020-01-01

# Fetch plots only without statistics (set stats to empty string or omit)
/fetch_plots?filename=collection123&stats=

Available Statistics¶

Statistic	Description	Fields Included
`eudr_deforestation`	EUDR deforestation detection	`deforestation_start`, `deforestation_end`, `noncompliance_area_ha`, `agreement`, `overlap`
`luc_emissions`	Land Use Change emissions	`luc_tco2eyear`, `luc_tco2ehayear`, `annual_agb_tco2eha`, `annual_bgb_tco2eha`
`biodiversity`	Biodiversity metrics	`diversity_score`, `annual_chm_m`, `diversity_uncertainty_sd`
`cft`	Corporate Forest Transparency	`cft_summary`, `cft_total`, `cft_details`

Response Format¶

The /fetch_plots endpoint returns a streaming response where: 1. First JSON object: Statistical region data (if available) 2. Subsequent JSON objects: Individual plot data

Statistical Region Response (First Object)¶

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[longitude, latitude], ...]]
  },
  "properties": {
    "uuid": "c0db3327-755f-4078-bb9d-237f76df4aa7",
    "uuid_stat": "c0db3327-755f-4078-bb9d-237f76df4aa7",
    "name_stat": "Region 1",
    "collection_id": "abc123",
    "facility_id": "xyz789",
    "ingestion_date": "2024-01-10T00:00:00+00:00",
    "monitoring_start": "2020-12-31T00:00:00+00:00",
    "monitoring_end": "2024-01-10T00:00:00+00:00",

    // LUC Emissions Data
    "luc_tco2eyear": -2.12,
    "luc_tco2ehayear": -1.06,
    "luc_uncertainty_sd": 8.47,
    "luc_thumbnail_url": "https://storage.googleapis.com/...",

    // Non-LUC Emissions Data
    "nonluc_tco2eyear": 0.25,
    "nonluc_tco2ehayear": 0.13,
    "nonluc_uncertainty_sd": 0.12,

    // Biomass Removal Data
    "removal_tco2eyear": 0.13,
    "removal_tco2ehayear": 0.07,
    "removal_uncertainty_sd": 0.05,

    // Annual Above-Ground Biomass
    "annual_agb_tco2eha": {
      "mean": 45.2,
      "std": 12.3,
      "2020": 42.1,
      "2021": 44.8,
      "2022": 46.7,
      "2023": 47.2
    },

    // Annual Below-Ground Biomass
    "annual_bgb_tco2eha": {
      "mean": 11.3,
      "std": 3.1,
      "2020": 10.5,
      "2021": 11.2,
      "2022": 11.8,
      "2023": 11.7
    },

    // Annual Deforestation
    "annual_defor_ha": {
      "mean": 0.8,
      "std": 0.3,
      "2020": 0.0,
      "2021": 1.2,
      "2022": 0.9,
      "2023": 0.3
    },

    // Biodiversity Metrics
    "diversity_score": 0.65,
    "diversity_uncertainty_sd": 9.48,
    "diversity_thumbnail_url": "https://storage.googleapis.com/...",

    // Annual Canopy Height
    "annual_chm_m": {
      "mean": 15.2,
      "std": 4.1,
      "2020": 14.8,
      "2021": 15.1,
      "2022": 15.4,
      "2023": 15.5
    },

    // Deforestation Detection
    "deforestation_start": "2021-06-08",
    "deforestation_end": "2022-02-14",
    "noncompliance_area_ha": 1.94,
    "noncompliance_area_perc": 0.52,
    "deforestation_uncertainty_rrmse": 12.47,
    "deforestation_thumbnail_url": "https://storage.googleapis.com/...",

    // Agreement Between Detection Methods
    "agreement": {
      "all": 0.85,
      "dynamic_world": 0.78,
      "glad": 0.92
    },

    // Overlap with Third-Party Datasets
    "overlap": {
      "jrc": 0.0,
      "wdpa": 0.0,
      "wdpa_mandate": 0.0
    },

    // Plot Overlap
    "plot_overlap_perc": 0.82,

    // Statistical Region Data (when available)
    "uuid_stat": "c0db3327-755f-4078-bb9d-237f76df4aa7",
    "name_stat": "Region 1",
    "luc_tco2ehayear_stat": 1.82,
    "nonluc_tco2eyear_stat": 0.25,
    "removal_tco2eyear_stat": 0.15,

    // CFT Data (when available)
    "cft_summary": {
      "2020": {"total_emissions": 125.4, "summary": {...}},
      "2021": {"total_emissions": 118.7, "summary": {...}},
      "2022": {"total_emissions": 132.1, "summary": {...}}
    },
    "cft_total": [...],
    "cft_details": [...],

    // Additional metadata
    "area": 3.945736451658705,
    "uncertainty_rrmse": 0.0,
    "thumbnail_url": ""
  }
}

Individual Plot Response (Subsequent Objects)¶

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[longitude, latitude], ...]]
  },
  "properties": {
    "uuid": "c0db3327-755f-4078-bb9d-237f76df4aa7",
    "plotid": "f881a77f-17f4-5da3-9870-e7730938a6bf",
    "collection_id": "abc123",
    "facility_id": "xyz789",
    "ingestion_date": "2024-01-10T00:00:00+00:00",
    "monitoring_start": "2020-12-31T00:00:00+00:00",
    "monitoring_end": "2024-01-10T00:00:00+00:00",

    // LUC Emissions Data
    "luc_tco2eyear": -2.12,
    "luc_tco2ehayear": -1.06,
    "luc_uncertainty_sd": 8.47,
    "luc_thumbnail_url": "https://storage.googleapis.com/...",

    // Non-LUC Emissions Data
    "nonluc_tco2eyear": 0.25,
    "nonluc_tco2ehayear": 0.13,
    "nonluc_uncertainty_sd": 0.12,

    // Biomass Removal Data
    "removal_tco2eyear": 0.13,
    "removal_tco2ehayear": 0.07,
    "removal_uncertainty_sd": 0.05,

    // Annual Above-Ground Biomass
    "annual_agb_tco2eha": {
      "mean": 45.2,
      "std": 12.3,
      "2020": 42.1,
      "2021": 44.8,
      "2022": 46.7,
      "2023": 47.2
    },

    // Annual Below-Ground Biomass
    "annual_bgb_tco2eha": {
      "mean": 11.3,
      "std": 3.1,
      "2020": 10.5,
      "2021": 11.2,
      "2022": 11.8,
      "2023": 11.7
    },

    // Annual Deforestation
    "annual_defor_ha": {
      "mean": 0.8,
      "std": 0.3,
      "2020": 0.0,
      "2021": 1.2,
      "2022": 0.9,
      "2023": 0.3
    },

    // Biodiversity Metrics
    "diversity_score": 0.65,
    "diversity_uncertainty_sd": 9.48,
    "diversity_thumbnail_url": "https://storage.googleapis.com/...",

    // Annual Canopy Height
    "annual_chm_m": {
      "mean": 15.2,
      "std": 4.1,
      "2020": 14.8,
      "2021": 15.1,
      "2022": 15.4,
      "2023": 15.5
    },

    // Deforestation Detection
    "deforestation_start": "2021-06-08",
    "deforestation_end": "2022-02-14",
    "noncompliance_area_ha": 1.94,
    "noncompliance_area_perc": 0.52,
    "deforestation_uncertainty_rrmse": 12.47,
    "deforestation_thumbnail_url": "https://storage.googleapis.com/...",

    // Agreement Between Detection Methods
    "agreement": {
      "all": 0.85,
      "dynamic_world": 0.78,
      "glad": 0.92
    },

    // Overlap with Third-Party Datasets
    "overlap": {
      "jrc": 0.0,
      "wdpa": 0.0,
      "wdpa_mandate": 0.0
    },

    // Plot Overlap
    "plot_overlap_perc": 0.82,

    // Statistical Region Data (when available)
    "uuid_stat": "c0db3327-755f-4078-bb9d-237f76df4aa7",
    "name_stat": "Region 1",
    "luc_tco2ehayear_stat": 1.82,
    "nonluc_tco2eyear_stat": 0.25,
    "removal_tco2eyear_stat": 0.15,

    // CFT Data (when available)
    "cft_summary": {
      "2020": {"total_emissions": 125.4, "summary": {...}},
      "2021": {"total_emissions": 118.7, "summary": {...}},
      "2022": {"total_emissions": 132.1, "summary": {...}}
    },
    "cft_total": [...],
    "cft_details": [...],

    // Additional metadata
    "area": 3.945736451658705,
    "uncertainty_rrmse": 0.0,
    "thumbnail_url": ""
  }
}

Usage Examples¶

Python¶

import requests
import json

# Authentication
headers = {
    'Authorization': 'Bearer <your_token>'
}

# Fetch plot data for a specific collection
response = requests.get(
    "https://epoch-sco2-api.com/fetch_plots",
    params={
        'filename': 'your_collection_name',
        'stats': 'eudr_deforestation,luc_emissions,biodiversity,cft',
        'monitoring_start': '2020-01-01',
        'monitoring_end': '2023-12-31',
        'limit': 100
    },
    headers=headers,
    stream=True
)

# Process streaming response
for line in response.iter_lines():
    if line:
        plot = json.loads(line)
        props = plot['properties']
        print(f"Plot {props['uuid']}: "
              f"LUC Emissions: {props['luc_tco2eyear']} tCO2e/year, "
              f"Diversity: {props['diversity_score']}")

# Example: Fetch plots only without statistics
response = requests.get(
    "https://epoch-sco2-api.com/fetch_plots",
    params={
        'filename': 'your_collection_name',
        'stats': ''  # Empty string returns plots only
    },
    headers=headers,
    stream=True
)

for line in response.iter_lines():
    if line:
        plot = json.loads(line)
        props = plot['properties']
        print(f"Plot {props['uuid']}: Area {props.get('area', 'N/A')} ha")
        # Note: Statistical fields (luc_tco2eyear, diversity_score, etc.) will not be present

# Process the streaming response
# First object is statistical region data, subsequent objects are individual plots
first_object = True
for line in response.iter_lines():
    if line:
        feature = json.loads(line)
        if first_object:
            print(f"Statistical Region: {feature['properties'].get('name_stat', 'N/A')}")
            first_object = False
        else:
            print(f"Plot: {feature['properties']['uuid']}")

JavaScript¶

const axios = require('axios');

const headers = {
  'Authorization': 'Bearer <your_token>'
};

// Fetch plot data
async function fetchPlotData() {
  try {
    const response = await axios.get(
      'https://epoch-sco2-api.com/fetch_plots',
      {
        params: {
          filename: 'your_collection_name',
          stats: 'eudr_deforestation,luc_emissions,biodiversity,cft',
          monitoring_start: '2020-01-01',
          monitoring_end: '2023-12-31',
          limit: 50
        },
        headers,
        responseType: 'stream'
      }
    );

    response.data.on('data', (chunk) => {
      const lines = chunk.toString().split('\n');
      lines.forEach(line => {
        if (line.trim()) {
          const plot = JSON.parse(line);
          const props = plot.properties;
          console.log(`Plot ${props.uuid}: LUC ${props.luc_tco2eyear} tCO2e/year`);
        }
      });
    });

  } catch (error) {
    console.error('Error fetching plot data:', error);
  }
}

// Fetch data for specific plot
async function fetchSpecificPlot(plotId) {
  try {
    const response = await axios.get(
      'https://epoch-sco2-api.com/fetch_plots',
      {
        params: {
          filename: 'your_collection_name',
          plotid: plotId,
          stats: 'eudr_deforestation,luc_emissions,biodiversity'
        },
        headers
      }
    );

    console.log('Plot data:', response.data);
  } catch (error) {
    console.error('Error fetching plot data:', error);
  }
}

cURL¶

# Fetch plot data for a collection
curl -X GET "https://epoch-sco2-api.com/fetch_plots" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "filename=your_collection_name" \
  -d "stats=eudr_deforestation,luc_emissions,biodiversity,cft" \
  -d "monitoring_start=2020-01-01" \
  -d "monitoring_end=2023-12-31" \
  -d "limit=100"

# Fetch data with specific statistical region type
curl -X GET "https://epoch-sco2-api.com/fetch_plots" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "filename=your_collection_name" \
  -d "stats=eudr_deforestation,luc_emissions,biodiversity" \
  -d "stat_type=admin_area" \
  -d "monitoring_start=2020-01-01" \
  -d "monitoring_end=2023-12-31"

# Fetch data for specific plot
curl -X GET "https://epoch-sco2-api.com/fetch_plots" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "filename=your_collection_name" \
  -d "plotid=abc123" \
  -d "stats=eudr_deforestation,luc_emissions,biodiversity"

# Fetch plots only without statistics (set stats to empty string)
curl -X GET "https://epoch-sco2-api.com/fetch_plots" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "filename=your_collection_name" \
  -d "stats="

Response Fields¶

Core Plot Information¶

Field	Type	Description
`uuid`	string	Unique identifier for the plot
`plotid`	string	Plot ID (when available)
`collection_id`	string	Collection identifier
`facility_id`	string	Associated facility ID
`ingestion_date`	string	Date data was ingested (ISO 8601)
`monitoring_start`	string	Start of monitoring period (ISO 8601)
`monitoring_end`	string	End of monitoring period (ISO 8601)

LUC Emissions¶

Field	Type	Description
`luc_tco2eyear`	float	Total LUC emissions in tCO2e/year
`luc_tco2ehayear`	float	LUC emissions per hectare in tCO2e/ha/year
`luc_uncertainty_sd`	float	Uncertainty (standard deviation)
`luc_thumbnail_url`	string	URL to LUC emissions visualization

Non-LUC Emissions¶

Field	Type	Description
`nonluc_tco2eyear`	float	Total non-LUC emissions in tCO2e/year
`nonluc_tco2ehayear`	float	Non-LUC emissions per hectare in tCO2e/ha/year
`nonluc_uncertainty_sd`	float	Uncertainty (standard deviation)

Biomass Removal¶

Field	Type	Description
`removal_tco2eyear`	float	Total biomass removal in tCO2e/year
`removal_tco2ehayear`	float	Biomass removal per hectare in tCO2e/ha/year
`removal_uncertainty_sd`	float	Uncertainty (standard deviation)

Annual Biomass Data¶

Field	Type	Description
`annual_agb_tco2eha`	object	Annual above-ground biomass by year
`annual_bgb_tco2eha`	object	Annual below-ground biomass by year

Biodiversity¶

Field	Type	Description
`diversity_score`	float	Biodiversity diversity score (0-1)
`diversity_uncertainty_sd`	float	Uncertainty in diversity score
`diversity_thumbnail_url`	string	URL to biodiversity visualization
`annual_chm_m`	object	Annual canopy height by year

Deforestation Detection¶

Field	Type	Description
`deforestation_start`	string	Date of first deforestation detection
`deforestation_end`	string	Date of last deforestation detection
`noncompliance_area_ha`	float	Non-compliant area in hectares
`noncompliance_area_perc`	float	Percentage of plot that is non-compliant
`deforestation_uncertainty_rrmse`	float	Deforestation detection uncertainty
`deforestation_thumbnail_url`	string	URL to deforestation visualization

Agreement and Overlap¶

Field	Type	Description
`agreement`	object	Agreement between detection methods
`overlap`	object	Overlap with third-party datasets
`plot_overlap_perc`	float	Percentage overlap with other plots

Statistical Region Data¶

Field	Type	Description
`uuid_stat`	string	Statistical region UUID
`name_stat`	string	Statistical region name
`luc_tco2ehayear_stat`	float	Statistical LUC emissions per hectare
`nonluc_tco2eyear_stat`	float	Statistical non-LUC emissions
`removal_tco2eyear_stat`	float	Statistical biomass removal

CFT Data¶

Field	Type	Description
`cft_summary`	object	CFT summary data by year
`cft_total`	array	CFT total data
`cft_details`	array	CFT detailed data

Performance Considerations¶

Streaming Responses¶

All responses are streamed in NDJSON format
Use --no-buffer with cURL for real-time streaming
Process responses incrementally for large datasets

Caching¶

Results are cached for 4 hours
Schema information is cached for 8 hours
Table discovery is cached for 2 hours

Rate Limiting¶

Standard API rate limits apply
Large datasets may take time to process
Monitor response headers for progress indicators

Error Handling¶

Common Errors¶

{
  "detail": "Collection not found",
  "status_code": 404
}

{
  "detail": "Invalid statistics specified",
  "status_code": 422
}

Error Codes¶

Code	Description
400	Bad Request - Invalid parameters
403	Forbidden - Insufficient permissions
404	Not Found - Collection not found
422	Validation Error - Invalid parameter format
500	Internal Server Error - Processing error

Best Practices¶

Use appropriate limits: Set reasonable limit values to avoid overwhelming responses
Filter early: Use query parameters to filter data at the source
Stream processing: Process streaming responses incrementally for large datasets
Cache results: Implement client-side caching for frequently accessed data
Monitor performance: Use aggregated endpoints for summary statistics
Handle errors gracefully: Implement proper error handling for network issues