fc-clubs-api 0.1.0__tar.gz

fc_clubs_api-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Erkan Dogan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fc_clubs_api-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: fc-clubs-api
+Version: 0.1.0
+Summary: Unofficial Python client for the EA Sports FC 27 Pro Clubs API, returning pandas DataFrames.
+Author: Erkan Dogan
+License: MIT License
+        
+        Copyright (c) 2025 Erkan Dogan
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/1erkandogan/fc27-clubs-api
+Project-URL: Issues, https://github.com/1erkandogan/fc27-clubs-api/issues
+Keywords: ea,fc27,pro clubs,api,pandas
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pandas>=1.5
+Dynamic: license-file
+
+# FC 27 Clubs API
+
+An unofficial Python client for the **EA Sports FC 27 Pro Clubs API**, the same
+endpoints `proclubs.ea.com` calls from the browser. You can find clubs and get
+their stats, members, matches and per-player match ratings as tables (pandas
+DataFrames).
+
+Not affiliated with or endorsed by EA. The endpoints are undocumented and can
+change without notice.
+
+- **New to Python, or want to know how it works?** Read [docs/how-it-works.md](docs/how-it-works.md).
+  It walks through the code and explains every import and decision.
+- **Want EA's raw responses?** See [docs/endpoints.md](docs/endpoints.md).
+
+## Install
+
+You need Python 3.9 or newer.
+
+```bash
+pip install fc-clubs-api   # also installs pandas, the only dependency
+```
+
+No API key needed. The whole client is one file, [`fc_clubs_api.py`](fc_clubs_api.py),
+and you import it as `fc_clubs_api`.
+
+To work on the code itself, install from a clone instead:
+
+```bash
+git clone https://github.com/1erkandogan/fc27-clubs-api.git
+cd fc27-clubs-api
+pip install -e .   # your edits to fc_clubs_api.py take effect without reinstalling
+```
+
+## Quick start
+
+```python
+from fc_clubs_api import FC27API
+
+api = FC27API(timezone="Europe/Istanbul")      # match times in your timezone
+
+club_id = api.find_club_id("Your Club Name")   # -> the id, e.g. 1001
+
+print(api.get_club_matches(club_id))           # last 10 league matches
+print(api.get_member_stats(club_id))           # squad stats this season
+```
+
+Or run the example: `python examples/quickstart.py "Your Club Name"`
+
+## Methods
+
+| Method | Gives you (one row per ...) |
+|---|---|
+| `find_club_id(name)` | the club's id as a number. If several clubs match, the error lists them. |
+| `search_club_by_name(name)` | club matching the name: division, wins, goals, points |
+| `get_club_details(club_id)` | club (1 row): name, ids, stadium |
+| `get_club_overall_stats(club_id)` | club (1 row): record, goals, streaks, skill rating |
+| `get_member_stats(club_id)` | member: games, goals, assists, average rating, pass/tackle rates |
+| `get_member_career_stats(club_id)` | member: career totals at the club |
+| `get_club_matches(club_id, match_type="leagueMatch", count=10)` | match, from your side: opponent, score, `result` (win/draw/loss), `dnf` |
+| `get_match_players(club_id, match_type="leagueMatch", count=10, both_teams=False)` | player per match: rating, goals, assists, shots, passes, tackles |
+| `get_playoff_achievements(club_id)` | achievement (EA has only returned an empty list so far) |
+| `get_json(endpoint, params)` | EA's raw response as dicts/lists, e.g. `api.get_json("clubs/info", {"clubIds": 1001})` |
+
+- `match_type` is `"leagueMatch"`, `"friendlyMatch"` or `"playoffMatch"`.
+- By default, tables have a short set of readable columns. Add `all_columns=True` to
+  `search_club_by_name`, `get_club_details`, `get_club_overall_stats`,
+  `get_member_stats` or `get_match_players` to get every field EA sends, with EA's names.
+- `FC27API(platform="common-gen5", timeout=10, timezone="UTC")`: all settings are optional.
+- If there is no data, you get an empty table (`df.empty` is `True`).
+
+## Recipes
+
+```python
+from fc_clubs_api import FC27API
+
+api = FC27API(timezone="Europe/Istanbul")
+club_id = api.find_club_id("Your Club Name")
+
+# Top 5 scorers this season
+members = api.get_member_stats(club_id)
+print(members.sort_values("goals", ascending=False).head(5)[["name", "goals", "assists"]])
+
+# Last 5 league results
+matches = api.get_club_matches(club_id)
+print(matches.head(5)[["timestamp", "opponentName", "goals", "goalsAgainst", "result"]])
+
+# Win rate over the last 10 league matches
+wins = (matches["result"] == "win").sum()
+print(f"Won {wins} of {len(matches)}")
+
+# One player's recent matches
+players = api.get_match_players(club_id)
+print(players[players["name"] == "YourGamertag"][["timestamp", "rating", "goals", "assists"]])
+
+# Average match rating per player, best first
+print(players.groupby("name")["rating"].mean().sort_values(ascending=False))
+
+# Save any table to open in Excel
+members.to_csv("members.csv", index=False)
+# members.to_excel("members.xlsx", index=False)   # needs: pip install openpyxl
+```
+
+## Errors
+
+- **`FC27APIError`**: EA couldn't be reached, refused the request, or didn't send JSON.
+- **`ValueError`**: you passed something invalid, such as an unknown `match_type`, or a
+  club name that `find_club_id` couldn't match to one club.
+
+```python
+from fc_clubs_api import FC27API, FC27APIError
+
+try:
+    df = FC27API().get_club_details(1001)
+except FC27APIError as error:
+    print("EA problem:", error)
+```
+
+## Good to know
+
+- **EA blocks non-browser requests.** Every request sends browser-like headers
+  (`HEADERS` in `fc_clubs_api.py`). Without them EA answers 403 or doesn't answer at all.
+  Plain `curl` is blocked even with the headers, while Python works.
+- **No caching or rate limiting.** Every call goes straight to EA. If you loop over
+  many clubs, add a pause between requests (`time.sleep(1)`) so you don't get blocked.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+The tests run offline, using EA responses saved in `tests/fixtures/`. They keep the real structure,
+but every club and player name, id and date is a placeholder.
+
+## Contributing
+
+Bug reports are welcome, especially when EA changes something and the client
+breaks. Please open an issue before writing code: the project is deliberately
+small and some things that look like oversights are decisions. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT, see [LICENSE.md](LICENSE.md).

