A package provided by: Impect GmbH
Version: v2.4.3
Updated: June 5th 2025
Supported API Version: V5
For older versions, please see list below:
The goal of the impectR package is to provide an easy way for Impect Customers to access data from the customer API. This API includes basic information about competitions, competition iterations, and matches as well as event data and aggregated scorings per player and position on match and season level.
You can install the latest version of impectR from GitHub with:
# install.packages("devtools")
::install_github("ImpectAPI/impectR@v2.4.3") devtools
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:
library(impectR)
# define login credentials
<- "yourUsername"
username <- "yourPassword"
password
# get access token
<- getAccessToken(username = username, password = password) token
This access token is a requirement to use any of the functions that requests data from the API. We recommend to first get a list of competition iterations that are enabled for your account.
# get list of iterations
<- getIterations(token = token)
iterations
# print iterations to console
iterations
If any iteration you were expected to see is not listed, please contact 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:
# get matches for iteration
<- getMatches(iteration = 518, token = token)
matches
# print matches to console
matches
The column available
denotes whether a given match has
been tagged by Impect and the data is available to you.
Let’s assume you are interested in the FC Bayern München vs Borussia Dortmund game from April 1st 2023 (matchId = 84344) and want to retrieve event level data as well as team formation, starting position and substitution data. As the functions allows 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:
# define matches to get event data for
<- c(84344)
matchIds
# get event data for match
<- getEvents(
events matches = matchIds,
token = token,
include_kpis = TRUE,
include_set_pieces = TRUE
)
# get match info
= getFormations(matches, token)
formations = getSubstitutions(matches, token)
substitutions = getStartingPositions(matches, token)
starting_positions
# print first few rows from events dataframe to console
head(events)
You can access the aggregated KPIs, scores and ratios per player and position or per squad for this match in a similar way. You can also find more detailed data around set piece situations within our API. Also, we provide you with IMPECT scores and ratios that you might know from our 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:
# define matches to get further data for
<- c(84344)
matchIds
# get set piece data including KPI aggregates
<- getSetPieces(matches = matchIds, token = token)
setPieces
# get kpi matchsums for match per player and position
<- getPlayerMatchsums(matches = matchIds, token = token)
playerMatchsums
# get kpi matchsums for match per squad
<- getSquadMatchsums(matches = matchIds, token = token)
squadMatchsums
# define positions to get scores aggregated by
<- c("LEFT_WINGBACK_DEFENDER", "RIGHT_WINGBACK_DEFENDER")
positions
# get player scores and ratios for match and positions per player
<-
playerMatchScores getPlayerMatchScores(matches = matchIds, positions = positions, token = token)
# get squad scores and ratios for match per squad
<- getSquadMatchScores(matches = matchIds, token = token) squadMatchScores
In case you wish to retrieve data for multiple matches, we suggest using 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:
# define list of matches
<- c(84344, 84350)
matchIds
# get event data for matches
<- getEvents(
events matches = matchIds,
token = token,
include_kpis = True,
include_set_pieces = True
)
# get set piece data including KPI aggregates
<- getSetPieces(ip.getSetPieces(matches = matchIds, token = token)
setPieces
# get matchsums for matches per player and position
<- getPlayerMatchsums(matches = matchIds, token = token)
playerMatchsums
# get matchsums for matches per squad
<- getSquadMatchsums(matches = matchIds, token = token)
squadMatchsums
# define positions to get scores aggregated by
<- c("LEFT_WINGBACK_DEFENDER", "RIGHT_WINGBACK_DEFENDER")
positions
# get player scores and ratios for match and positions per player
<-
playerMatchScores getPlayerMatchScores(matches = matchIds, positions = positions, token = token)
# get squad scores and ratios for match per squad
<- getSquadMatchScores(matches = matchIds, token = token) squadMatchScores
Starting from API version V5, we also offer an endpoint to get KPI average values per iteration on player as well as squad level. These averages are calculated by dividing the kpi sum of all individual matches by the sum of matchShares the player accumulated at a given position. On a team level we divide the score by the amount of matches played by the team. Also, we provide you with IMPECT scores and ratios that you might know from our 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. Let’s assume you were interested in wingbacks in the 2022/2023 Bundesliga season, then you could use this code snippet:
# define iteration ID
<- 518
iteration
# define positions to get scores aggregated by
<- c("LEFT_WINGBACK_DEFENDER", "RIGHT_WINGBACK_DEFENDER")
positions
# get player kpi averages for iteration
<-
playerIterationAverages getPlayerIterationAverages(iteration = iteration, token = token)
# get squad kpi averages for iteration
<-
squadIterationAverages getSquadIterationAverages(iteration = iteration, token = token)
# get player scores and ratios for iteration and positions
<-
playerIterationScores getPlayerIterationScores(iteration = iteration, positions = positions, token = token)
# get squad scores and ratios for iteration
<-
squadIterationScores getSquadIterationScores(iteration = iteration, token = token)
# get squad ratings for iteration
<- getSquadRatings(iteration = iteration, token = token) squadRatings
Please keep in mind that Impect enforces a rate limit of 10 requests per second per user. A token bucket logic has been implemented to restrict the amount of API calls made on the client side already. The rate limit is read from the first limit policy sent back by the API, so if this limit increases over time, this package will act accordingly.
Further documentation on the data and explanations of variables can be found in our glossary.