yield-analytics

# yield-analytics

Query aggregated yield data from harvest-logger's analytics endpoints for trend analysis, crop comparison, and quality reporting.

## When to Use

- Finding total yield for one crop across a date range
- Comparing yield performance across fields
- Identifying which crops have the best Grade A rate
- Generating weekly or monthly yield trend data
- Comparing this season's performance to last season
- Building reports from harvest data

## Analytics Endpoints

All endpoints support `?from=YYYY-MM-DD&to=YYYY-MM-DD` date range filtering.

### Yield by Crop

```bash
# Total yield per crop
curl "http://localhost:3003/api/analytics/yield-by-crop"

# With date range
curl "http://localhost:3003/api/analytics/yield-by-crop?from=2025-04-01&to=2025-04-30"
```

Response:
```json
{
  "data": [
    { "crop_id": "...", "crop_name": "Tomatoes", "total": 1840, "unit": "kg", "harvest_days": 24 },
    { "crop_id": "...", "crop_name": "Beans", "total": 940, "unit": "kg", "harvest_days": 18 }
  ]
}
```

### Yield by Field

```bash
curl "http://localhost:3003/api/analytics/yield-by-field?from=2025-04-01"
```

Response includes `total`, `unit`, `harvest_count`, and `area_acres` for yield-per-acre calculation.

### Yield Trend

```bash
# Daily totals for a crop
curl "http://localhost:3003/api/analytics/yield-trend?crop_id=...&granularity=day"

# Weekly totals across all crops
curl "http://localhost:3003/api/analytics/yield-trend?granularity=week"
```

Granularity values: `day`, `week`, `month`

Response:
```json
{
  "data": [
    { "period": "2025-W14", "total": 480 },
    { "period": "2025-W15", "total": 520 }
  ]
}
```

### Grade Breakdown

```bash
# Grade distribution per crop
curl "http://localhost:3003/api/analytics/grade-breakdown"

# For a specific crop
curl "http://localhost:3003/api/analytics/grade-breakdown?crop_id=..."
```

Response:
```json
{
  "data": [
    {
      "crop_name": "Tomatoes",
      "total": 1840,
      "grades": {
        "A": { "quantity": 1490, "percent": 81 },
        "B": { "quantity": 258, "percent": 14 },
        "C": { "quantity": 55, "percent": 3 },
        "reject": { "quantity": 37, "percent": 2 }
      }
    }
  ]
}
```

### Top Crops

```bash
# Top 10 crops by total volume
curl "http://localhost:3003/api/analytics/top-crops"

# Top 5 only
curl "http://localhost:3003/api/analytics/top-crops?limit=5"
```

## Season Comparison Pattern

To compare two seasons, make two calls with different date ranges:

```bash
# 2025 season (April only)
curl "http://localhost:3003/api/analytics/yield-by-crop?from=2025-04-01&to=2025-04-30"

# 2024 same period
curl "http://localhost:3003/api/analytics/yield-by-crop?from=2024-04-01&to=2024-04-30"
```

The Season Comparison page in the UI does this automatically.

## Calculated Metrics

Some metrics are derived from the raw data:

| Metric | Calculation |
|---|---|
| Average daily yield | total / harvest_days |
| Yield per acre | field_total / area_acres |
| Grade A rate | grade_A_quantity / total * 100 |
| Year-over-year change | (this_year - last_year) / last_year * 100 |

These calculations are performed client-side in the Analytics page using Chart.js datasets.

## Troubleshooting

### Top crops endpoint shows wrong ranking

The endpoint ranks by `SUM(quantity)`. If different crops use different units (some kg, some count), the ranking will not be unit-comparable. Ensure you use consistent units for crops you want to compare analytically, or filter by unit: `?unit=kg`.

### Yield trend shows gaps in dates

Dates with no harvests have no data points. The Chart.js line chart connects existing points, which may create visual gaps for days with no harvests. This is expected behavior.

### Grade breakdown shows less than 100%

If some entries are `ungraded`, the A+B+C+Reject percentages will not sum to 100%. The Analytics page UI shows ungraded as a separate segment.