fc_clubs_api-0.1.0/README.md

@@ -0,0 +1,144 @@
+# FC 27 Clubs API
+
+An unofficial Python client for the **EA Sports FC 27 Pro Clubs API**, the same
+endpoints `proclubs.ea.com` calls from the browser. You can find clubs and get
+their stats, members, matches and per-player match ratings as tables (pandas
+DataFrames).
+
+Not affiliated with or endorsed by EA. The endpoints are undocumented and can
+change without notice.
+
+- **New to Python, or want to know how it works?** Read [docs/how-it-works.md](docs/how-it-works.md).
+  It walks through the code and explains every import and decision.
+- **Want EA's raw responses?** See [docs/endpoints.md](docs/endpoints.md).
+
+## Install
+
+You need Python 3.9 or newer.
+
+```bash
+pip install fc-clubs-api   # also installs pandas, the only dependency
+```
+
+No API key needed. The whole client is one file, [`fc_clubs_api.py`](fc_clubs_api.py),
+and you import it as `fc_clubs_api`.
+
+To work on the code itself, install from a clone instead:
+
+```bash
+git clone https://github.com/1erkandogan/fc27-clubs-api.git
+cd fc27-clubs-api
+pip install -e .   # your edits to fc_clubs_api.py take effect without reinstalling
+```
+
+## Quick start
+
+```python
+from fc_clubs_api import FC27API
+
+api = FC27API(timezone="Europe/Istanbul")      # match times in your timezone
+
+club_id = api.find_club_id("Your Club Name")   # -> the id, e.g. 1001
+
+print(api.get_club_matches(club_id))           # last 10 league matches
+print(api.get_member_stats(club_id))           # squad stats this season
+```
+
+Or run the example: `python examples/quickstart.py "Your Club Name"`
+
+## Methods
+
+| Method | Gives you (one row per ...) |
+|---|---|
+| `find_club_id(name)` | the club's id as a number. If several clubs match, the error lists them. |
+| `search_club_by_name(name)` | club matching the name: division, wins, goals, points |
+| `get_club_details(club_id)` | club (1 row): name, ids, stadium |
+| `get_club_overall_stats(club_id)` | club (1 row): record, goals, streaks, skill rating |
+| `get_member_stats(club_id)` | member: games, goals, assists, average rating, pass/tackle rates |
+| `get_member_career_stats(club_id)` | member: career totals at the club |
+| `get_club_matches(club_id, match_type="leagueMatch", count=10)` | match, from your side: opponent, score, `result` (win/draw/loss), `dnf` |
+| `get_match_players(club_id, match_type="leagueMatch", count=10, both_teams=False)` | player per match: rating, goals, assists, shots, passes, tackles |
+| `get_playoff_achievements(club_id)` | achievement (EA has only returned an empty list so far) |
+| `get_json(endpoint, params)` | EA's raw response as dicts/lists, e.g. `api.get_json("clubs/info", {"clubIds": 1001})` |
+
+- `match_type` is `"leagueMatch"`, `"friendlyMatch"` or `"playoffMatch"`.
+- By default, tables have a short set of readable columns. Add `all_columns=True` to
+  `search_club_by_name`, `get_club_details`, `get_club_overall_stats`,
+  `get_member_stats` or `get_match_players` to get every field EA sends, with EA's names.
+- `FC27API(platform="common-gen5", timeout=10, timezone="UTC")`: all settings are optional.
+- If there is no data, you get an empty table (`df.empty` is `True`).
+
+## Recipes
+
+```python
+from fc_clubs_api import FC27API
+
+api = FC27API(timezone="Europe/Istanbul")
+club_id = api.find_club_id("Your Club Name")
+
+# Top 5 scorers this season
+members = api.get_member_stats(club_id)
+print(members.sort_values("goals", ascending=False).head(5)[["name", "goals", "assists"]])
+
+# Last 5 league results
+matches = api.get_club_matches(club_id)
+print(matches.head(5)[["timestamp", "opponentName", "goals", "goalsAgainst", "result"]])
+
+# Win rate over the last 10 league matches
+wins = (matches["result"] == "win").sum()
+print(f"Won {wins} of {len(matches)}")
+
+# One player's recent matches
+players = api.get_match_players(club_id)
+print(players[players["name"] == "YourGamertag"][["timestamp", "rating", "goals", "assists"]])
+
+# Average match rating per player, best first
+print(players.groupby("name")["rating"].mean().sort_values(ascending=False))
+
+# Save any table to open in Excel
+members.to_csv("members.csv", index=False)
+# members.to_excel("members.xlsx", index=False)   # needs: pip install openpyxl
+```
+
+## Errors
+
+- **`FC27APIError`**: EA couldn't be reached, refused the request, or didn't send JSON.
+- **`ValueError`**: you passed something invalid, such as an unknown `match_type`, or a
+  club name that `find_club_id` couldn't match to one club.
+
+```python
+from fc_clubs_api import FC27API, FC27APIError
+
+try:
+    df = FC27API().get_club_details(1001)
+except FC27APIError as error:
+    print("EA problem:", error)
+```
+
+## Good to know
+
+- **EA blocks non-browser requests.** Every request sends browser-like headers
+  (`HEADERS` in `fc_clubs_api.py`). Without them EA answers 403 or doesn't answer at all.
+  Plain `curl` is blocked even with the headers, while Python works.
+- **No caching or rate limiting.** Every call goes straight to EA. If you loop over
+  many clubs, add a pause between requests (`time.sleep(1)`) so you don't get blocked.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+The tests run offline, using EA responses saved in `tests/fixtures/`. They keep the real structure,
+but every club and player name, id and date is a placeholder.
+
+## Contributing
+
+Bug reports are welcome, especially when EA changes something and the client
+breaks. Please open an issue before writing code: the project is deliberately
+small and some things that look like oversights are decisions. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT, see [LICENSE.md](LICENSE.md).

