By Brian Greenwood and Tyler Richardett

For the latter half of 2021, American Soccer Analysis has been working on an R and Python library to make it easier to programmatically interact with our data. Today, we are happy to announce the release of the library which we've dubbed itscalledsoccer. If you want to get started right away, the library is available for download from CRAN and PyPI, and the source code can be found here.

In this article, we'll talk a bit about how we built the library and walk through a basic example or two.

Writing A Library

At a high level, itscalledsoccer is just a wrapper around the American Soccer Analysis API that powers our interactive tables. Many functions the library makes available are just API calls with some sensible defaults. When initially designing the library, we had considered writing the core functionality in C++ and having both versions directly call the shared C++ code, much like how xgboost is written. But given that we didn't have a lot of C++ expertise, we decided to maintain separate codebases for the R and Python versions. So in essence, the versions are two separate entities that we manually keep in sync. Both versions have caching enabled, so when making repeated calls, the results are stored locally, which speeds up performance and reduces load on the API. We have rate limiting enabled on the API, and the library gracefully handles this by executing large queries in batches.

How To Use itscalledsoccer

# Python

pip install itscalledsoccer

# R

install.packages("itscalledsoccer")

Once the library is installed, you'll want to import it and create a client.

# Python

from itscalledsoccer.client import AmericanSoccerAnalysis

asa_client = AmericanSoccerAnalysis()

# R

library(itscalledsoccer)

asa_client <- AmericanSoccerAnalysis$new()

Once you have a client, querying data can be done by calling any of the get_* functions. For instance, if I wanted to get goals added for a particular Philadelphia Union goalkeeper, I would use the get_goalkeeper_goals_added function. All the library functions return a data frame.

# Python

df = asa_client.get_goalkeeper_goals_added(leagues="mls", player_names="Andre Blake")

# R

df <- asa_client$get_goalkeeper_goals_added(leagues = "mls", player_names = "Andre Blake") %>% tidyr::unnest(data)

  
player_id   team_id   minutes_played   action_type   goals_added_raw   goals_added_above_avg   count_actions   competition  
7VqGmob3Mv 9z5k7Yg5A3 17805 Claiming -0.2881 -0.2653 279 mls
7VqGmob3Mv 9z5k7Yg5A3 17805 Fielding -1.1517 -0.1366 2279 mls
7VqGmob3Mv 9z5k7Yg5A3 17805 Handling -0.8955 -0.9808 566 mls
7VqGmob3Mv 9z5k7Yg5A3 17805 Passing 11.3168 -0.205 5203 mls
7VqGmob3Mv 9z5k7Yg5A3 17805 Shotstopping -1.4373 3.0576 805 mls
7VqGmob3Mv 9z5k7Yg5A3 17805 Sweeping -0.4462 -0.1893 373 mls

If I wanted to get demographic data of all past and present NWSL managers, I would use the get_managers function.

# Python

df = asa_client.get_managers(leagues="nwsl")

# R

df <- asa_client$get_managers(leagues = "nwsl")

manager_id   manager_name   nationality  
e7MzExPQr0 Amy LePeilbet USA
NPqxODg59d Becky Burleigh USA
wvq9mKNqWn Christy Holly Northern Ireland
gOMnE7XQwN Craig Harrington England
lgpMOr7Qzy David Hodgson 
NWMWR7eQlz Denise Reddy USA
… … …

Looking ahead

Again, in the interest of openness (and of getting others to do our work for us), we’d like to highlight that all of our source code for the library is publicly available on GitHub. If you’d like to report a bug or request a new feature, please open an issue. Or, if you’d like to contribute code, we’ve left some instructions there as well. Our application and API do use modest compute resources, so we ask that you be mindful when using the library.

We plan to add new features over time, hopefully starting with a CLI. We hope that itscalledsoccer provides another useful way for folks to interact with our data, and if you do make something with the library we just ask that you give us proper attribution credit. And we would love for you to share it with us!