# WorldTrashDay.org
> The year-round global cleanup ledger and civic debris coordination network. Register a zone. Clean it up. Put it on the permanent record.

WorldTrashDay.org is an open civic platform for coordinating neighbourhood and community cleanups globally, powered by the Open Debris Event Standard (ODES v0.1). Fleet operators, municipalities, waste haulers, ride platforms, and good samaritans participate through a shared covenant — the World Trash Day Compact.

## Core Concepts

- **ODES**: Open Debris Event Standard v0.1. CC0 public-domain JSON schema for reporting observed debris fields. Maintained at worldtrashday.org/api-docs.
- **Debris Zone**: Geographic area confirmed by 2+ independent ODES reports within 200m radius. Classified T1 (minor litter, score < 4), T2 (bulk debris, 4–7), T3 (biohazard/critical, ≥ 7).
- **Chapter**: Named cleanup organisation at worldtrashday.org/{slug}. Schools, NGOs, municipalities, corporate teams.
- **Pledge**: Individual commitment to clean a zone. Appears on the global map.
- **Proof Submission**: Before/after photos + participant count. Permanent public ledger entry.
- **Compact Signatory**: Organisation that has signed the World Trash Day Compact.
- **Trash Drop Location**: Registered site where good samaritans can deposit sealed T1/T2 debris bags for pickup by a Covenant Hauler.
- **Covenant Hauler**: Waste management organisation registered to service one or more Trash Drop Locations.
- **Trash Run**: In-vehicle or mobile experience that routes volunteers to nearest confirmed T1/T2 debris zones.
- **Trash Ride**: Free ride-hailing trip provided by participating platforms to verified good samaritans traveling to/from cleanup sites.

## ODES v0.1 API — Debris Events & Zones

All read endpoints are public (no auth). Write endpoints require Bearer API key.
Base URL: https://worldtrashday.org

### Submit Events (auth required)
- POST /api/wtd/v1/events — Submit a debris detection event. Body: { lat, lng, debris_score (0-10), confidence (0-1), debris_tags (string[]), sharps_present, human_population_present, estimated_area_m2, source_operator, thumbnail_url }. Creates or updates a zone within 200m radius. Returns { zone_id, status, report_count, debris_tier, confirmed }.
- POST /api/wtd/v1/analyze-image — AI vision analysis. Accepts multipart image or { imageUrl }. Returns { debris_score, tier, tags, confidence, estimated_area_m2, analysis }.

### Query Zones (public)
- GET /api/wtd/v1/zones — List debris zones. Query params: status (active/claimed/cleared), tier (T1/T2/T3), lat, lng, radius_m, country. Returns { zones[], total, schema_version }.
- GET /api/wtd/v1/zones/:id — Single zone record with all events.
- GET /api/wtd/v1/feed — Latest 50 debris events across all zones.

### Zone Actions (auth required)
- POST /api/wtd/v1/zones/:id/claim — Claim a zone for cleanup. Body: { claimed_by }. Sets status to 'claimed'.
- POST /api/wtd/v1/zones/:id/clear — Mark zone resolved. Body: { actor_type, bags_collected, notes }. Sets status to 'cleared'.

## Trash Drop Network API

### Query (public)
- GET /api/wtd/v1/drop-locations — List Trash Drop locations. Params: status, country, lat, lng, radius_m. Returns { locations[], total }.
- GET /api/wtd/v1/drop-locations/:id — Single drop location.

### Register & Update (auth required)
- POST /api/wtd/v1/drop-locations — Register a new drop location. Body: { name, operator_name, operator_type, address, lat, lng, city, country, max_capacity_bags, hours, contact_email, hauler_name, hauler_pickup_frequency, accepts_t1, accepts_t2, accepts_t3, alert_threshold_pct }.
- PATCH /api/wtd/v1/drop-locations/:id/log-drop — Log a bag drop. Body: { bags }. Returns { fill_pct, alert }.

## Community API

### Chapters
- GET /api/wtd/chapters — List all chapters.
- GET /api/wtd/chapter/:slug — Single chapter with pledges and proofs.
- POST /api/wtd/chapter — Create chapter.

### Proof Submissions
- POST /api/wtd/submit — Submit cleanup proof (submitterName, city, country, participantCount, bagsEstimate, areaCleaned, beforePhotoUrl, afterPhotoUrl, motivation, chapterId).
- POST /api/wtd/upload-image — Upload photo (multipart/form-data, field: photo). Returns { url }.
- GET /api/wtd/ledger — Paginated proof list.

### Compact & Status
- GET /api/wtd/compact/signatories — All Compact signatories.
- POST /api/wtd/compact/sign — Sign the Compact.
- GET /api/wtd/compact/status — Platform status: { signatories, drop_locations, operators, invitations, compact_version }.

### Stats & Geocoding
- GET /api/wtd/stats — { submissions, pledges, nations, chapters }.
- GET /api/wtd/geocode?q=QUERY — Nominatim geocoding proxy.

## Privacy Rules (ODES Article VII)
- No ODES event may include personally identifiable information, facial imagery, or license plates.
- When human_population_present: true, zone is flagged and no volunteer dispatch proceeds until social services outreach has assessed site.
- Debris detection may not be used for law enforcement, encampment enforcement, or immigration enforcement.

## Debris Tier Definitions
- T1 (score < 4): Minor litter. Volunteer dispatch OK.
- T2 (score 4–7): Bulk debris. Volunteer dispatch OK.
- T3 (score ≥ 7): Biohazard or critical accumulation. Social services review required before any volunteer dispatch. Trash Run excludes T3 zones.

## Ecosystem Features
- **Trash Run** (/run): Routes volunteers to nearest confirmed T1/T2 zones. EV/AV onboard cache of confirmed zones via GET /api/wtd/v1/zones. Claim and clear zones via API.
- **Trash Drop** (/drop, /drop/register): Community bag drop network. Register sites at /drop/register. Map of active sites with fill-level tracking.
- **Trash Ride** (/ride): Ride-hailing subsidy program for verified good samaritans. Eligibility via WorldTrashDay.org proof record. Partner discussions open at partnerships@worldtrashday.org.

## Pages
- / — Landing page with mission, map, stats
- /developers — Full developer platform documentation
- /api-docs — ODES API reference
- /run — Trash Run: route to nearest debris zone
- /drop — Trash Drop locations map
- /drop/register — Register a Trash Drop location
- /ride — Trash Ride program info
- /organize — Create a chapter
- /pledge — Pledge a cleanup zone
- /submit — Submit before/after proof
- /ledger — Public cleanup ledger (all submissions worldwide)
- /compact — World Trash Day Compact
- /operators — Fleet operator scorecard
- /{slug} — Individual chapter page

## Discovery Files
- /llms.txt — This file. Natural language API description for AI agents.
- /.well-known/srr.json — Machine-readable endpoint manifest (Source Routing Record).
- /sitemap.xml — XML sitemap.
- /robots.txt — Crawl permissions.