Fetch Sampling Design

The /fetch_samples/ endpoint retrieves sampling design data (strata and sample points) that were previously generated via the Batch API sampling design endpoint. This endpoint returns statistically valid field sampling plans with travel-time clustering, confidence intervals, and carbon pool specifications.

Endpoint

GET /fetch_samples/

Parameters

Parameter	Type	Required	Default	Description
collection_name	string	Yes	None	Any collection that participated in the sampling run. The API looks up the associated metaID automatically.
confidence_interval	float	No	0.95	Optional override when filtering samples. The API will snap to the closest available confidence interval if an exact match is not present.
margin_of_error	float	No	0.05	Same behavior as confidence_interval; used to pick the best matching sample realization.

Response Format

The endpoint returns a JSON object with two GeoJSON strings that need to be parsed. Both strata and samples are GeoJSON FeatureCollections containing the most recent sampling design for the specified collection.

response = {
    "strata": "{\"type\":\"FeatureCollection\",\"features\":[...]}",  # (1)!
    "samples": "{\"type\":\"FeatureCollection\",\"features\":[...]}"  # (2)!
}

1. GeoJSON string containing the strata (statistical groups) used for stratification. Parse with json.loads() before use.
2. GeoJSON string containing the individual sample points selected for field measurement. Parse with json.loads() before use.

Strata Feature Properties

Each stratum in the strata FeatureCollection contains:

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[longitude, latitude], ...]]
  },
  "properties": {
    "stratum_id": 1,                    // (1)!
    "agb_tha_mean": 45.2,               // (2)!
    "agb_tha_stddev": 12.5,             // (3)!
    "agb_tha_potential": 52.8,          // (4)!
    "area": 1250.5,                     // (5)!
    "plot_no": 342,                     // (6)!
    "sample_size": 15,                  // (7)!
    "monitoring_start": "2017-01-01",   // (8)!
    "monitoring_end": "2024-12-31",     // (9)!
    "ingestion_date": "2025-01-15T10:30:00",  // (10)!
    "collections": "0x299d006b..."      // (11)!
  }
}

1. Unique identifier for the stratum (integer)
2. Mean above-ground biomass (AGB) in tonnes per hectare for this stratum
3. Standard deviation of AGB in tonnes per hectare
4. Potential AGB in tonnes per hectare (upper bound estimate)
5. Total area of the stratum in hectares
6. Number of plots within this stratum
7. Required number of sample plots to visit for this stratum (based on confidence interval and margin of error)
8. Start date of the monitoring period (YYYY-MM-DD format)
9. End date of the monitoring period (YYYY-MM-DD format)
10. Timestamp when the sampling design was generated (ISO 8601 format)
11. Comma-separated list of collection IDs that contributed to this sampling design

Sample Feature Properties

Each sample point in the samples FeatureCollection contains:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [longitude, latitude]
  },
  "properties": {
    "sample_id": "sample_001",           // (1)!
    "stratum_id": 1,                     // (2)!
    "confidence_interval": 0.9,         // (3)!
    "margin_of_error": 0.07,            // (4)!
    "annual_agb": "45.2,48.1,42.3,...",  // (5)!
    "agb_sampling": true,                // (6)!
    "soil_sampling": false,              // (7)!
    "sampling_year": 2025,              // (8)!
    "monitoring_start": "2017-01-01",    // (9)!
    "monitoring_end": "2024-12-31",      // (10)!
    "ingestion_date": "2025-01-15T10:30:00",  // (11)!
    "collections": "0x299d006b..."       // (12)!
  }
}

1. Unique identifier for the sample point
2. The stratum ID this sample belongs to
3. Confidence interval used for this sample realization
4. Margin of error used for this sample realization
5. Comma-separated annual AGB values (tonnes per hectare) for the monitoring period
6. Boolean flag indicating if this sample requires above-ground biomass measurement
7. Boolean flag indicating if this sample requires soil organic carbon measurement
8. Recommended year for field sampling
9. Start date of the monitoring period (YYYY-MM-DD format)
10. End date of the monitoring period (YYYY-MM-DD format)
11. Timestamp when the sampling design was generated (ISO 8601 format)
12. Comma-separated list of collection IDs that contributed to this sampling design

Usage Examples

Python Example

import requests
import json

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

params = {
    "collection_name": "lujeri-phase-1",
    "confidence_interval": 0.9,
    "margin_of_error": 0.07
}

response = requests.get(
    "https://epoch-sco2-api.com/fetch_samples/",
    params=params,
    headers=headers
)

result = response.json()

# Parse the GeoJSON strings
strata = json.loads(result["strata"])
samples = json.loads(result["samples"])

print(f"Found {len(strata['features'])} strata and {len(samples['features'])} samples")

# Access individual sample properties
for sample in samples["features"]:
    props = sample["properties"]
    coords = sample["geometry"]["coordinates"]
    print(f"Sample {props['sample_id']} at ({coords[0]}, {coords[1]})")
    print(f"  Stratum: {props['stratum_id']}")
    print(f"  AGB sampling: {props['agb_sampling']}")
    print(f"  Soil sampling: {props['soil_sampling']}")
    print(f"  Sampling year: {props['sampling_year']}")

JavaScript Example

const axios = require('axios');

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

const params = {
  collection_name: 'lujeri-phase-1',
  confidence_interval: 0.9,
  margin_of_error: 0.07
};

async function fetchSamplingDesign() {
  try {
    const response = await axios.get(
      'https://epoch-sco2-api.com/fetch_samples/',
      { params, headers }
    );

    // Parse the GeoJSON strings
    const strata = JSON.parse(response.data.strata);
    const samples = JSON.parse(response.data.samples);

    console.log(`Found ${strata.features.length} strata and ${samples.features.length} samples`);

    // Access individual sample properties
    samples.features.forEach(sample => {
      const props = sample.properties;
      const coords = sample.geometry.coordinates;
      console.log(`Sample ${props.sample_id} at (${coords[0]}, ${coords[1]})`);
      console.log(`  Stratum: ${props.stratum_id}`);
      console.log(`  AGB sampling: ${props.agb_sampling}`);
      console.log(`  Soil sampling: ${props.soil_sampling}`);
      console.log(`  Sampling year: ${props.sampling_year}`);
    });
  } catch (error) {
    console.error('Error fetching sampling design:', error);
  }
}

cURL Example

curl -G https://epoch-sco2-api.com/fetch_samples/ \
  -H "Authorization: Bearer <your_token>" \
  --data-urlencode "collection_name=lujeri-phase-1" \
  --data-urlencode "confidence_interval=0.9" \
  --data-urlencode "margin_of_error=0.07"

Notes

• Both strata and samples are returned as JSON strings and must be parsed with json.loads() (Python) or JSON.parse() (JavaScript) before use.
• Only the most recent ingestion for each stratum/sample is returned, so you can re-run the sampling design without worrying about stale versions.
• The API automatically looks up the metaID associated with the collection name, so you don't need to know the internal table hash.
• If an exact match for confidence_interval or margin_of_error is not found, the API will snap to the closest available value.
• Use the sampling_year and agb_sampling/soil_sampling flags to plan field campaigns efficiently.
• The sample points are clustered based on travel-time constraints specified during design generation, making field access more efficient.

Related Documentation

• Sampling Design (Batch API) - Generate new sampling designs
• Fetch API Introduction - Overview of all Fetch API endpoints