Facility Validation¶

The /validate_facilities and /validate_facility API endpoints assess whether locations are suitable for commodity aggregation facilities. These endpoints analyze geographic, infrastructure, and business factors to determine the likelihood that a location serves as a first-mile aggregation point for commodities.

Validation Metrics¶

The system combines multiple data sources and AI analysis to evaluate:

Commodity Presence: Whether the target commodity is present in the area using commodity maps
Infrastructure Access: Road, water, and port accessibility using Overture Maps and Google Places API
Building/Industrial Presence: Industrial facility and building analysis within 100m using Overture Places dataset with graduated scoring (large = +0.23, medium = +0.12, none = +0.0). The AI receives binary values (0/1) but scoring uses graduated values.
Business Context: Nearby POIs using multiple data sources
Geographic Suitability: Building density and latitude constraints for commodity production
Producer Verification: Cross-referencing facility information with external business databases

Endpoints¶

POST /validate_facilities¶

Validates multiple facility locations from an uploaded GeoJSON file.

Parameters:

Parameter	Type	Required	Default	Description
`file`	File	Yes	-	GeoJSON file containing facility geometries
`commodity_type`	string	No	-	Commodity type for validation (rubber, palm, cocoa, coffee, soy, timber, cattle)
`commodity_radius`	float	No	5000	Radius in meters to check for commodity presence
`check_water_access`	boolean	No	False	Whether to check water access proximity
`check_port_proximity`	boolean	No	False	Whether to check port proximity
`check_road_access`	boolean	No	True	Whether to check road access (fast Overture Places query)

Response:

Returns a streaming GeoJSON FeatureCollection with:

Collection Properties: Aggregate statistics across all facilities
Feature Properties: Individual validation results for each facility

Example Request:

curl -X POST "https://api.epoch.eco/validate_facilities" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@facilities.geojson" \
  -F "commodity_type=rubber" \
  -F "commodity_radius=3000" \
  -F "check_water_access=true"

GET /validate_facility¶

Validates a single facility location using a WKT geometry string.

Parameters:

Parameter	Type	Required	Default	Description
`geometry`	string	Yes	-	WKT geometry (Point, Polygon, etc.)
`commodity_type`	string	No	-	Commodity type for validation
`commodity_radius`	float	No	5000	Radius in meters to check for commodity presence
`check_water_access`	boolean	No	False	Whether to check water access proximity
`check_port_proximity`	boolean	No	False	Whether to check port proximity
`check_road_access`	boolean	No	True	Whether to check road access

Response:

Returns a GeoJSON FeatureCollection with a single feature containing validation results.

Example Request:

curl -X GET "https://api.epoch.eco/validate_facility" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -G \
  -d "geometry=POINT(100.5018 13.7563)" \
  -d "commodity_type=rubber" \
  -d "check_road_access=true"

Validation Criteria¶

Commodity Presence Scoring¶

The system evaluates commodity presence with latitude considerations:

+0.3 if commodity present AND facility in optimal latitude range
+0.25 if commodity present AND facility in viable latitude range
+0.2 if commodity present BUT facility outside viable latitude range
+0.15 if no commodity BUT facility in commodity-producing country AND optimal latitude
+0.12 if no commodity BUT facility in commodity-producing country AND viable latitude
+0.08 if no commodity BUT facility in commodity-producing country BUT outside viable latitude

Infrastructure & Location Factors¶

+0.10 for road access (if enabled)
+0.12 or +0.23 for building/industrial presence
+0.24 for relevant POIs (warehouses, processing facilities, agricultural businesses)
+0.08 for unrelated POIs (restaurants, retail)
+0.24 for low building density (rural/industrial areas)
+0.04 for water access (if enabled)
+0.04 for port proximity (if enabled)

Latitude Constraints by Commodity¶

Commodity	Optimal Range	Viable Range	Unlikely Beyond
Rubber	10°N-10°S	20°N/S	30°N/S
Palm Oil	10°N-10°S	15°N/S	20°N/S
Cocoa	20°N-20°S	25°N/S	30°N/S
Coffee	25°N-25°S	35°N/S	40°N/S
Soy	30°N-30°S	45°N/S	50°N/S
Timber	30°N-60°N, 30°S-60°S	20°N-70°N, 20°S-70°S	Extreme polar regions
Cattle	Global	Global	None

