added sorting and artist dates

README.md

@@ -126,7 +126,7 @@ DATA_FILE=/path/to/events.json ARCHIVE_DATA_FILE=/path/to/archive.json uvicorn m
 | `GET`  | `/events` | List events, with optional filters (below) |
 | `GET`  | `/events/archive` | Past events only — shorthand for `/events?upcoming=false` |
 | `GET`  | `/events/{index}` | A single event by its 0-based position in the merged list; `404` if out of range |
-| `GET`  | `/artists` | Deduplicated, case-insensitively sorted list of all artist names |
+| `GET`  | `/artists` | Deduplicated, case-insensitively sorted list of all artists, each with every date they appear on |
 | `GET`  | `/calendar.ics` | iCalendar/webcal feed of all events — subscribe from any calendar app |
 | `POST` | `/reload` | Re-read the data file(s) from disk (call after re-running the scraper); rate-limited (below); `500` if the main file is missing |
 
@@ -142,6 +142,7 @@ same filters except `upcoming` (it's always `false`).
 | `artist` | string | Case-insensitive substring match on any artist name in the line-up |
 | `date` | string | Exact match on the raw `event_date` string (`dd.mm.yy`) |
 | `upcoming` | bool | `true` = event date is today or later, `false` = past events (events with an unparseable date are excluded) |
+| `sort` | string | `asc`/`desc` = chronological by `event_date` (events with an unparseable date always sort last, regardless of direction); `az`/`za` = alphabetical by `event_name` (case-insensitive) |
 
 ### Response shapes
 
@@ -155,7 +156,15 @@ same filters except `upcoming` (it's always `false`).
 ```
 
 `GET /events/{index}` returns a single event object (same schema as the scraper
-output). `GET /artists` returns a plain JSON array of strings.
+output). `GET /artists` returns each artist once with every date (past or
+upcoming) they're in the line-up for, sorted chronologically:
+
+```json
+[
+  { "artist_name": "Bizarre", "dates": ["05.09.26", "12.10.26"] },
+  { "artist_name": "Skkin Velvet", "dates": ["04.09.26"] }
+]
+```
 
 ### Scrape schedule reporting
 
@@ -238,6 +247,9 @@ curl 'https://fundi.api.example.com/events?artist=randali&upcoming=true'
 # Everything on a given night
 curl 'https://fundi.api.example.com/events?date=05.09.26'
 
+# Soonest events first
+curl 'https://fundi.api.example.com/events?sort=asc'
+
 # Past events (archive)
 curl https://fundi.api.example.com/events/archive