rbarton65 / espnff

ESPN Fantasy Football API

ESPN Fantasy Football API

Using ESPN's Fantasy Football private API, this package interfaces with ESPN Fantasy Football to gather data from any public league. A good way to mine data without webscraping for data manipulation projects.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Installing

With pip:

pip3 install espnff

With Git:

git clone https://github.com/rbarton65/espnff

cd espnff

python3 setup.py install

Basic Usage

This gives an overview of all the features of espnff

Downloading a public league

>>> from espnff import League
>>> league_id = 123456
>>> year = 2016
>>> league = League(league_id, year)
>>> league
League 123456, 2016 Season

Viewing teams in a public league

>>> from espnff import League
>>> league_id = 123456
>>> year = 2016
>>> league = League(league_id, year)
>>> league.teams
[Team(Team 1), Team(Team 2), Team(Team 3), Team(Team 4),
Team(Team 5), Team(Team 6), Team(Team 7), Team(Team 8)]
>>> team1 = league.teams[0]
>>> team1
Team(Team 1)

Viewing data for specific team

>>> league.teams
[Team(Team 1), Team(Team 2), Team(Team 3), Team(Team 4),
Team(Team 5), Team(Team 6), Team(Team 7), Team(Team 8)]
>>> team1 = league.teams[0]
>>> team1.team_id
1
>>> team1.team_name
Team 1
>>> team1.team_abbrev
T1
>>> team1.owner
Roger Goodell
>>> team1.division_id
0
>>> team1.division_name
Division 1
>>> team1.wins
5
>>> team1.losses
1
>>> team1.points_for
734.69
>>> team1.points_against
561.15
>>> team1.schedule
[Team(Team 2), Team(Team 3), Team(Team 4), Team(Team 5), Team(Team 6), Team(Team 7), Team(Team 8),
Team(Team 2), Team(Team 3), Team(Team 4), Team(Team 5), Team(Team 6), Team(Team 7), Team(Team 8)
>>> team1.scores
[135.5, 126.38, 129.53, 126.65, 114.81, 101.82, 1.15, 0, 0, 0, 0, 0, 0, 0]
>>> team1.mov
[32.12, 24.92, 45.97, 34.17, 41.74, -5.39, 1.15, 0, 0, 0, 0, 0, 0, 0]

Viewing league settings

>>> from espnff import League
>>> league_id = 123456
>>> year = 2016
>>> league = League(league_id, year)
>>> settings = league.settings
>>> settings
'Settings(League Name)'
>>> settings.reg_season_count
14
>>> self.final_season_count
16
>>> settings.undroppable_list
true
>>> settings.veto_votes_required
4
>>> settings.team_count
8
>>> settings.playoff_team_count
4
>>> settings.id
123456
>>> settings.keeper_count
3
>>> settings.tie_rule
'Most Bench Points'
>>> settings.playoff_seed_tie_rule
'Head to Head Record'
>>> settings.roster
{'RB/WR/TE': 1, 'BE': 7, 'QB': 1, 'D/ST': 1, 'RB': 2, 'TE': 1, 'K': 1, 'WR': 2}
>>> settings.trade_deadline
2016-11-16T17:00:00.000Z
>>> settings.name
League Name
>>> settings.status
playoffs
>>> settings.year
2016
>>> settings.server_date
2016-12-08T21:06:53.087Z

Viewing power rankings

>>> from espnff import League
>>> league_id = 123456
>>> year = 2016
>>> league = League(league_id, year)
>>> league.power_rankings(week=5)
[('31.85', Team(Team 1)), ('25.60', Team(Team 3)), ('25.60', Team(Team 6)), ('22.45', Team(Team 2)),
('20.70', Team(Team 8)), ('18.20', Team(Team 7)), ('18.20', Team(Team 4)), ('18.10', Team(Team 5))]

Viewing scoreboard

>>> from espnff import League
>>> league_id = 123456
>>> year = 2016
>>> league = League(league_id, year)
>>> league.scoreboard() # grab current week
["Matchup(Team(Team 2), Team(Team 7))", "Matchup(Team(Team 1), Team(Team 11))",
"Matchup(Team(Team 6), Team(Team 9))", "Matchup(Team(Team 12), Team(Team 4))",
"Matchup(Team(Team 10), Team(Team 3))", "Matchup(Team(Team 8), Team(Team 5))"]
>>> scoreboard = league.scoreboard(week=12) # define week
>>> scoreboard
["Matchup(Team(Team 2), Team(Team 7))", "Matchup(Team(Team 1), Team(Team 11))",
"Matchup(Team(Team 6), Team(Team 9))", "Matchup(Team(Team 12), Team(Team 4))",
"Matchup(Team(Team 10), Team(Team 3))", "Matchup(Team(Team 8), Team(Team 5))"]
>>> matchup = scoreboard[1]
>>> matchup
"Matchup(Team(Team 1), Team(Team 11))"
>>> matchup.home_team
"Team(Team 1)"
>>> matchup.home_score
7.05
>>> matchup.away_team
"Team(Team 11)"
>>> matchup.away_score
45.85

Running the tests

Automated tests for this package are included in the tests directory. After installation, you can run these tests by changing the directory to the espnff directory and running the following:

python3 setup.py test

Versioning

This library uses SemVer for versioning. For available versions, see the tags on this repository

espnff's Issues

Private League Auth

I see you added cookie support, and I was able to hack my way into using it. However, I think you should document this, and provide a method for setting your cookies. The only way I could get this to work was by hacking the cookie var in the module itself.

Curious about ESPN API...

So I'm a little confused. I wasn't able to get this working on my machine, but before I dig into it too much... I'm curious how you were able to use the ESPN Fantasy Football API, seeing as they stopped issuing new API keys in 2012, and cut off all use in 2014 . Furthermore, I haven't been able to find any information online that would suggest that ESPN has a Fantasy Football API available at this moment. So I'm just curious if, and how, this works on the back-end?

What is the .mov in the example?

Hello,

Hopfully this is something simple, but what is the .mov in the example?

team1.mov
[32.12, 24.92, 45.97, 34.17, 41.74, -5.39, 1.15, 0, 0, 0, 0, 0, 0, 0]

Thanks!

P.S. I'm doing a unique scoring system so this is really helping my automate the scoring each week and display it on a web page, thanks so much!!

issue with scoreboard

This is not an issue with your code but espnff is affected.

for some reason the scoreboard API just kind breaks when making requests for my league, for a specified matchup period, when making a request for data 2+ years old.

For example the Json get request --> http://games.espn.com/ffl/api/v2/scoreboard?leagueId=censored&seasonId=2015&matchupPeriodId=3

returns this -->{"error":[{"code":"exception","message":"java.lang.NullPointerException"}]}

If i request data for 2017 or 2018 I have no issues... Any idea whats going on here?

Power Rankings sometimes return less teams than in league

Download all stats

Pretty new to Python but trying to get all stats into Excel for reporting/metrics over 10 years. Is there a good way to do a CSV dump for every year?

Will the `player` endpoints be added anytime soon?

I noticed the player.py file is empty. Do you plan to add the player endpoints to this library?

Private leagues

Hi, this is an interesting project. Is there any chance of supporting private leagues using stored credentials in the future via OAuth or whatever the ESPN backend is using?

KeyError: 'tradeDeadline' in leagues with no trade deadline

Able to load a year when there was a trade deadline.
Unable to load a year when there was no trade deadline.
Receive the following error "KeyError: 'tradeDeadline'"

Service Unavailable

It appears that ESPN has disallowed access to this data unfortunately

PyPI Not updated to latest version?

It looks like there's a discrepancy between the project files at PyPI (https://pypi.org/project/espnff/1.3.1/#files) versus in this repository and the latest version on master. Is there any plans to update it? I'd love to be able to use this package in a project of mine without having to download the source, and I am currently seeing this issue #22 when I install with pip.

Unable to fetch League

Getting:

league = League(719284, 2017)
Traceback (most recent call last):
File "", line 1, in
File "/Users/Ash/Downloads/espnff-master/espnff/league.py", line 22, in init
self._fetch_league()
File "/Users/Ash/Downloads/espnff-master/espnff/league.py", line 42, in _fetch_league
data = r.json()
File "/anaconda/lib/python3.6/site-packages/requests/models.py", line 877, in json
self.content.decode(encoding), **kwargs
File "/anaconda/lib/python3.6/site-packages/simplejson/init.py", line 516, in loads
return _default_decoder.decode(s)
File "/anaconda/lib/python3.6/site-packages/simplejson/decoder.py", line 374, in decode
obj, end = self.raw_decode(s)
File "/anaconda/lib/python3.6/site-packages/simplejson/decoder.py", line 404, in raw_decode
return self.scan_once(s, idx=_w(s, idx).end())
simplejson.scanner.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Bit of a noob, got this all working properly but unsure how to format/export data to excel sheet or a usable format

Thank you for your time, this script is a lifesaver

README has wrong attribute names for some Team attributes

I was just playing around with this (very cool!), and it seems like some of the Team attribute names are wrong in the README. For example, points_for should be pointsFor (similarly for a few of the others).

I'm not sure which way you want (points_for is probably more pythonic), so probably it's best to follow the README and switch the attributes. If you are interested in help on this project I could submit a PR.

`scoreboard()` function returning an error

>>> league.scoreboard()
File "/usr/lib/python3.5/site-packages/espnff-1.2.2-py3.5.egg/espnff/espnff.py", line 120, in scoreboard
  File "/usr/lib/python3.5/site-packages/espnff-1.2.2-py3.5.egg/espnff/espnff.py", line 120, in <listcomp>
  File "/usr/lib/python3.5/site-packages/espnff-1.2.2-py3.5.egg/espnff/espnff.py", line 178, in __init__
  File "/usr/lib/python3.5/site-packages/espnff-1.2.2-py3.5.egg/espnff/espnff.py", line 188, in _fetch_matchup_info
IndexError: list index out of range

How to install locally

Hey there,

Sorry for creating an issue, but I came across this script and would love to use it for my league. Problem is, I'm a noob with Python and I'm not sure how to get the rankings returned. Are there any beginner tutorials you could point me towards (or simple instructions) on how to run this locally on OS X to get the rankings? I've got MAMP and Coda installed if that helps. Thank you!

Meaning of power rankings

Is there a concise mathematical explanation of the meaning of the power rankings provided by this library? Is this a known formula for computing them?

Power Rankings Break for Leagues with Deleted Members

TL;DR deleted members mess up the matrix math so your dominance matrix and thus power rankings won't be correct

My league has been ongoing since 2016. Since then we've had to delete two members, but in ESPN they still retain that team id (6 and 8 in my case). When the code goes to develop the win matrices for the power rankings, it loops through the teams_sorted array: "for team in teams_sorted:"

The teams_sorted array correctly ignores the deleted teams. However, the win matrix is built upon opponent.team_id, so the team_id for 6 and 8 (array position 5 and 7) still exists. That outputs a matrix with rows != columns (rows follow teams_sorted list, columns follow opponent.team_id). Then, the matrix math uses len(X) where X is the win_matrix for its loops. len(X) gives you the number of rows in the matrix (since a matrix in python is really just a list of list). In my case, this meant that any wins against the two newer teams were ignored because there were 12 rows but 14 columns and the last 2 columns were the 2 newer members.

Sorry for the wall of text, but I was trying to step through to make it clear. I'll see if I can get a PR in but if someone else gets to this before me it's all theirs

Roster endpoint

Is there a known endpoint for getting a team's roster (for future support)?

Unable to Pull Roster Information

I see the revision to the team parameter on JUL 28 with the fetch_roster parameter but I'm unable to correctly pull roster information

ESPN Fantasy platform updates broke JSON parsing?

From what I can tell, some big changes to the ESPN fantasy platform may have changed the format of the JSON this package parses. Especially when attempting to get the leage: league = League(league_id, year).

I get a JSONDecodeError("Expecting value", s, err.value) from None followed by json.decoder.JSONDecodeError: Expecting value: line 2 column 2 (char 2). Can anyone else confirm this problem?

Number of bye week teams

technically this isn't completely necessary since it can be inferred using the number regular season vs total weeks and the number of playoff teams, but it would be a nice feature

number of playoff rounds goes along with this too

Adapt To Baseball

Any idea how one would adapt this to ESPNs fantasty baseball? Would it use a similar or different API?

Request: Power rankings take week as optional argument.

Request: Power rankings take week as optional argument.
Assume current week like with scoreboard if no week provided.

Typo

There is a typo in league.py, line 108

'matchupPeriodId' should be 'matchUpPeriodId' else there is an error when trying to get the scoreboard by week.