Add Python examples for FPL teams, league standings and transfers

2026-10-24 11:05:49 +01:00
commit a9521479c0
@@ -0,0 +1,74 @@
+# Fantasy Premier League API: three Python examples
+
+These standalone examples use Python 3's standard library. No packages, API key,
+or login are needed for these public GET requests.
+
+## Run the examples
+
+Open a terminal in this folder, then run:
+
+```sh
+python3 team.py
+python3 league.py
+python3 transfers.py
+```
+
+`team.py` defaults to fantasy team **2134**. It prints the manager, overall points
+and rank, then the latest published gameweek's squad, including captain and bench.
+It joins player IDs from the picks response with names, clubs and positions from
+the bootstrap response.
+
+`league.py` defaults to classic league **37803**, **Special Teams, Special Players**.
+It prints the first page of standings with team names, managers, gameweek points,
+total points and entry IDs. You can pass an entry ID to the team script.
+
+`transfers.py` defaults to fantasy team **2134**. It prints public transfer history,
+newest first, with UTC timestamps, gameweeks, players sold and bought, and their
+transfer prices in millions of pounds. Player IDs are joined to bootstrap data
+to display readable names.
+
+```sh
+python3 team.py --team-id 2134 --gameweek 7
+python3 league.py --league-id 37803 --page 2
+python3 league.py --league-id 37803 --all-pages
+python3 transfers.py --team-id 2134 --gameweek 7
+```
+
+`--all-pages` starts at `--page` (page 1 by default). Run any script with
+`--help` for its options.
+
+## What the API calls demonstrate
+
+Each script builds a URL, sends an HTTP GET with `urllib.request.urlopen`, parses
+the JSON using `json.load`, and reads fields from Python dictionaries and lists.
+The small request helper is repeated to keep each example self-contained.
+
+| Endpoint, relative to `https://fantasy.premierleague.com/api/` | Purpose |
+| --- | --- |
+| `entry/2134/` | Fantasy team and manager summary |
+| `entry/2134/event/7/picks/` | Squad selection for gameweek 7 |
+| `entry/2134/transfers/` | Public transfer history for the current season |
+| `bootstrap-static/` | Player, club, position and gameweek reference data |
+| `leagues-classic/37803/standings/?page_standings=1` | One page of classic league standings |
+
+Try opening the [team JSON](https://fantasy.premierleague.com/api/entry/2134/)
+or [league JSON](https://fantasy.premierleague.com/api/leagues-classic/37803/standings/)
+in your browser to compare the raw response with the printed output.
+
+## Useful details
+
+- A fantasy team ID is an **entry ID**, not a Premier League club ID or player ID.
+- Gameweek selections are public after the deadline. This does not show a
+  manager's unpublished changes for the next deadline. The role column describes
+  the selected lineup; it does not apply automatic substitutions or chip scoring.
+- The league example is for **classic** leagues, not head-to-head leagues.
+- The transfers example shows only the history published by the public API.
+  Transfers for an upcoming deadline may not be public yet. Prices are the sale
+  and purchase prices recorded for each transfer, not current player prices;
+  they do not indicate transfer points deductions.
+- Standings are paginated; `has_next` tells the script whether another page exists.
+  Newly joined entries may not appear in the ranked standings yet.
+- Data and IDs are season-specific. These public website endpoints can change;
+  use the response's league name to confirm the intended league after a reset.
+- Requests have a 20-second timeout. HTTP/network errors produce a message and a
+  nonzero exit status. Avoid repeatedly polling the service in a tight loop.