fc_clubs_api-0.1.0/fc_clubs_api.egg-info/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: fc-clubs-api
+Version: 0.1.0
+Summary: Unofficial Python client for the EA Sports FC 27 Pro Clubs API, returning pandas DataFrames.
+Author: Erkan Dogan
+License: MIT License
+        
+        Copyright (c) 2025 Erkan Dogan
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/1erkandogan/fc27-clubs-api
+Project-URL: Issues, https://github.com/1erkandogan/fc27-clubs-api/issues
+Keywords: ea,fc27,pro clubs,api,pandas
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pandas>=1.5
+Dynamic: license-file
+
+# FC 27 Clubs API
+
+An unofficial Python client for the **EA Sports FC 27 Pro Clubs API**, the same
+endpoints `proclubs.ea.com` calls from the browser. You can find clubs and get
+their stats, members, matches and per-player match ratings as tables (pandas
+DataFrames).
+
+Not affiliated with or endorsed by EA. The endpoints are undocumented and can
+change without notice.
+
+- **New to Python, or want to know how it works?** Read [docs/how-it-works.md](docs/how-it-works.md).
+  It walks through the code and explains every import and decision.
+- **Want EA's raw responses?** See [docs/endpoints.md](docs/endpoints.md).
+
+## Install
+
+You need Python 3.9 or newer.
+
+```bash
+pip install fc-clubs-api   # also installs pandas, the only dependency
+```
+
+No API key needed. The whole client is one file, [`fc_clubs_api.py`](fc_clubs_api.py),
+and you import it as `fc_clubs_api`.
+
+To work on the code itself, install from a clone instead:
+
+```bash
+git clone https://github.com/1erkandogan/fc27-clubs-api.git
+cd fc27-clubs-api
+pip install -e .   # your edits to fc_clubs_api.py take effect without reinstalling
+```
+
+## Quick start
+
+```python
+from fc_clubs_api import FC27API
+
+api = FC27API(timezone="Europe/Istanbul")      # match times in your timezone
+
+club_id = api.find_club_id("Your Club Name")   # -> the id, e.g. 1001
+
+print(api.get_club_matches(club_id))           # last 10 league matches
+print(api.get_member_stats(club_id))           # squad stats this season
+```
+
+Or run the example: `python examples/quickstart.py "Your Club Name"`
+
+## Methods
+
+| Method | Gives you (one row per ...) |
+|---|---|
+| `find_club_id(name)` | the club's id as a number. If several clubs match, the error lists them. |
+| `search_club_by_name(name)` | club matching the name: division, wins, goals, points |
+| `get_club_details(club_id)` | club (1 row): name, ids, stadium |
+| `get_club_overall_stats(club_id)` | club (1 row): record, goals, streaks, skill rating |
+| `get_member_stats(club_id)` | member: games, goals, assists, average rating, pass/tackle rates |
+| `get_member_career_stats(club_id)` | member: career totals at the club |
+| `get_club_matches(club_id, match_type="leagueMatch", count=10)` | match, from your side: opponent, score, `result` (win/draw/loss), `dnf` |
+| `get_match_players(club_id, match_type="leagueMatch", count=10, both_teams=False)` | player per match: rating, goals, assists, shots, passes, tackles |
+| `get_playoff_achievements(club_id)` | achievement (EA has only returned an empty list so far) |
+| `get_json(endpoint, params)` | EA's raw response as dicts/lists, e.g. `api.get_json("clubs/info", {"clubIds": 1001})` |
+
+- `match_type` is `"leagueMatch"`, `"friendlyMatch"` or `"playoffMatch"`.
+- By default, tables have a short set of readable columns. Add `all_columns=True` to
+  `search_club_by_name`, `get_club_details`, `get_club_overall_stats`,
+  `get_member_stats` or `get_match_players` to get every field EA sends, with EA's names.
+- `FC27API(platform="common-gen5", timeout=10, timezone="UTC")`: all settings are optional.
+- If there is no data, you get an empty table (`df.empty` is `True`).
+
+## Recipes
+
+```python
+from fc_clubs_api import FC27API
+
+api = FC27API(timezone="Europe/Istanbul")
+club_id = api.find_club_id("Your Club Name")
+
+# Top 5 scorers this season
+members = api.get_member_stats(club_id)
+print(members.sort_values("goals", ascending=False).head(5)[["name", "goals", "assists"]])
+
+# Last 5 league results
+matches = api.get_club_matches(club_id)
+print(matches.head(5)[["timestamp", "opponentName", "goals", "goalsAgainst", "result"]])
+
+# Win rate over the last 10 league matches
+wins = (matches["result"] == "win").sum()
+print(f"Won {wins} of {len(matches)}")
+
+# One player's recent matches
+players = api.get_match_players(club_id)
+print(players[players["name"] == "YourGamertag"][["timestamp", "rating", "goals", "assists"]])
+
+# Average match rating per player, best first
+print(players.groupby("name")["rating"].mean().sort_values(ascending=False))
+
+# Save any table to open in Excel
+members.to_csv("members.csv", index=False)
+# members.to_excel("members.xlsx", index=False)   # needs: pip install openpyxl
+```
+
+## Errors
+
+- **`FC27APIError`**: EA couldn't be reached, refused the request, or didn't send JSON.
+- **`ValueError`**: you passed something invalid, such as an unknown `match_type`, or a
+  club name that `find_club_id` couldn't match to one club.
+
+```python
+from fc_clubs_api import FC27API, FC27APIError
+
+try:
+    df = FC27API().get_club_details(1001)
+except FC27APIError as error:
+    print("EA problem:", error)
+```
+
+## Good to know
+
+- **EA blocks non-browser requests.** Every request sends browser-like headers
+  (`HEADERS` in `fc_clubs_api.py`). Without them EA answers 403 or doesn't answer at all.
+  Plain `curl` is blocked even with the headers, while Python works.
+- **No caching or rate limiting.** Every call goes straight to EA. If you loop over
+  many clubs, add a pause between requests (`time.sleep(1)`) so you don't get blocked.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+The tests run offline, using EA responses saved in `tests/fixtures/`. They keep the real structure,
+but every club and player name, id and date is a placeholder.
+
+## Contributing
+
+Bug reports are welcome, especially when EA changes something and the client
+breaks. Please open an issue before writing code: the project is deliberately
+small and some things that look like oversights are decisions. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT, see [LICENSE.md](LICENSE.md).

