Fetch Statistical Regions¶

The /fetch_stat_regions endpoint retrieves statistical region data for uploaded and processed collections. Statistical regions provide aggregated environmental metrics for administrative units or watersheds, allowing comparison of user-provided plots with similar commodity growing areas in the same region.

Overview¶

Statistical regions can be:

Administrative units: Government-defined administrative boundaries
Watersheds: Hydrological watershed boundaries

The endpoint summarizes environmental statistics (deforestation, biomass emissions, biodiversity) for plots within each statistical region, providing context for individual plot performance.

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"`	Comma-separated statistics to fetch
`stat_type`	string	None	Type of statistical region (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 region name
/fetch_stat_regions?filename=collection123&name_stat=Region%201

# Filter by region UUID
/fetch_stat_regions?filename=collection123&uuid_stat=abc123

# Multiple filters
/fetch_stat_regions?filename=collection123&name_stat=Region%201&monitoring_start=2020-01-01

Available Statistics¶

Statistic	Description	Fields Included
`eudr_deforestation`	EUDR deforestation detection	`noncompliance_area_ha`, `annual_defor_ha`, `deforestation_thumbnail_url`
`luc_emissions`	Land Use Change emissions	`luc_tco2eyear`, `luc_tco2ehayear`
`biodiversity`	Biodiversity metrics	`diversity_score`, `diversity_uncertainty_sd`

Response Format¶

Individual Statistical Region Response¶

{
  "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": -125.4,
    "luc_tco2ehayear": -0.175,
    "luc_uncertainty_sd": 8.47,
    "luc_thumbnail_url": "https://storage.googleapis.com/...",

    // Non-LUC Emissions Data
    "nonluc_tco2eyear": 15.2,
    "nonluc_tco2ehayear": 0.021,
    "nonluc_uncertainty_sd": 1.2,

    // Biomass Removal Data
    "removal_tco2eyear": 8.7,
    "removal_tco2ehayear": 0.012,
    "removal_uncertainty_sd": 0.8,

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

    // Deforestation Detection
    "noncompliance_area_ha": 125.4,
    "noncompliance_area_perc": 0.033,
    "deforestation_uncertainty_rrmse": 12.47,
    "deforestation_thumbnail_url": "https://storage.googleapis.com/...",

    // Annual Deforestation
    "annual_defor_ha": {
      "mean": 31.35,
      "std": 8.2,
      "2020": 0.0,
      "2021": 45.2,
      "2022": 38.7,
      "2023": 10.5
    },

    // Statistical Region Metadata
    "stat_type": "administrative_unit",
    "region_area_ha": 125000.0,
    "plot_count": 1250,
    "commodity_plot_count": 980,
    "forest_plot_count": 270
  }
}

Usage Examples¶

Python¶

import requests
import json

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

# Fetch statistical region data
response = requests.get(
    "https://epoch-sco2-api.com/fetch_stat_regions",
    params={
        'filename': 'your_collection_name',
        'stats': 'eudr_deforestation,luc_emissions,biodiversity',
        'monitoring_start': '2020-01-01',
        'monitoring_end': '2023-12-31',
        'limit': 25
    },
    headers=headers,
    stream=True
)

# Process streaming response
for line in response.iter_lines():
    if line:
        region = json.loads(line)
        props = region['properties']
        print(f"Region: {props['name_stat']}")
        print(f"  LUC Emissions: {props['luc_tco2eyear']} tCO2e/year")
        print(f"  Non-compliance: {props['noncompliance_area_ha']} ha")
        print(f"  Diversity Score: {props['diversity_score']}")

# Fetch data with specific statistical region type
response = requests.get(
    "https://epoch-sco2-api.com/fetch_stat_regions",
    params={
        'filename': 'your_collection_name',
        'stats': 'eudr_deforestation,luc_emissions,biodiversity',
        'stat_type': 'admin_area',
        'monitoring_start': '2020-01-01',
        'monitoring_end': '2023-12-31'
    },
    headers=headers,
    stream=True
)

# Process streaming response
for line in response.iter_lines():
    if line:
        region = json.loads(line)
        props = region['properties']
        print(f"Region: {props['name_stat']} - Area: {props['region_area_ha']} ha")

JavaScript¶

const axios = require('axios');

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

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

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

  } catch (error) {
    console.error('Error fetching statistical regions:', error);
  }
}

// Fetch data for specific region
async function fetchSpecificRegion(regionName) {
  try {
    const response = await axios.get(
      'https://epoch-sco2-api.com/fetch_stat_regions',
      {
        params: {
          filename: 'your_collection_name',
          name_stat: regionName,
          stats: 'eudr_deforestation,luc_emissions,biodiversity'
        },
        headers
      }
    );

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

cURL¶

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

# Fetch data with specific statistical region type
curl -X GET "https://epoch-sco2-api.com/fetch_stat_regions" \
  -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 region
curl -X GET "https://epoch-sco2-api.com/fetch_stat_regions" \
  -H "Authorization: Bearer <your_token>" \
  -G \
  -d "filename=your_collection_name" \
  -d "name_stat=Region%201" \
  -d "stats=eudr_deforestation,luc_emissions,biodiversity"

Response Fields¶

Core Region Information¶

Field	Type	Description
`uuid`	string	Unique identifier for the region
`uuid_stat`	string	Statistical region UUID
`name_stat`	string	Statistical region name
`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)

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

Deforestation Detection¶

Field	Type	Description
`noncompliance_area_ha`	float	Non-compliant area in hectares
`noncompliance_area_perc`	float	Percentage of region that is non-compliant
`deforestation_uncertainty_rrmse`	float	Deforestation detection uncertainty
`deforestation_thumbnail_url`	string	URL to deforestation visualization
`annual_defor_ha`	object	Annual deforestation by year

Region Metadata¶

Field	Type	Description
`stat_type`	string	Type of statistical region
`region_area_ha`	float	Total region area in hectares
`plot_count`	integer	Total number of plots in region
`commodity_plot_count`	integer	Number of commodity plots
`forest_plot_count`	integer	Number of forest plots

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