added uvicorn web api

2026-09-02 20:20:01 +02:00
parent cabab25861
commit 7065dfd8d2
8 changed files with 250 additions and 0 deletions
@@ -0,0 +1,55 @@
+# Fundi Scraper API
+
+A small REST API (FastAPI) that serves the events scraped by
+[`scraper/scraper.py`](../scraper/scraper.py) from a JSON file.
+
+## Setup
+
+```bash
+cd api
+pip install -r requirements.txt
+```
+
+## Run
+
+```bash
+cd api
+uvicorn main:app --reload
+```
+
+Interactive docs: http://127.0.0.1:8000/docs
+
+By default the API reads `../fundi-scraped-output.json` (the repo root).
+Point it elsewhere with an env var:
+
+```bash
+DATA_FILE=/path/to/events.json uvicorn main:app
+```
+
+## Endpoints
+
+| Method | Path             | Description |
+|--------|------------------|-------------|
+| GET    | `/health`        | Status + number of events loaded |
+| GET    | `/events`        | List events, with optional filters (see below) |
+| GET    | `/events/{index}`| Single event by its position in the file (0-based) |
+| GET    | `/artists`       | Deduplicated, sorted list of all artist names |
+| POST   | `/reload`        | Re-read the JSON file from disk (after a fresh scrape) |
+
+### `/events` query parameters
+
+| Param      | Type   | Meaning |
+|------------|--------|---------|
+| `free`     | bool   | Only free / only paid events |
+| `name`     | string | Case-insensitive substring match on the event name |
+| `artist`   | string | Case-insensitive substring match on any artist name |
+| `date`     | string | Exact match on the raw date string (`dd.mm.yy`) |
+| `upcoming` | bool   | `true` = today or later, `false` = past events |
+
+Examples:
+
+```bash
+curl 'http://127.0.0.1:8000/events?free=true'
+curl 'http://127.0.0.1:8000/events?artist=randali&upcoming=true'
+curl 'http://127.0.0.1:8000/events/0'
+```