fc_clubs_api-0.1.0/fc_clubs_api.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE.md
+README.md
+fc_clubs_api.py
+pyproject.toml
+fc_clubs_api.egg-info/PKG-INFO
+fc_clubs_api.egg-info/SOURCES.txt
+fc_clubs_api.egg-info/dependency_links.txt
+fc_clubs_api.egg-info/requires.txt
+fc_clubs_api.egg-info/top_level.txt
+tests/test_fc_clubs_api.py

fc_clubs_api-0.1.0/fc_clubs_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fc_clubs_api-0.1.0/fc_clubs_api.egg-info/requires.txt

@@ -0,0 +1 @@
+pandas>=1.5

fc_clubs_api-0.1.0/fc_clubs_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+fc_clubs_api

fc_clubs_api-0.1.0/fc_clubs_api.py

@@ -0,0 +1,370 @@
+"""Unofficial client for the EA Sports FC 27 Pro Clubs API.
+
+Every method returns a pandas DataFrame (a table). New to this code? Read
+docs/how-it-works.md, which walks through this file step by step.
+Raw response formats are in docs/endpoints.md.
+"""
+
+# Built into Python, no install needed:
+import json             # turns the text EA sends back into Python dicts and lists
+import urllib.error     # the errors urllib raises (e.g. EA answering 403)
+import urllib.parse     # builds the "?platform=...&clubIds=..." part of a URL
+import urllib.request   # sends the request to EA
+
+# The only thing you need to install (pip install pandas). It gives us tables
+# (DataFrames) that are easy to sort, filter, average and save to Excel/CSV.
+import pandas as pd
+
+
+__version__ = "0.1.0"   # keep in sync with "version" in pyproject.toml
+
+BASE_URL = "https://proclubs.ea.com/api/fc"
+
+MATCH_TYPES = ("leagueMatch", "friendlyMatch", "playoffMatch")
+
+# EA's servers sit behind Akamai, which blocks requests that don't look like
+# they come from the proclubs.ea.com website itself: without these headers you
+# get a 403 error or no answer at all. "sec-fetch-site: same-origin" is the key one.
+HEADERS = {
+    "accept": "application/json",
+    "accept-language": "en-US,en;q=0.9",
+    "sec-ch-ua": '"Google Chrome";v="141", "Not?A_Brand";v="8", "Chromium";v="141"',
+    "sec-fetch-site": "same-origin",
+    "user-agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+        "(KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36"
+    ),
+}
+
+# EA returns a lot of columns with inconsistent names (passesmade, ratingAve,
+# mom, ...). By default each method keeps only the useful ones and renames them.
+# Format: "EA's name": "our name". Pass all_columns=True to get everything as-is.
+COLUMNS = {
+    "search": {
+        "clubId": "clubId",
+        "clubName": "clubName",
+        "currentDivision": "currentDivision",
+        "bestDivision": "bestDivision",
+        "gamesPlayed": "gamesPlayed",
+        "wins": "wins",
+        "ties": "ties",
+        "losses": "losses",
+        "goals": "goals",
+        "goalsAgainst": "goalsAgainst",
+        "cleanSheets": "cleanSheets",
+        "points": "points",
+    },
+    "details": {
+        "clubId": "clubId",
+        "name": "clubName",
+        "regionId": "regionId",
+        "teamId": "teamId",
+        "customKit.stadName": "stadium",
+    },
+    "overall": {
+        "clubId": "clubId",
+        "gamesPlayed": "gamesPlayed",
+        "wins": "wins",
+        "ties": "ties",
+        "losses": "losses",
+        "goals": "goals",
+        "goalsAgainst": "goalsAgainst",
+        "skillRating": "skillRating",
+        "wstreak": "winStreak",
+        "unbeatenstreak": "unbeatenStreak",
+        "promotions": "promotions",
+        "relegations": "relegations",
+        "bestDivision": "bestDivision",
+    },
+    "members": {
+        "name": "name",
+        "proName": "playerName",
+        "favoritePosition": "position",
+        "proOverall": "overall",
+        "gamesPlayed": "gamesPlayed",
+        "winRate": "winRate",
+        "goals": "goals",
+        "assists": "assists",
+        "ratingAve": "averageRating",
+        "manOfTheMatch": "manOfTheMatch",
+        "shotSuccessRate": "shotSuccessRate",
+        "passesMade": "passesMade",
+        "passSuccessRate": "passSuccessRate",
+        "tacklesMade": "tacklesMade",
+        "tackleSuccessRate": "tackleSuccessRate",
+        "cleanSheetsDef": "cleanSheetsDef",
+        "cleanSheetsGK": "cleanSheetsGK",
+        "redCards": "redCards",
+    },
+    "players": {
+        "matchId": "matchId",
+        "timestamp": "timestamp",
+        "clubId": "clubId",
+        "playername": "name",
+        "pos": "position",
+        "rating": "rating",
+        "goals": "goals",
+        "assists": "assists",
+        "shots": "shots",
+        "passesmade": "passesMade",
+        "passattempts": "passAttempts",
+        "tacklesmade": "tacklesMade",
+        "tackleattempts": "tackleAttempts",
+        "saves": "saves",
+        "cleansheetsany": "cleanSheet",
+        "mom": "manOfTheMatch",
+        "redcards": "redCards",
+        "secondsPlayed": "secondsPlayed",
+    },
+}
+
+
+class FC27APIError(Exception):
+    """Raised when EA can't be reached, refuses the request, or doesn't send JSON."""
+
+
+def to_dataframe(records):
+    """Turn a list of dicts from EA into a DataFrame.
+
+    Two fixes happen here:
+    1. Nested dicts become their own columns (json_normalize), e.g.
+       {"clubInfo": {"name": "X"}} becomes a column called "clubInfo.name".
+    2. EA sends numbers as text ("25", "7.4"). Text can't be summed or sorted
+       numerically, so every column that is fully numeric is converted.
+    """
+    if not records:
+        return pd.DataFrame()
+
+    df = pd.json_normalize(records)
+    for column in df.columns:
+        try:
+            df[column] = pd.to_numeric(df[column])
+        except (ValueError, TypeError):
+            pass  # a text column such as a name: leave it as text
+    return df
+
+
+def pick_columns(df, columns, all_columns):
+    """Keep only the columns listed in `columns` and give them friendly names."""
+    if all_columns:
+        return df
+
+    keep = []
+    for ea_name in columns:
+        if ea_name in df.columns:
+            keep.append(ea_name)
+    return df[keep].rename(columns=columns)
+
+
+class FC27API:
+    """Talks to EA's Pro Clubs API.
+
+    platform: "common-gen5" (PS5 / Xbox Series / PC). The only one tested.
+    timeout:  seconds to wait for EA before giving up.
+    timezone: timezone for match times, e.g. "Europe/Istanbul". Default "UTC".
+    """
+
+    def __init__(self, platform="common-gen5", timeout=10, timezone="UTC"):
+        self.platform = platform
+        self.timeout = timeout
+        self.timezone = timezone
+
+    # ------------------------------------------------------------------ basics
+
+    def get_json(self, endpoint, params):
+        """Ask EA for `endpoint` and return the answer as Python dicts/lists.
+
+        Use this if you want EA's raw, untouched response, for example
+        api.get_json("clubs/info", {"clubIds": 1001})
+        """
+        query = {"platform": self.platform}
+        query.update(params)
+        url = BASE_URL + "/" + endpoint + "?" + urllib.parse.urlencode(query)
+        request = urllib.request.Request(url, headers=HEADERS)
+
+        # `from None` keeps the error message short: our message already says
+        # what went wrong, so Python's internal error chain isn't shown.
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                data = json.load(response)
+        except urllib.error.HTTPError as error:
+            raise FC27APIError(f"EA answered with error {error.code} for {url}") from None
+        except OSError as error:  # no internet, timeout, DNS problem, ...
+            raise FC27APIError(f"Could not reach EA ({error}) for {url}") from None
+        except json.JSONDecodeError:
+            raise FC27APIError(f"EA did not send JSON for {url}") from None
+
+        # EA sometimes answers "null" instead of an empty list.
+        if data is None:
+            return []
+        return data
+
+    def _convert_times(self, df):
+        """EA gives times as Unix seconds (1767297600); make them readable dates."""
+        if not df.empty:
+            utc_times = pd.to_datetime(df["timestamp"], unit="s", utc=True)
+            df["timestamp"] = utc_times.dt.tz_convert(self.timezone)
+        return df
+
+    # ------------------------------------------------------------------- clubs
+
+    def search_club_by_name(self, club_name, all_columns=False):
+        """All clubs whose name contains `club_name`, one row per club."""
+        results = self.get_json("allTimeLeaderboard/search", {"clubName": club_name})
+        return pick_columns(to_dataframe(results), COLUMNS["search"], all_columns)
+
+    def find_club_id(self, club_name):
+        """Return the id (a number) of the club called `club_name`.
+
+        Uses the club with exactly that name (ignoring upper/lower case), or the
+        only search result. If it can't decide, the error lists the options.
+        """
+        results = self.get_json("allTimeLeaderboard/search", {"clubName": club_name})
+        if len(results) == 0:
+            raise ValueError(f"No club found for {club_name!r}")
+
+        for club in results:
+            if club["clubName"].lower() == club_name.lower():
+                return int(club["clubId"])
+
+        if len(results) == 1:
+            return int(results[0]["clubId"])
+
+        options = []
+        for club in results:
+            options.append(f"{club['clubName']} (id {club['clubId']})")
+        raise ValueError(
+            f"{len(results)} clubs match {club_name!r}: {', '.join(options)}. "
+            "Use the exact club name, or use the id directly."
+        )
+
+    def get_club_details(self, club_id, all_columns=False):
+        """One row: club name, ids and stadium (all_columns adds kit details)."""
+        data = self.get_json("clubs/info", {"clubIds": club_id})
+        # EA answers {"1001": {...club...}}; we only need the {...club...} part.
+        clubs = list(data.values())
+        return pick_columns(to_dataframe(clubs), COLUMNS["details"], all_columns)
+
+    def get_club_overall_stats(self, club_id, all_columns=False):
+        """One row: wins/draws/losses, goals, streaks, skill rating."""
+        data = self.get_json("clubs/overallStats", {"clubIds": club_id})
+        return pick_columns(to_dataframe(data), COLUMNS["overall"], all_columns)
+
+    def get_playoff_achievements(self, club_id):
+        """Playoff achievements (EA has only returned an empty list so far)."""
+        return to_dataframe(self.get_json("club/playoffAchievements", {"clubId": club_id}))
+
+    # ----------------------------------------------------------------- members
+
+    def get_member_stats(self, club_id, all_columns=False):
+        """One row per club member with their stats for the current season."""
+        data = self.get_json("members/stats", {"clubId": club_id})
+        members = data.get("members", [])
+        return pick_columns(to_dataframe(members), COLUMNS["members"], all_columns)
+
+    def get_member_career_stats(self, club_id):
+        """One row per club member with their career totals at this club."""
+        data = self.get_json("members/career/stats", {"clubId": club_id})
+        return to_dataframe(data.get("members", []))
+
+    # ----------------------------------------------------------------- matches
+
+    def _get_matches(self, club_id, match_type, count):
+        if match_type not in MATCH_TYPES:
+            raise ValueError(f"match_type must be one of {MATCH_TYPES}, not {match_type!r}")
+        params = {"clubIds": club_id, "matchType": match_type, "maxResultCount": count}
+        return self.get_json("clubs/matches", params)
+
+    def get_club_matches(self, club_id, match_type="leagueMatch", count=10):
+        """One row per match, seen from `club_id`'s side, newest first.
+
+        match_type: "leagueMatch", "friendlyMatch" or "playoffMatch".
+        count:      how many recent matches to ask EA for.
+        """
+        # EA uses the club id as a text key ("1001"), so compare as text.
+        club_id = str(club_id)
+        rows = []
+
+        for match in self._get_matches(club_id, match_type, count):
+            clubs = match.get("clubs", {})
+            us = clubs.get(club_id, {})
+
+            # The other key in `clubs` is the opponent.
+            opponent_id = None
+            them = {}
+            for other_id in clubs:
+                if other_id != club_id:
+                    opponent_id = other_id
+                    them = clubs[other_id]
+
+            goals = int(us.get("goals", 0))
+            goals_against = int(us.get("goalsAgainst", 0))
+
+            # League matches say who won in wins/ties/losses. Friendlies leave
+            # those at "0", so there we compare the goals instead.
+            if us.get("wins") == "1":
+                result = "win"
+            elif us.get("losses") == "1":
+                result = "loss"
+            elif us.get("ties") == "1":
+                result = "draw"
+            elif goals > goals_against:
+                result = "win"
+            elif goals < goals_against:
+                result = "loss"
+            else:
+                result = "draw"
+
+            rows.append({
+                "matchId": match.get("matchId"),
+                "timestamp": match.get("timestamp"),
+                "matchType": match_type,
+                "clubId": club_id,
+                "clubName": us.get("details", {}).get("name"),
+                "opponentId": opponent_id,
+                "opponentName": them.get("details", {}).get("name"),
+                "goals": goals,
+                "goalsAgainst": goals_against,
+                "result": result,
+                # DNF = "did not finish": someone quit and the other team got the win.
+                "dnf": us.get("winnerByDnf") == "1" or them.get("winnerByDnf") == "1",
+            })
+
+        return self._convert_times(to_dataframe(rows))
+
+    def get_match_players(self, club_id, match_type="leagueMatch", count=10,
+                          both_teams=False, all_columns=False):
+        """One row per player per match: rating, goals, assists, passes, ...
+
+        By default only `club_id`'s players are included; both_teams=True adds
+        the opponents' players too (tell them apart with the clubId column).
+        """
+        club_id = str(club_id)
+        rows = []
+
+        for match in self._get_matches(club_id, match_type, count):
+            # match["players"] looks like {"1001": {"<playerId>": {...stats...}}}
+            for player_club, players in match.get("players", {}).items():
+                if player_club != club_id and not both_teams:
+                    continue  # skip the opponent's players
+                for player_id, stats in players.items():
+                    row = {
+                        "matchId": match.get("matchId"),
+                        "timestamp": match.get("timestamp"),
+                        "clubId": player_club,
+                        "playerId": player_id,
+                    }
+                    row.update(stats)  # add all of EA's stat fields to the row
+                    rows.append(row)
+
+        df = self._convert_times(to_dataframe(rows))
+        return pick_columns(df, COLUMNS["players"], all_columns)
+
+
+# This only runs when you start this file directly (python fc_clubs_api.py),
+# not when another script does `from fc_clubs_api import FC27API`.
+if __name__ == "__main__":
+    api = FC27API()
+    club_id = api.find_club_id(input("Club name: "))
+    print(api.get_club_matches(club_id))
+    print(api.get_member_stats(club_id))

