bytetrack-counter-python/API.md

# counter_dashboard.py — API Documentation

## Page

### `GET /`
Renders the main dashboard HTML page (`dashboard.html`).

---

## API Endpoints

### `GET /api/live-video`
MJPEG streaming endpoint. Serves live frames from the path configured in `LIVE_STREAM_FRAME_PATH` (default `/dev/shm/jetson-counter/live_frame.jpg`) as `multipart/x-mixed-replace`.

**Response:** JPEG stream with `--frame` boundary delimiters.

---

### `GET /api/current-batch`
Returns the currently active batch's data read from `current_batch.json`.

**Success response:**
```json
{
  "success": true,
  "counting_date": "2024-01-01",
  "batch_number": 12,
  "count": 342,
  "start_time": "2024-01-01T14:30:00",
  "last_detection_time": "2024-01-01T14:35:00"
}
```

**Error response (no active batch, 200):**
```json
{
  "success": false,
  "error": "No active batch",
  "count": 0,
  "batch_number": null,
  "counting_date": null
}
```

---

### `GET /api/previous-batch`
Returns the most recently completed batch from the `batches` database table, with computed `duration_minutes`.

**Success response:**
```json
{
  "success": true,
  "date": "2024-01-01",
  "batch_number": 11,
  "count": 287,
  "start_time": "2024-01-01T14:00:00",
  "end_time": "2024-01-01T14:27:00",
  "duration_minutes": 27.0
}
```

---

### `GET /api/summary`
Returns today, yesterday, and all-time aggregate statistics plus average per day and best day.

**Success response:**
```json
{
  "today": {
    "date": "2024-01-01",
    "total_count": 1500,
    "total_batches": 8
  },
  "yesterday": {
    "date": "2023-12-31",
    "total_count": 1342,
    "total_batches": 7
  },
  "all_time": {
    "grand_total": 50000,
    "grand_batches": 260,
    "total_days": 45
  },
  "average_per_day": 1111.1,
  "best_day": {
    "date": "2023-12-15",
    "count": 2100
  }
}
```

---

### `GET /api/daily-data`
Returns daily summary rows for charting.

**Query params:**
| Param  | Type | Default | Description                     |
|--------|------|---------|---------------------------------|
| `days` | int  | 30      | Number of days to look back     |

**Response:**
```json
[
  {
    "date": "2024-01-01",
    "total_count": 1500,
    "total_batches": 8,
    "avg_per_batch": 187.5
  }
]
```

---

### `GET /api/day-detail/<date>`
Returns all batch records for a specific `counting_date` along with summary totals.

**Path params:**
| Param  | Type   | Description            |
|--------|--------|------------------------|
| `date` | string | Date in `YYYY-MM-DD`   |

**Success response:**
```json
{
  "date": "2024-01-01",
  "total_count": 1500,
  "total_batches": 8,
  "total_duration_minutes": 216.0,
  "avg_duration_minutes": 27.0,
  "batches": [
    {
      "batch_number": 1,
      "count": 187,
      "start_time": "2024-01-01T08:00:00",
      "end_time": "2024-01-01T08:27:00",
      "duration_minutes": 27.0
    }
  ]
}
```

---

### `GET /api/recent-batches`
Returns the most recent batches with computed durations.

**Query params:**
| Param   | Type | Default | Description                     |
|---------|------|---------|---------------------------------|
| `limit` | int  | 10      | Max number of batches to return |

**Response:**
```json
[
  {
    "date": "2024-01-01",
    "batch_number": 8,
    "count": 213,
    "start_time": "2024-01-01T16:30:00",
    "end_time": "2024-01-01T16:58:00",
    "duration_minutes": 28.0
  }
]
```

---

### `GET /api/available-dates`
Returns all dates with data from the `daily_summaries` table, ordered by date descending.

**Response:**
```json
[
  {
    "date": "2024-01-01",
    "total_count": 1500,
    "total_batches": 8
  }
]
```

---

## Export Endpoints (XLSX)

### `GET /api/export-daily-csv`
Exports batch detail records for the last N days as an `.xlsx` file.

**Query params:**
| Param  | Type | Default | Description                 |
|--------|------|---------|-----------------------------|
| `days` | int  | 30      | Number of days to look back |

**Response:** XLSX file download with columns: Date, Batch #, Count, Start Time, End Time, Duration (min).

Filename format: `{SITE_NAME}_daily_records_{timestamp}.xlsx`

---

### `GET /api/export-day-csv/<date>`
Exports all batch records for a single date as an `.xlsx` file.

**Path params:**
| Param  | Type   | Description          |
|--------|--------|----------------------|
| `date` | string | Date in `YYYY-MM-DD` |

**Response:** XLSX file download with columns: Batch Number, Count, Start Time, End Time, Duration (min).

Filename format: `{SITE_NAME}_day_detail_{date}.xlsx`

---

## Error Handling

All endpoints return `{"success": false, "error": "<message>"}` with HTTP 500 on unexpected errors. Database-unavailable errors (`sqlite3.OperationalError`) return HTTP 200 with an empty/default data structure. The `/api/live-video` endpoint returns HTTP 503 if the frame file is not found.