# B2 Image URL JSON API

Returns Backblaze B2 image URLs for a given camera and time period as JSON.

## Base URL

```
https://www.livetimelapse.com.au/php/tlc.include.b2api.php
```

## Required Parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| `cam` | Camera identifier (underscore format, must start with `tlc_`) | `tlc_johnholland_lakemacdonald2_jn1061` |
| `mode` | Time period mode | `last2hours`, `today`, `yesterday`, `project`, `custom` |

## Mode Descriptions

| Mode | Description |
|------|-------------|
| `last2hours` | Last 2 hours of images. If outside operating hours, returns the last 2 hours of the most recent operating period. |
| `today` | All images from today within operating hours |
| `yesterday` | All images from yesterday within operating hours |
| `project` | Sampled images across the entire project date range, limited to `max_project_images` |
| `custom` | Custom date/time range (requires s1*/s2* parameters) |

## Custom Mode Parameters

Required when `mode=custom`:

| Parameter | Description | Example |
|-----------|-------------|---------|
| `s1y` | Start year | `2026` |
| `s1m` | Start month (3-letter lowercase) | `feb` |
| `s1d` | Start day | `07` |
| `s1t` | Start time (HHMM, 24hr) | `0600` |
| `s2y` | Stop year | `2026` |
| `s2m` | Stop month (3-letter lowercase) | `feb` |
| `s2d` | Stop day | `07` |
| `s2t` | Stop time (HHMM, 24hr) | `1800` |

## Optional Parameters

### Operating Hours

| Parameter | Description | Default |
|-----------|-------------|---------|
| `project_start_hour` | Daily start hour (1-12) | `6` |
| `project_start_ampm` | AM/PM for start | `am` |
| `project_stop_hour` | Daily stop hour (1-12) | `6` |
| `project_stop_ampm` | AM/PM for stop | `pm` |

### Project Mode

| Parameter | Description | Default |
|-----------|-------------|---------|
| `project_start_date` | Project start date (YYYYMMDD) | `20200101` |
| `project_stop_date` | Project stop date (YYYYMMDD) | `20301231` |
| `max_project_images` | Maximum images to return in project mode | `200` |

### Project Limit Hours (narrower sampling window)

| Parameter | Description | Default |
|-----------|-------------|---------|
| `project_limit_start_hour` | Narrow sampling start hour | (empty = use project_start_hour) |
| `project_limit_start_ampm` | AM/PM | `am` |
| `project_limit_stop_hour` | Narrow sampling stop hour | (empty = use project_stop_hour) |
| `project_limit_stop_ampm` | AM/PM | `pm` |

### Image Settings

| Parameter | Description | Default |
|-----------|-------------|---------|
| `image_size` | Image dimension filter | `980x655` |

## Response Format

### Success Response

```json
{
    "status": "success",
    "camera": "tlc_johnholland_lakemacdonald2_jn1061",
    "mode": "yesterday",
    "time_range": {
        "start": "2026-02-06T06:00:00+10:00",
        "stop": "2026-02-06T18:00:00+10:00"
    },
    "image_size": "980x655",
    "image_count": 358,
    "images": [
        "https://tlc-johnholland-lakemacdonald2-jn1061.s3.us-west-002.backblazeb2.com/tlc_johnholland_lakemacdonald2_jn1061/2026/02/06/980x655_060001.jpg",
        "https://tlc-johnholland-lakemacdonald2-jn1061.s3.us-west-002.backblazeb2.com/tlc_johnholland_lakemacdonald2_jn1061/2026/02/06/980x655_060201.jpg"
    ]
}
```

### Error Response

```json
{
    "status": "error",
    "message": "Missing required parameter: cam"
}
```

### Possible Errors

| Message | Cause |
|---------|-------|
| `Missing required parameter: cam` | No `cam` parameter provided |
| `Missing required parameter: mode` | No `mode` parameter provided |
| `Invalid mode. Must be one of: ...` | Unrecognized mode value |
| `Invalid camera identifier format` | Camera name doesn't match expected pattern |
| `Custom mode requires start/stop parameters` | Missing s1y/s2y for custom mode |
| `Start time is after stop time` | Invalid time range |
| `Camera not found in database or B2 region not configured` | Unknown camera or missing B2 config |
| `Database connection failed` | Server-side DB issue |

## Usage Examples

### Last 2 Hours
```bash
curl "https://www.livetimelapse.com.au/php/tlc.include.b2api.php?cam=tlc_johnholland_lakemacdonald2_jn1061&mode=last2hours&project_start_hour=6&project_start_ampm=am&project_stop_hour=6&project_stop_ampm=pm"
```

### Today
```bash
curl "https://www.livetimelapse.com.au/php/tlc.include.b2api.php?cam=tlc_johnholland_lakemacdonald2_jn1061&mode=today&project_start_hour=6&project_start_ampm=am&project_stop_hour=6&project_stop_ampm=pm"
```

### Yesterday
```bash
curl "https://www.livetimelapse.com.au/php/tlc.include.b2api.php?cam=tlc_johnholland_lakemacdonald2_jn1061&mode=yesterday&project_start_hour=6&project_start_ampm=am&project_stop_hour=6&project_stop_ampm=pm"
```

### Project (sampled across date range)
```bash
curl "https://www.livetimelapse.com.au/php/tlc.include.b2api.php?cam=tlc_johnholland_lakemacdonald2_jn1061&mode=project&project_start_date=20240101&project_start_hour=6&project_start_ampm=am&project_stop_hour=6&project_stop_ampm=pm&max_project_images=200"
```

### Custom Date Range
```bash
curl "https://www.livetimelapse.com.au/php/tlc.include.b2api.php?cam=tlc_johnholland_lakemacdonald2_jn1061&mode=custom&s1y=2026&s1m=feb&s1d=06&s1t=1000&s2y=2026&s2m=feb&s2d=06&s2t=1200"
```

## Notes

- The timezone is set automatically based on the camera's configured location
- Operating hours (`project_start_hour`/`project_stop_hour`) should match the values used in the camera's HTML page
- For `last2hours` mode, if the current time is outside operating hours, the API returns the last 2 hours of the most recent operating period
- For `project` mode, images are evenly sampled across the date range, limited to `max_project_images`
- The `project_limit_start_hour`/`project_limit_stop_hour` parameters narrow the daily window for project mode sampling (e.g., to only sample around noon)
- CORS is enabled (Access-Control-Allow-Origin: *)
- Response is UTF-8 encoded JSON with `Content-Type: application/json`

## Files

| File | Purpose |
|------|---------|
| `tlc.include.b2api.php` | Main API endpoint |
| `tlc.include.b2native-camconfig.php` | Shared camera configuration (timezone, image size) |
| `tlc.include.b2native.php` | Original HTML/JS include (for reference) |
| `tlc.include.a-script.php` | Auto-generated camera configs (included by camconfig) |