fc_clubs_api-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fc-clubs-api"
+version = "0.1.0"
+description = "Unofficial Python client for the EA Sports FC 27 Pro Clubs API, returning pandas DataFrames."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE.md" }
+authors = [{ name = "Erkan Dogan" }]
+dependencies = ["pandas>=1.5"]
+keywords = ["ea", "fc27", "pro clubs", "api", "pandas"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/1erkandogan/fc27-clubs-api"
+Issues = "https://github.com/1erkandogan/fc27-clubs-api/issues"
+
+[tool.setuptools]
+py-modules = ["fc_clubs_api"]

fc_clubs_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fc_clubs_api-0.1.0/tests/test_fc_clubs_api.py

@@ -0,0 +1,168 @@
+"""Offline tests: run with  python -m unittest discover -s tests -v
+
+These tests never contact EA. `unittest.mock.patch` temporarily replaces
+urllib.request.urlopen (the function that sends the request) with a fake that
+returns a saved response from tests/fixtures/. This keeps the tests fast and
+repeatable, and they don't break when EA's live data changes.
+
+The fixtures have the exact shape of real EA responses, but every club, player,
+id, date and kit value is a placeholder: Example FC = 1001, Opponent A = 2001,
+Player1, Player2, ...
+"""
+
+import io
+import json
+import unittest
+import urllib.error
+import urllib.parse
+from pathlib import Path
+from unittest.mock import patch
+
+from fc_clubs_api import FC27API, FC27APIError
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def fixture(name):
+    return json.loads((FIXTURES / f"{name}.json").read_text(encoding="utf-8"))
+
+
+def fake_ea(payload):
+    """Pretend EA answers every request with `payload` (as JSON text)."""
+    body = json.dumps(payload).encode("utf-8")
+    # side_effect builds a fresh response for every call, like a real server.
+    return patch("urllib.request.urlopen", side_effect=lambda *args, **kwargs: io.BytesIO(body))
+
+
+def sent_params(fake):
+    """The query parameters of the last request our code sent."""
+    request = fake.call_args[0][0]
+    query = urllib.parse.urlparse(request.full_url).query
+    return dict(urllib.parse.parse_qsl(query))
+
+
+class ClubTests(unittest.TestCase):
+    def test_search_returns_all_results_with_short_columns(self):
+        with fake_ea(fixture("search")) as fake:
+            df = FC27API().search_club_by_name("example")
+
+        self.assertEqual(len(df), 2)
+        self.assertEqual(df["clubName"].iat[0], "Example FC")
+        self.assertEqual(df["wins"].iat[0], 20)  # "20" (text) became 20 (number)
+        self.assertNotIn("clubInfo.customKit.kitId", df.columns)
+        self.assertEqual(sent_params(fake), {"platform": "common-gen5", "clubName": "example"})
+
+    def test_all_columns_keeps_ea_names(self):
+        with fake_ea(fixture("search")):
+            df = FC27API().search_club_by_name("example", all_columns=True)
+        self.assertIn("clubInfo.customKit.kitId", df.columns)
+
+    def test_club_details_is_one_row(self):
+        with fake_ea(fixture("info")):
+            df = FC27API().get_club_details(1001)
+
+        self.assertEqual(len(df), 1)
+        self.assertEqual(df["clubName"].iat[0], "Example FC")
+        self.assertEqual(df["stadium"].iat[0], "Example Stadium")
+
+    def test_overall_stats_keeps_nulls(self):
+        with fake_ea(fixture("overall")):
+            df = FC27API().get_club_overall_stats(1001)
+
+        self.assertEqual(df["skillRating"].iat[0], 1500)
+        self.assertEqual(df["winStreak"].iat[0], 3)
+        self.assertTrue(df["bestDivision"].isna().iat[0])
+
+    def test_members(self):
+        with fake_ea(fixture("members")):
+            df = FC27API().get_member_stats(1001)
+        self.assertEqual(len(df), 2)
+        self.assertEqual(df["averageRating"].iat[0], 7.4)
+
+        with fake_ea(fixture("career")):
+            self.assertEqual(len(FC27API().get_member_career_stats(1001)), 2)
+
+
+class FindClubIdTests(unittest.TestCase):
+    def test_exact_name_ignoring_case(self):
+        with fake_ea(fixture("search")):
+            self.assertEqual(FC27API().find_club_id("example fc"), 1001)
+
+    def test_single_result(self):
+        with fake_ea(fixture("search")[1:]):
+            self.assertEqual(FC27API().find_club_id("example"), 1002)
+
+    def test_ambiguous_lists_options(self):
+        with fake_ea(fixture("search")):
+            with self.assertRaises(ValueError) as caught:
+                FC27API().find_club_id("example")
+        self.assertIn("Example FC (id 1001)", str(caught.exception))
+
+    def test_no_result(self):
+        with fake_ea([]):
+            with self.assertRaises(ValueError):
+                FC27API().find_club_id("nothing")
+
+
+class MatchTests(unittest.TestCase):
+    def test_matches_from_club_side(self):
+        with fake_ea(fixture("matches")) as fake:
+            df = FC27API().get_club_matches(1001)
+
+        # 1: league win (opponent quit), 2: league draw, 3: friendly lost 0-3
+        self.assertEqual(list(df["result"]), ["win", "draw", "loss"])
+        self.assertEqual(list(df["dnf"]), [True, False, False])
+        self.assertEqual(df["opponentId"].iat[0], 2001)
+        self.assertEqual(df["goalsAgainst"].iat[2], 3)
+        self.assertEqual(str(df["timestamp"].dt.tz), "UTC")
+        self.assertEqual(sent_params(fake)["maxResultCount"], "10")
+
+    def test_timezone(self):
+        with fake_ea(fixture("matches")):
+            df = FC27API(timezone="Europe/Istanbul").get_club_matches(1001)
+        # 20:00 UTC is 23:00 in Istanbul (UTC+3)
+        self.assertEqual(df["timestamp"].iat[0].hour, 23)
+
+    def test_match_players_own_team_by_default(self):
+        with fake_ea(fixture("matches")):
+            df = FC27API().get_match_players(1001)
+        self.assertEqual(len(df), 3 * 2)  # 3 matches x 2 players (fixtures are trimmed)
+        self.assertEqual(set(df["clubId"]), {1001})
+        self.assertIn("passesMade", df.columns)
+
+    def test_match_players_both_teams(self):
+        with fake_ea(fixture("matches")):
+            df = FC27API().get_match_players(1001, both_teams=True)
+        self.assertEqual(len(df), 3 * 2 * 2)
+
+    def test_empty_and_null_matches(self):
+        for payload in ([], None):
+            with fake_ea(payload):
+                self.assertTrue(FC27API().get_club_matches(1001, "playoffMatch").empty)
+                self.assertTrue(FC27API().get_match_players(1001, "playoffMatch").empty)
+
+    def test_bad_match_type(self):
+        with self.assertRaises(ValueError):
+            FC27API().get_club_matches(1001, "cupMatch")
+
+
+class ErrorTests(unittest.TestCase):
+    def test_http_error(self):
+        error = urllib.error.HTTPError("url", 403, "Forbidden", {}, None)
+        with patch("urllib.request.urlopen", side_effect=error):
+            with self.assertRaises(FC27APIError):
+                FC27API().get_club_details(1001)
+
+    def test_timeout(self):
+        with patch("urllib.request.urlopen", side_effect=TimeoutError("timed out")):
+            with self.assertRaises(FC27APIError):
+                FC27API().get_club_details(1001)
+
+    def test_not_json(self):
+        with patch("urllib.request.urlopen", return_value=io.BytesIO(b"<html>blocked</html>")):
+            with self.assertRaises(FC27APIError):
+                FC27API().get_club_details(1001)
+
+
+if __name__ == "__main__":
+    unittest.main()