impectPy 2.4.4__tar.gz → 2.5.1__tar.gz

{impectPy-2.4.4 → impectPy-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: impectPy
-Version: 2.4.4
+Version: 2.5.1
 Summary: A Python package to facilitate interaction with the Impect customer API
 Home-page: https://github.com/ImpectAPI/impectPy
 Author: Impect
@@ -16,9 +16,9 @@ Requires-Dist: numpy<2.0,>=1.24.2
 
 A package provided by: Impect GmbH
 
-Version: v2.4.4
+Version: v2.5.1
 
-**Updated: June 5th 2025**
+**Updated: October 17th 2025**
 
 ---
 
@@ -40,11 +40,16 @@ match and season level.
 
 ## Installation
 
-You can install the latest version of impectPy from
-[GitHub](https://github.com/) with:
+You can install the latest version of impectPy from PyPi with:
 
-``` cmd
-pip install git+https://github.com/ImpectAPI/impectPy.git@v2.4.4
+```cmd
+pip install impectPy
+```
+
+You can also install it from [GitHub](https://github.com/) with:
+
+```cmd
+pip install git+https://github.com/ImpectAPI/impectPy.git@v2.5.1
 ```
 
 ## Usage
@@ -55,7 +60,7 @@ Before accessing any data via our API, you will need to request a bearer
 token for authorization. You can get this authorization token using the
 following code snippet:
 
-``` python
+```python
 import impectPy as ip
 import pandas as pd
 
@@ -73,7 +78,7 @@ competition iterations that are enabled for your account.
 
 ### Retrieve Basic Information
 
-``` python
+```python
 # get list of iterations
 iterations = ip.getIterations(token=token)
 
@@ -86,7 +91,7 @@ your sales representative. Now let’s assume you are interested in data
 for 2022/23 season of the 1. Bundesliga (iteration = 518). The following
 snippet gets you a list of matches for this iteration:
 
-``` python
+```python
 # get matches for iteration
 matchplan = ip.getMatches(iteration=518, token=token)
 
@@ -105,7 +110,7 @@ as team formation, starting position and substitution data. As the functions all
 for multiple games to be requested at once, we need to wrap the matchId into a list. 
 Hence, to request data for this game, run the following code snippet:
 
-``` python
+```python
 # define matches to get event data for
 matches = [84344]
 
@@ -134,7 +139,7 @@ Scouting and Analysis portals. On player level, these are calculated across
 positions which is why you have to supply the function with a list of positions 
 your want to retrieve data for:
 
-``` python
+```python
 # define matches to get further data for
 matches = [84344]
 
@@ -166,7 +171,7 @@ the following method to do so in order to minimize the amount of
 requests sent to the API. Let’s also get the event data for the RB
 Leipzig vs FSV Mainz 05 game (matchId = 84350) from the same day:
 
-``` python
+```python
 # define list of matches
 matches = [84344, 84350]
 
@@ -193,8 +198,8 @@ positions = ["LEFT_WINGBACK_DEFENDER", "RIGHT_WINGBACK_DEFENDER"]
 # get player scores and ratios for match and positions per player
 playerMatchScores = ip.getPlayerMatchScores(
     matches=matches,
-    positions=positions,
-    token=token
+    token=token,
+    positions=positions  # optional
 )
 
 # get squad scores and ratios for match per squad
@@ -215,7 +220,7 @@ your want to retrieve data for.
 Let's assume you were interested in wing backs in the 2022/2023 Bundesliga season, 
 then you could use this code snippet:
 
-``` python
+```python
 # define iteration ID
 iteration = 518
 
@@ -237,8 +242,8 @@ squadIterationAverages = ip.getSquadIterationAverages(
 # get player scores and ratios for iteration and positions
 playerIterationScores = ip.getPlayerIterationScores(
     iteration=iteration,
-    positions=positions,
-    token=token
+    token=token,
+    positions=positions  # optional
 )
 
 # get squad scores and ratios for iteration
@@ -246,9 +251,19 @@ squadIterationScores = ip.getSquadIterationScores(
     iteration=iteration,
     token=token
 )
+```
+
+The squad rating values that you can find on the league ranking in the Scouting portal can 
+also be retrieved from the API. In addition, we also provide you with the more detailed squad 
+coefficients that can be used to make match predictions. See [this example script](https://github.com/ImpectAPI/impectPy/blob/release/examples/predict_matches.ipynb) 
+for further details. 
 
+```python
 # get squad rating for iteration
-squadRatings = ip.getSquadRatings(iteration=iteration, token=token
+squadRatings = ip.getSquadRatings(iteration=iteration, token=token)
+
+# get squad coefficients for iteration
+squadCoefficients = ip.getSquadCoefficients(iteration=iteration, token=token)
 ```
 
 You can now also retrieve the positional profile scores for players via our API. This 
@@ -257,7 +272,7 @@ positional input that determines which matchShares to consider when computing th
 In the below example, all matchShares that a player played as either a left back or a right 
 back are included for profile score calculation.
 
-``` python
+```python
 # define iteration ID
 iteration = 518
 
@@ -265,7 +280,11 @@ iteration = 518
 positions = ["LEFT_WINGBACK_DEFENDER", "RIGHT_WINGBACK_DEFENDER"]
 
 # get player profile scores
-playerProfileScores = getPlayerProfileScores(iteration, positions, token)
+playerProfileScores = ip.getPlayerProfileScores(
+    iteration=iteration,
+    positions=positions,
+    token=token
+)
 ```
 
 Please keep in mind that Impect enforces a rate limit of 10 requests per second
@@ -292,7 +311,7 @@ please see the beginning of the [function definition](https://github.com/ImpectA
 Please make sure to only retrieve event data for
 one game at a time. Let's use the Bayern vs Dortmund game from earlier as an example:
 
-``` python
+```python
 # define matchId
 matches = [84344]
 
@@ -374,51 +393,56 @@ positions = ["LEFT_WINGBACK_DEFENDER", "RIGHT_WINGBACK_DEFENDER"]
 iterations = api.getIterations()
 
 # get squad ratings
-ratings = api.getSquadRatings(iteration)
+ratings = api.getSquadRatings(iteration=iteration)
+
+# get squad coefficients
+coefficients = api.getSquadCoefficients(iteration=iteration)
 
 # get matches
-matchplan = api.getMatches(iteration)
+matchplan = api.getMatches(iteration=iteration)
 
 # get match info
-formations = api.getFormations(matches)
-substitutions = api.getSubstitutions(matches)
-startingPositions = api.getStartingPositions(matches)
+formations = api.getFormations(matches=matches)
+substitutions = api.getSubstitutions(matches=matches)
+startingPositions = api.getStartingPositions(matches=matches)
 
 # get match events
-events = api.getEvents(matches, include_kpis=True, include_set_pieces=True)
+events = api.getEvents(matches=matches, include_kpis=False, include_set_pieces=False)
 
 # get set pieces
-setPieces = api.getSetPieces(matches)
+set_pieces = api.getSetPieces(matches=matches)
 
 # get player iteration averages
-playerIterationAverages = api.getPlayerIterationAverages(iteration)
+playerIterationAverages = api.getPlayerIterationAverages(iteration=iteration)
 
 # get player matchsums
-playerMatchsums = api.getPlayerMatchsums(matches)
+playerMatchsums = api.getPlayerMatchsums(matches=matches)
 
 # get squad iteration averages
-squadIterationAverages = api.getSquadIterationAverages(iteration)
+squadIterationAverages = api.getSquadIterationAverages(iteration=iteration)
 
 # get squad matchsums
-squadMatchsums = api.getSquadMatchsums(matches)
+squadMatchsums = api.getSquadMatchsums(matches=matches)
 
 # get player match scores
-playerMatchScores = api.getPlayerMatchScores(matches, positions)
+playerMatchScores = api.getPlayerMatchScores(matches=matches, positions=positions)  # specific positions
+playerMatchScoresAll = api.getPlayerMatchScores(matches=matches)  # all positions
 
 # get squad match scores
-squadMatchScores = api.getSquadMatchScores(matches)
+squadMatchScores = api.getSquadMatchScores(matches=matches)
 
 # get player iteration scores
-playerIterationScores = api.getPlayerIterationScores(iteration, positions)
+playerIterationScores = api.getPlayerIterationScores(iteration=iteration, positions=positions)  # specific positions
+playerIterationScoresAll = api.getPlayerIterationScores(iteration=iteration)  # all positions
 
 # get squad iteration scores
-squadIterationScores = api.getSquadIterationScores(iteration)
+squadIterationScores = api.getSquadIterationScores(iteration=iteration)
 
 # get player profile scores
-playerProfileScores = api.getPlayerProfileScores(iteration, positions)
+playerProfileScores = api.getPlayerProfileScores(iteration=iteration, positions=positions)
 ```
 
 ## Final Notes
 
 Further documentation on the data and explanations of variables can be
-found in our [glossary](https://glossary.impect.com/).
+found in our [Glossary](https://glossary.impect.com/).

{impectPy-2.4.4 → impectPy-2.5.1}/README.md

@@ -2,9 +2,9 @@
 
 A package provided by: Impect GmbH
 
-Version: v2.4.4
+Version: v2.5.1
 
-**Updated: June 5th 2025**
+**Updated: October 17th 2025**
 
 ---
 
@@ -26,11 +26,16 @@ match and season level.
 
 ## Installation
 
-You can install the latest version of impectPy from
-[GitHub](https://github.com/) with:
+You can install the latest version of impectPy from PyPi with:
 
-``` cmd
-pip install git+https://github.com/ImpectAPI/impectPy.git@v2.4.4
+```cmd
+pip install impectPy
+```
+
+You can also install it from [GitHub](https://github.com/) with:
+
+```cmd
+pip install git+https://github.com/ImpectAPI/impectPy.git@v2.5.1
 ```
 
 ## Usage
@@ -41,7 +46,7 @@ Before accessing any data via our API, you will need to request a bearer
 token for authorization. You can get this authorization token using the
 following code snippet:
 
-``` python
+```python
 import impectPy as ip
 import pandas as pd
 
@@ -59,7 +64,7 @@ competition iterations that are enabled for your account.
 
 ### Retrieve Basic Information
 
-``` python
+```python
 # get list of iterations
 iterations = ip.getIterations(token=token)
 
@@ -72,7 +77,7 @@ your sales representative. Now let’s assume you are interested in data
 for 2022/23 season of the 1. Bundesliga (iteration = 518). The following
 snippet gets you a list of matches for this iteration:
 
-``` python
+```python
 # get matches for iteration
 matchplan = ip.getMatches(iteration=518, token=token)
 
@@ -91,7 +96,7 @@ as team formation, starting position and substitution data. As the functions all
 for multiple games to be requested at once, we need to wrap the matchId into a list. 
 Hence, to request data for this game, run the following code snippet:
 
-``` python
+```python
 # define matches to get event data for
 matches = [84344]
 
@@ -120,7 +125,7 @@ Scouting and Analysis portals. On player level, these are calculated across
 positions which is why you have to supply the function with a list of positions 
 your want to retrieve data for:
 
-``` python
+```python
 # define matches to get further data for
 matches = [84344]
 
@@ -152,7 +157,7 @@ the following method to do so in order to minimize the amount of
 requests sent to the API. Let’s also get the event data for the RB
 Leipzig vs FSV Mainz 05 game (matchId = 84350) from the same day:
 
-``` python
+```python
 # define list of matches
 matches = [84344, 84350]
 
@@ -179,8 +184,8 @@ positions = ["LEFT_WINGBACK_DEFENDER", "RIGHT_WINGBACK_DEFENDER"]
 # get player scores and ratios for match and positions per player
 playerMatchScores = ip.getPlayerMatchScores(
     matches=matches,
-    positions=positions,
-    token=token
+    token=token,
+    positions=positions  # optional
 )
 
 # get squad scores and ratios for match per squad
@@ -201,7 +206,7 @@ your want to retrieve data for.
 Let's assume you were interested in wing backs in the 2022/2023 Bundesliga season, 
 then you could use this code snippet:
 
-``` python
+```python
 # define iteration ID
 iteration = 518
 
@@ -223,8 +228,8 @@ squadIterationAverages = ip.getSquadIterationAverages(
 # get player scores and ratios for iteration and positions
 playerIterationScores = ip.getPlayerIterationScores(
     iteration=iteration,
-    positions=positions,
-    token=token
+    token=token,
+    positions=positions  # optional
 )
 
 # get squad scores and ratios for iteration
@@ -232,9 +237,19 @@ squadIterationScores = ip.getSquadIterationScores(
     iteration=iteration,
     token=token
 )
+```
+
+The squad rating values that you can find on the league ranking in the Scouting portal can 
+also be retrieved from the API. In addition, we also provide you with the more detailed squad 
+coefficients that can be used to make match predictions. See [this example script](https://github.com/ImpectAPI/impectPy/blob/release/examples/predict_matches.ipynb) 
+for further details. 
 
+```python
 # get squad rating for iteration
-squadRatings = ip.getSquadRatings(iteration=iteration, token=token
+squadRatings = ip.getSquadRatings(iteration=iteration, token=token)
+
+# get squad coefficients for iteration
+squadCoefficients = ip.getSquadCoefficients(iteration=iteration, token=token)
 ```
 
 You can now also retrieve the positional profile scores for players via our API. This 
@@ -243,7 +258,7 @@ positional input that determines which matchShares to consider when computing th
 In the below example, all matchShares that a player played as either a left back or a right 
 back are included for profile score calculation.
 
-``` python
+```python
 # define iteration ID
 iteration = 518
 
@@ -251,7 +266,11 @@ iteration = 518
 positions = ["LEFT_WINGBACK_DEFENDER", "RIGHT_WINGBACK_DEFENDER"]
 
 # get player profile scores
-playerProfileScores = getPlayerProfileScores(iteration, positions, token)
+playerProfileScores = ip.getPlayerProfileScores(
+    iteration=iteration,
+    positions=positions,
+    token=token
+)
 ```
 
 Please keep in mind that Impect enforces a rate limit of 10 requests per second
@@ -278,7 +297,7 @@ please see the beginning of the [function definition](https://github.com/ImpectA
 Please make sure to only retrieve event data for
 one game at a time. Let's use the Bayern vs Dortmund game from earlier as an example:
 
-``` python
+```python
 # define matchId
 matches = [84344]
 
@@ -360,51 +379,56 @@ positions = ["LEFT_WINGBACK_DEFENDER", "RIGHT_WINGBACK_DEFENDER"]
 iterations = api.getIterations()
 
 # get squad ratings
-ratings = api.getSquadRatings(iteration)
+ratings = api.getSquadRatings(iteration=iteration)
+
+# get squad coefficients
+coefficients = api.getSquadCoefficients(iteration=iteration)
 
 # get matches
-matchplan = api.getMatches(iteration)
+matchplan = api.getMatches(iteration=iteration)
 
 # get match info
-formations = api.getFormations(matches)
-substitutions = api.getSubstitutions(matches)
-startingPositions = api.getStartingPositions(matches)
+formations = api.getFormations(matches=matches)
+substitutions = api.getSubstitutions(matches=matches)
+startingPositions = api.getStartingPositions(matches=matches)
 
 # get match events
-events = api.getEvents(matches, include_kpis=True, include_set_pieces=True)
+events = api.getEvents(matches=matches, include_kpis=False, include_set_pieces=False)
 
 # get set pieces
-setPieces = api.getSetPieces(matches)
+set_pieces = api.getSetPieces(matches=matches)
 
 # get player iteration averages
-playerIterationAverages = api.getPlayerIterationAverages(iteration)
+playerIterationAverages = api.getPlayerIterationAverages(iteration=iteration)
 
 # get player matchsums
-playerMatchsums = api.getPlayerMatchsums(matches)
+playerMatchsums = api.getPlayerMatchsums(matches=matches)
 
 # get squad iteration averages
-squadIterationAverages = api.getSquadIterationAverages(iteration)
+squadIterationAverages = api.getSquadIterationAverages(iteration=iteration)
 
 # get squad matchsums
-squadMatchsums = api.getSquadMatchsums(matches)
+squadMatchsums = api.getSquadMatchsums(matches=matches)
 
 # get player match scores
-playerMatchScores = api.getPlayerMatchScores(matches, positions)
+playerMatchScores = api.getPlayerMatchScores(matches=matches, positions=positions)  # specific positions
+playerMatchScoresAll = api.getPlayerMatchScores(matches=matches)  # all positions
 
 # get squad match scores
-squadMatchScores = api.getSquadMatchScores(matches)
+squadMatchScores = api.getSquadMatchScores(matches=matches)
 
 # get player iteration scores
-playerIterationScores = api.getPlayerIterationScores(iteration, positions)
+playerIterationScores = api.getPlayerIterationScores(iteration=iteration, positions=positions)  # specific positions
+playerIterationScoresAll = api.getPlayerIterationScores(iteration=iteration)  # all positions
 
 # get squad iteration scores
-squadIterationScores = api.getSquadIterationScores(iteration)
+squadIterationScores = api.getSquadIterationScores(iteration=iteration)
 
 # get player profile scores
-playerProfileScores = api.getPlayerProfileScores(iteration, positions)
+playerProfileScores = api.getPlayerProfileScores(iteration=iteration, positions=positions)
 ```
 
 ## Final Notes
 
 Further documentation on the data and explanations of variables can be
-found in our [glossary](https://glossary.impect.com/).
+found in our [Glossary](https://glossary.impect.com/).

{impectPy-2.4.4 → impectPy-2.5.1}/impectPy/__init__.py

@@ -1,5 +1,5 @@
 # define version attribute
-__version__ = "2.4.4"
+__version__ = "2.5.1"
 
 # import modules
 from .access_token import getAccessToken
@@ -14,6 +14,7 @@ from .player_profile_scores import getPlayerProfileScores
 from .xml import generateXML
 from .set_pieces import getSetPieces
 from .squad_ratings import getSquadRatings
+from .squad_coefficients import getSquadCoefficients
 from .match_info import getFormations, getSubstitutions, getStartingPositions
 from .config import Config as Config
 from .impect import Impect as Impect

{impectPy-2.4.4 → impectPy-2.5.1}/impectPy/events.py

@@ -2,10 +2,10 @@
 import numpy as np
 import pandas as pd
 import requests
-from impectPy.helpers import RateLimitedAPI
+import re
+from impectPy.helpers import RateLimitedAPI, ForbiddenError
 from .matches import getMatchesFromHost
 from .iterations import getIterationsFromHost
-import re
 
 ######
 #
@@ -38,18 +38,18 @@ def getEventsFromHost(
         raise Exception("Argument 'matches' must be a list of integers.")
 
     # get match info
-    iterations = pd.concat(
+    match_data = pd.concat(
         map(lambda match: connection.make_api_request_limited(
             url=f"{host}/v5/customerapi/matches/{match}",
             method="GET"
         ).process_response(
-            endpoint="Iterations"
+            endpoint="Match Info"
         ),
             matches),
         ignore_index=True)
 
     # filter for matches that are unavailable
-    fail_matches = iterations[iterations.lastCalculationDate.isnull()].id.drop_duplicates().to_list()
+    fail_matches = match_data[match_data.lastCalculationDate.isnull()].id.drop_duplicates().to_list()
 
     # drop matches that are unavailable from list of matches
     matches = [match for match in matches if match not in fail_matches]
@@ -62,7 +62,7 @@ def getEventsFromHost(
             print(f"The following matches are not available yet and were ignored:\n{fail_matches}")
 
     # extract iterationIds
-    iterations = list(iterations[iterations.lastCalculationDate.notnull()].iterationId.unique())
+    iterations = list(match_data[match_data.lastCalculationDate.notnull()].iterationId.unique())
 
     # get match events
     events = pd.concat(
@@ -118,6 +118,25 @@ def getEventsFromHost(
             iterations),
         ignore_index=True)[["id", "name"]].drop_duplicates()
 
+    # get coaches
+    coaches_blacklisted = False
+    try:
+        coaches = pd.concat(
+            map(lambda iteration: connection.make_api_request_limited(
+                url=f"{host}/v5/customerapi/iterations/{iteration}/coaches",
+                method="GET"
+            ).process_response(
+                endpoint="Coaches",
+                raise_exception=False
+            ),
+                iterations),
+            ignore_index=True)[["id", "name"]].drop_duplicates()
+    except KeyError:
+        # no coaches found, create empty df
+        coaches = pd.DataFrame(columns=["id", "name"])
+    except ForbiddenError:
+        coaches_blacklisted = True
+
     # get matches
     matchplan = pd.concat(
         map(lambda iteration: getMatchesFromHost(
@@ -188,7 +207,7 @@ def getEventsFromHost(
 
     # start merging dfs
 
-    # merge events with squads
+    # merge events with secondary data
     events = events.merge(
         squads[["id", "name"]].rename(columns={"id": "squadId", "name": "squadName"}),
         left_on="squadId",
@@ -201,10 +220,7 @@ def getEventsFromHost(
         right_on="squadId",
         how="left",
         suffixes=("", "_away")
-    )
-
-    # merge events with players
-    events = events.merge(
+    ).merge(
         players[["id", "commonname"]].rename(columns={"id": "playerId", "commonname": "playerName"}),
         left_on="playerId",
         right_on="playerId",
@@ -243,19 +259,20 @@ def getEventsFromHost(
         right_on="dribbleOpponentPlayerId",
         how="left",
         suffixes=("", "_right")
-    )
-
-    # merge with matches info
-    events = events.merge(
+    ).merge(
         matchplan,
         left_on="matchId",
         right_on="id",
         how="left",
         suffixes=("", "_right")
-    )
-
-    # merge with competition info
-    events = events.merge(
+    ).merge(
+        match_data[["id", "squadHomeCoachId", "squadAwayCoachId"]].rename(
+            columns={"squadHomeCoachId": "homeSquadCoachId", "squadAwayCoachId": "awaySquadCoachId"}),
+        left_on="matchId",
+        right_on="id",
+        how="left",
+        suffixes=("", "_right")
+    ).merge(
         iterations,
         left_on="iterationId",
         right_on="id",
@@ -263,6 +280,21 @@ def getEventsFromHost(
         suffixes=("", "_right")
     )
 
+    if not coaches_blacklisted:
+        events = events.merge(
+            coaches[["id", "name"]].rename(columns={"id": "homeCoachId", "name": "homeCoachName"}),
+            left_on="homeSquadCoachId",
+            right_on="homeCoachId",
+            how="left",
+            suffixes=("", "_right")
+        ).merge(
+            coaches[["id", "name"]].rename(columns={"id": "awayCoachId", "name": "awayCoachName"}),
+            left_on="awaySquadCoachId",
+            right_on="awayCoachId",
+            how="left",
+            suffixes=("", "_right")
+        )
+
     if include_kpis:
         # unnest scorings and full join with kpi list to ensure all kpis are present
         scorings = scorings.merge(kpis, left_on="kpiId", right_on="id", how="outer") \
@@ -374,12 +406,16 @@ def getEventsFromHost(
         "homeSquadName",
         "homeSquadCountryId",
         "homeSquadCountryName",
+        "homeCoachId",
+        "homeCoachName",
         "homeSquadType",
         "awaySquadId",
         "awaySquadName",
         "awaySquadCountryId",
         "awaySquadCountryName",
         "awaySquadType",
+        "awayCoachId",
+        "awayCoachName",
         "eventId",
         "eventNumber",
         "sequenceIndex",
@@ -506,6 +542,9 @@ def getEventsFromHost(
         # add kpis
         order = order + kpi_cols
 
+    if coaches_blacklisted:
+        order = [col for col in order if col not in ["homeCoachId", "homeCoachName", "awayCoachId", "awayCoachName"]]
+
     # reorder data
     events = events[order]