Commodity-Producing Countries¶

Rubber: Thailand, Vietnam, Indonesia, Malaysia, Ivory Coast, China, Ghana, Philippines, Laos, Cambodia, Myanmar, India, Bangladesh, Nepal, Bhutan, Liberia
Palm Oil: Thailand, Indonesia, Malaysia, Ivory Coast, Ghana, Nigeria, Ecuador, Honduras, Brazil, Colombia, Venezuela, Peru, Bolivia, Panama, Nicaragua, Guatemala, Belize, Liberia, Togo, Benin, Cameroon
Cocoa: Ghana, Ivory Coast, Ecuador, Colombia, Peru, Togo, Benin, Nigeria, Cameroon, Venezuela, Panama, Brazil, Bolivia, Dominican Republic, Liberia
Coffee: Peru, Brazil, Ecuador, Colombia, Nicaragua, Honduras, El Salvador, Uganda, Ethiopia, Indonesia, Vietnam, Argentina, Bolivia, Venezuela, Panama, Costa Rica, Guatemala, Belize, India, Sri Lanka, Malaysia, Myanmar, Cambodia, Thailand, Laos, Papua New Guinea
Soy: Argentina, Brazil, Paraguay, Uruguay, Bolivia
Timber: Global (all countries with forest cover)
Cattle: Global (all countries)

Response Format¶

Collection Properties (Aggregate Statistics)¶

{
  "type": "FeatureCollection",
  "properties": {
    "total_facilities": 382,
    "commodity_present": 315,
    "poi_present": 298,
    "road_access": 245,
    "water_access": 89,
    "port_proximity": 23,
    "high_density": 67,
    "confidence_score": 0.456,
    "confidence_level": {
      "high": 89,
      "medium": 149,
      "low": 144
    },
    "producer_confirmed": {
      "true": 156,
      "false": 226
    }
  },
  "features": [...]
}

Feature Properties (Individual Results)¶

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [100.5018, 13.7563]
  },
  "properties": {
    "commodity_present": 1,
    "poi_present": 1,
    "road_access": 1,
    "water_access": 0,
    "port_proximity": 0,
    "high_density": 0,
    "confidence_score": 0.820,
    "confidence_level": "high",
    "confidence_comment": "Strong commodity presence with relevant nearby businesses and good infrastructure access",
    "producer_confirmation_score": 0.750,
    "producer_confirmed": true,
    "producer_confirmation_comment": "Producer name matches nearby business listings and address is consistent"
  }
}

Confidence Levels¶

High (0.7-1.0): Strong evidence of commodity aggregation facility
Medium (0.4-0.7): Moderate evidence with some supporting factors
Low (0.0-0.4): Weak evidence or conflicting indicators

Data Sources¶

Earth Engine: Commodity presence detection and building density analysis using satellite imagery
Overture Maps: Road access, water features, building footprints, and POI data
Google Places API: Business listings and POI verification
Gemini AI: Combined analysis and scoring based on multiple factors

Performance Notes¶

Road Access: Uses fast Overture Places queries (default enabled)
Water Access: Uses Overture Places for water features (optional)
POI Detection: Combines Overture Maps and Google Places API
Commodity Detection: Earth Engine satellite analysis
Parallel Processing: All validation checks run concurrently for optimal performance

Error Handling¶

The API handles various error conditions:

Invalid geometries: Set to 0 scores with appropriate error messages
API timeouts: Graceful fallback with partial results
Missing data: Default to 0 values with explanatory comments
Rate limiting: Automatic retry with exponential backoff

Use Cases¶

Supply Chain Verification: Validate claimed aggregation facilities
Due Diligence: Assess facility suitability for commodity sourcing
Risk Assessment: Identify potentially fraudulent facility claims
Compliance: Support EUDR and other deforestation regulations
Site Selection: Evaluate potential locations for new facilities