1 """
2 Introduction
3 ============
4 An API to retrieve and read NFL Game Center JSON data.
5 It can work with real-time data, which can be used for fantasy football.
6
7 nflgame works by parsing the same JSON data that powers NFL.com's live
8 GameCenter. Therefore, nflgame can be used to report game statistics while
9 a game is being played.
10
11 The package comes pre-loaded with game data from every pre- and regular
12 season game from 2009 up until August 28, 2012. Therefore, querying such data
13 does not actually ping NFL.com.
14
15 However, if you try to search for data in a game that is being currently
16 played, the JSON data will be downloaded from NFL.com at each request (so be
17 careful not to inspect for data too many times while a game is being played).
18 If you ask for data for a particular game that hasn't been cached to disk
19 but is no longer being played, it will be automatically cached to disk
20 so that no further downloads are required.
21
22 nflgame requires Python 2.6 or Python 2.7. It does not (yet) work with
23 Python 3.
24
25 Examples
26 ========
27
28 Finding games
29 -------------
30 Games can be selected in bulk, e.g., every game in week 1 of 2010::
31
32 games = nflgame.games(2010, week=1)
33
34 Or pin-pointed exactly, e.g., the Patriots week 17 whomping against the Bills::
35
36 game = nflgame.game(2011, 17, "NE", "BUF")
37
38 This season's (2012) pre-season games can also be accessed::
39
40 pregames = nflgame.games(2012, kind='PRE')
41
42 Find passing leaders of a game
43 ------------------------------
44 Given some game, the player statistics can be easily searched. For example,
45 to find the passing leaders of a particular game::
46
47 for p in game.players.passing().sort("passing_yds"):
48 print p, p.passing_att, p.passing_cmp, p.passing_yds, p.passing_tds
49
50 Output::
51
52 T.Brady 35 23 338 3
53 R.Fitzpatrick 46 29 307 2
54 B.Hoyer 1 1 22 0
55
56 See every player that made an interception
57 ------------------------------------------
58 We can filter all players on whether they had more than zero defensive
59 interceptions, and then sort those players by the number of picks::
60
61 for p in game.players.filter(defense_int=lambda x:x>0).sort("defense_int"):
62 print p, p.defense_int
63
64 Output::
65
66 S.Moore 2
67 A.Molden 1
68 D.McCourty 1
69 N.Barnett 1
70
71 Finding weekly rushing leaders
72 ------------------------------
73 Sequences of players can be added together, and their sum can then be used
74 like any other sequence of players. For example, to get every player
75 that played in week 10 of 2009::
76
77 week10 = nflgame.games(2009, 10)
78 players = nflgame.combine(week10)
79
80 And then to list all rushers with at least 10 carries sorted by rushing yards::
81
82 rushers = players.rushing()
83 for p in rushers.filter(rushing_att=lambda x: x > 10).sort("rushing_yds"):
84 print p, p.rushing_att, p.rushing_yds, p.rushing_tds
85
86 And the final output::
87
88 A.Peterson 18 133 2
89 C.Johnson 26 132 2
90 S.Jackson 26 131 1
91 M.Jones-Drew 24 123 1
92 J.Forsett 17 123 1
93 M.Bush 14 119 0
94 L.Betts 26 114 1
95 F.Gore 25 104 1
96 J.Charles 18 103 1
97 R.Williams 20 102 0
98 K.Moreno 18 97 0
99 L.Tomlinson 24 96 2
100 D.Williams 19 92 0
101 R.Rice 20 89 1
102 C.Wells 16 85 2
103 J.Stewart 11 82 2
104 R.Brown 12 82 1
105 R.Grant 19 79 0
106 K.Faulk 12 79 0
107 T.Jones 21 77 1
108 J.Snelling 18 61 1
109 K.Smith 12 55 0
110 C.Williams 14 52 1
111 M.Forte 20 41 0
112 P.Thomas 11 37 0
113 R.Mendenhall 13 36 0
114 W.McGahee 13 35 0
115 B.Scott 13 33 0
116 L.Maroney 13 31 1
117
118 You could do the same for the entire 2009 season::
119
120 players = nflgame.combine(nflgame.games(2009))
121 for p in players.rushing().sort("rushing_yds").limit(35):
122 print p, p.rushing_att, p.rushing_yds, p.rushing_tds
123
124 And the output::
125
126 C.Johnson 322 1872 12
127 S.Jackson 305 1361 4
128 A.Peterson 306 1335 17
129 T.Jones 305 1324 12
130 M.Jones-Drew 296 1309 15
131 R.Rice 240 1269 7
132 R.Grant 271 1202 10
133 C.Benson 272 1118 6
134 D.Williams 210 1104 7
135 R.Williams 229 1090 11
136 R.Mendenhall 222 1014 7
137 F.Gore 206 1013 8
138 J.Stewart 205 1008 9
139 K.Moreno 233 897 5
140 M.Turner 177 864 10
141 J.Charles 165 861 5
142 F.Jackson 205 850 2
143 M.Barber 200 841 7
144 B.Jacobs 218 834 5
145 M.Forte 242 828 4
146 J.Addai 213 788 9
147 C.Williams 190 776 4
148 C.Wells 170 774 7
149 A.Bradshaw 156 765 7
150 L.Maroney 189 735 9
151 J.Harrison 161 735 4
152 P.Thomas 141 733 5
153 L.Tomlinson 221 729 12
154 Kv.Smith 196 678 4
155 L.McCoy 154 633 4
156 M.Bell 155 626 5
157 C.Buckhalter 114 624 1
158 J.Jones 163 602 2
159 F.Jones 101 594 2
160 T.Hightower 137 574 8
161
162 Load data into Excel
163 --------------------
164 Every sequence of Players can be easily dumped into a file formatted
165 as comma-separated values (CSV). CSV files can then be opened directly
166 with programs like Excel, Google Docs, Open Office and Libre Office.
167
168 You could dump every statistic from a game like so::
169
170 game.players.csv('player-stats.csv')
171
172 Or if you want to get crazy, you could dump the statistics of every player
173 from an entire season::
174
175 nflgame.combine(nflgame.games(2010)).csv('season2010.csv')
176 """
177
178 try:
179 from collections import OrderedDict
180 except:
181 from ordereddict import OrderedDict
182 import itertools
183
184 import nflgame.game
185 import nflgame.live
186 import nflgame.player
187 import nflgame.schedule
188 import nflgame.seq
189
190 VERSION = "1.1.2"
191
192 NoPlayers = nflgame.seq.GenPlayerStats(None)
193 """
194 NoPlayers corresponds to the identity element of a Players sequences.
195
196 Namely, adding it to any other Players sequence has no effect.
197 """
198
199 players = nflgame.player._create_players()
200 """
201 A dict of all players and meta information about each player keyed
202 by GSIS ID. (The identifiers used by NFL.com GameCenter.)
203 """
204
205 teams = [
206 ['ARI', 'Arizona', 'Cardinals', 'Arizona Cardinals'],
207 ['ATL', 'Atlanta', 'Falcons', 'Atlana Falcons'],
208 ['BAL', 'Baltimore', 'Ravens', 'Baltimore Ravens'],
209 ['BUF', 'Buffalo', 'Bills', 'Buffalo Bills'],
210 ['CAR', 'Carolina', 'Panthers', 'Caroline Panthers'],
211 ['CHI', 'Chicago', 'Bears', 'Chicago Bears'],
212 ['CIN', 'Cincinnati', 'Bengals', 'Cincinnati Bengals'],
213 ['CLE', 'Cleveland', 'Browns', 'Cleveland Browns'],
214 ['DAL', 'Dallas', 'Cowboys', 'Dallas Cowboys'],
215 ['DEN', 'Denver', 'Broncos', 'Denver Broncos'],
216 ['DET', 'Detroit', 'Lions', 'Detroit Lions'],
217 ['GB', 'Green Bay', 'Packers', 'Green Bay Packers', 'G.B.'],
218 ['HOU', 'Houston', 'Texans', 'Houston Texans'],
219 ['IND', 'Indianapolis', 'Colts', 'Indianapolis Colts'],
220 ['JAC', 'Jacksonville', 'Jaguars', 'Jacksonville Jaguars', 'JAX'],
221 ['KC', 'Kansas City', 'Chiefs', 'Kansas City Chiefs', 'K.C.'],
222 ['MIA', 'Miami', 'Dolphins', 'Miami Dolphins'],
223 ['MIN', 'Minnesota', 'Vikings', 'Minnesota Vikings'],
224 ['NE', 'New England', 'Patriots', 'New England Patriots', 'N.E.'],
225 ['NO', 'New Orleans', 'Saints', 'New Orleans Saints', 'N.O.'],
226 ['NYG', 'Giants', 'New York Giants', 'N.Y.G.'],
227 ['NYJ', 'Jets', 'New York Jets', 'N.Y.J.'],
228 ['OAK', 'Oakland', 'Raiders', 'Oakland Raiders'],
229 ['PHI', 'Philadelphia', 'Eagles', 'Philadelphia Eagles'],
230 ['PIT', 'Pittsburgh', 'Steelers', 'Pittsburgh Steelers'],
231 ['SD', 'San Diego', 'Chargers', 'San Diego Chargers', 'S.D.'],
232 ['SEA', 'Seattle', 'Seahawks', 'Seattle Seahawks'],
233 ['SF', 'San Francisco', '49ers', 'San Francisco 49ers', 'S.F.'],
234 ['STL', 'St. Louis', 'Rams', 'St. Louis Rams', 'S.T.L.'],
235 ['TB', 'Tampa Bay', 'Buccaneers', 'Tampa Bay Buccaneers', 'T.B.'],
236 ['TEN', 'Tennessee', 'Titans', 'Tennessee Titans'],
237 ['WAS', 'Washington', 'Redskins', 'Washington Redskins', 'WSH'],
238 ]
239 """
240 A list of all teams. Each item is a list of different ways to
241 describe a team. (i.e., JAC, JAX, Jacksonville, Jaguars, etc.).
242 The first item in each list is always the standard NFL.com
243 team abbreviation (two or three letters).
244 """
245
246
247 -def find(name, team=None):
248 """
249 Finds a player (or players) with a name matching (case insensitive)
250 name and returns them as a list.
251
252 If team is not None, it is used as an additional search constraint.
253 """
254 hits = []
255 for player in players.itervalues():
256 if player.name.lower() == name.lower():
257 if team is None or team.lower() == player.team.lower():
258 hits.append(player)
259 return hits
260
261
263 """
264 Returns a standard abbreviation when team corresponds to a team in
265 nflgame.teams (case insensitive). All known variants of a team name are
266 searched. If no team is found, None is returned.
267 """
268 team = team.lower()
269 for variants in teams:
270 for variant in variants:
271 if team == variant.lower():
272 return variants[0]
273 return None
274
275
276 -def games(year, week=None, home=None, away=None, kind='REG', started=False):
277 """
278 games returns a list of all games matching the given criteria. Each
279 game can then be queried for player statistics and information about
280 the game itself (score, winner, scoring plays, etc.).
281
282 As a special case, if the home and away teams are set to the same team,
283 then all games where that team played are returned.
284
285 The kind parameter specifies whether to fetch preseason, regular season
286 or postseason games. Valid values are PRE, REG and POST.
287
288 The week parameter is relative to the value of the kind parameter, and
289 may be set to a list of week numbers.
290 In the regular season, the week parameter corresponds to the normal
291 week numbers 1 through 17. Similarly in the preseason, valid week numbers
292 are 1 through 4. In the post season, the week number corresponds to the
293 numerical round of the playoffs. So the wild card round is week 1,
294 the divisional round is week 2, the conference round is week 3
295 and the Super Bowl is week 4.
296
297 The year parameter specifies the season, and not necessarily the actual
298 year that a game was played in. For example, a Super Bowl taking place
299 in the year 2011 actually belongs to the 2010 season. Also, the year
300 parameter may be set to a list of seasons just like the week parameter.
301
302 Note that if a game's JSON data is not cached to disk, it is retrieved
303 from the NFL web site. A game's JSON data is *only* cached to disk once
304 the game is over, so be careful with the number of times you call this
305 while a game is going on. (i.e., don't piss off NFL.com.)
306
307 If started is True, then only games that have already started (or are
308 about to start in less than 5 minutes) will be returned. Note that the
309 started parameter requires pytz to be installed. This is useful when
310 you only want to collect stats from games that have JSON data available
311 (as opposed to waiting for a 404 error from NFL.com).
312 """
313 return list(games_gen(year, week, home, away, kind, started))
314
315
316 -def games_gen(year, week=None, home=None, away=None,
317 kind='REG', started=False):
318 """
319 games returns a generator of all games matching the given criteria. Each
320 game can then be queried for player statistics and information about
321 the game itself (score, winner, scoring plays, etc.).
322
323 As a special case, if the home and away teams are set to the same team,
324 then all games where that team played are returned.
325
326 The kind parameter specifies whether to fetch preseason, regular season
327 or postseason games. Valid values are PRE, REG and POST.
328
329 The week parameter is relative to the value of the kind parameter, and
330 may be set to a list of week numbers.
331 In the regular season, the week parameter corresponds to the normal
332 week numbers 1 through 17. Similarly in the preseason, valid week numbers
333 are 1 through 4. In the post season, the week number corresponds to the
334 numerical round of the playoffs. So the wild card round is week 1,
335 the divisional round is week 2, the conference round is week 3
336 and the Super Bowl is week 4.
337
338 The year parameter specifies the season, and not necessarily the actual
339 year that a game was played in. For example, a Super Bowl taking place
340 in the year 2011 actually belongs to the 2010 season. Also, the year
341 parameter may be set to a list of seasons just like the week parameter.
342
343 Note that if a game's JSON data is not cached to disk, it is retrieved
344 from the NFL web site. A game's JSON data is *only* cached to disk once
345 the game is over, so be careful with the number of times you call this
346 while a game is going on. (i.e., don't piss off NFL.com.)
347
348 If started is True, then only games that have already started (or are
349 about to start in less than 5 minutes) will be returned. Note that the
350 started parameter requires pytz to be installed. This is useful when
351 you only want to collect stats from games that have JSON data available
352 (as opposed to waiting for a 404 error from NFL.com).
353 """
354 infos = _search_schedule(year, week, home, away, kind, started)
355 if not infos:
356 return None
357
358 def gen():
359 for info in infos:
360 yield nflgame.game.Game(info['eid'])
361 return gen()
362
363
364 -def one(year, week, home, away, kind='REG', started=False):
365 """
366 one returns a single game matching the given criteria. The
367 game can then be queried for player statistics and information about
368 the game itself (score, winner, scoring plays, etc.).
369
370 one returns either a single game or no games. If there are multiple games
371 matching the given criteria, an assertion is raised.
372
373 The kind parameter specifies whether to fetch preseason, regular season
374 or postseason games. Valid values are PRE, REG and POST.
375
376 The week parameter is relative to the value of the kind parameter, and
377 may be set to a list of week numbers.
378 In the regular season, the week parameter corresponds to the normal
379 week numbers 1 through 17. Similarly in the preseason, valid week numbers
380 are 1 through 4. In the post season, the week number corresponds to the
381 numerical round of the playoffs. So the wild card round is week 1,
382 the divisional round is week 2, the conference round is week 3
383 and the Super Bowl is week 4.
384
385 The year parameter specifies the season, and not necessarily the actual
386 year that a game was played in. For example, a Super Bowl taking place
387 in the year 2011 actually belongs to the 2010 season. Also, the year
388 parameter may be set to a list of seasons just like the week parameter.
389
390 Note that if a game's JSON data is not cached to disk, it is retrieved
391 from the NFL web site. A game's JSON data is *only* cached to disk once
392 the game is over, so be careful with the number of times you call this
393 while a game is going on. (i.e., don't piss off NFL.com.)
394
395 If started is True, then only games that have already started (or are
396 about to start in less than 5 minutes) will be returned. Note that the
397 started parameter requires pytz to be installed. This is useful when
398 you only want to collect stats from games that have JSON data available
399 (as opposed to waiting for a 404 error from NFL.com).
400 """
401 infos = _search_schedule(year, week, home, away, kind, started)
402 if not infos:
403 return None
404 assert len(infos) == 1, 'More than one game matches the given criteria.'
405 return nflgame.game.Game(infos[0]['eid'])
406
407
409 """
410 DEPRECATED. Please use one of nflgame.combine_{game,play,max}_stats
411 instead.
412
413 Combines a list of games into one big player sequence containing game
414 level statistics.
415
416 This can be used, for example, to get PlayerStat objects corresponding to
417 statistics across an entire week, some number of weeks or an entire season.
418
419 If the plays parameter is True, then statistics will be dervied from
420 play by play data. This mechanism is slower but will contain more detailed
421 statistics like receiver targets, yards after the catch, punt and field
422 goal blocks, etc.
423 """
424 if plays:
425 return combine_play_stats(games)
426 else:
427 return combine_game_stats(games)
428
429
431 """
432 Combines a list of games into one big player sequence containing game
433 level statistics.
434
435 This can be used, for example, to get GamePlayerStats objects corresponding
436 to statistics across an entire week, some number of weeks or an entire
437 season.
438 """
439 return reduce(lambda ps1, ps2: ps1 + ps2, [g.players for g in games])
440
441
443 """
444 Combines a list of games into one big player sequence containing play
445 level statistics.
446
447 This can be used, for example, to get PlayPlayerStats objects corresponding
448 to statistics across an entire week, some number of weeks or an entire
449 season.
450
451 This function should be used in lieu of combine_game_stats when more
452 detailed statistics such as receiver targets, yards after the catch and
453 punt/FG blocks are needed.
454
455 N.B. Since this combines *all* play data, this function may take a while
456 to complete depending on the number of games passed in.
457 """
458 return reduce(lambda p1, p2: p1 + p2, [g.drives.players() for g in games])
459
460
462 """
463 Combines a list of games into one big player sequence containing maximum
464 statistics based on game and play level statistics.
465
466 This can be used, for example, to get GamePlayerStats objects corresponding
467 to statistics across an entire week, some number of weeks or an entire
468 season.
469
470 This function should be used in lieu of combine_game_stats or
471 combine_play_stats when the best possible accuracy is desired.
472 """
473 return reduce(lambda a, b: a + b, [g.max_player_stats() for g in games])
474
475
477 """
478 Combines a list of games into one big play generator that can be searched
479 as if it were a single game.
480 """
481 chain = itertools.chain(*[g.drives.plays() for g in games])
482 return nflgame.seq.GenPlays(chain)
483
484
485 -def _search_schedule(year, week=None, home=None, away=None, kind='REG',
486 started=False):
487 """
488 Searches the schedule to find the game identifiers matching the criteria
489 given.
490
491 The kind parameter specifies whether to fetch preseason, regular season
492 or postseason games. Valid values are PRE, REG and POST.
493
494 The week parameter is relative to the value of the kind parameter, and
495 may be set to a list of week numbers.
496 In the regular season, the week parameter corresponds to the normal
497 week numbers 1 through 17. Similarly in the preseason, valid week numbers
498 are 1 through 4. In the post season, the week number corresponds to the
499 numerical round of the playoffs. So the wild card round is week 1,
500 the divisional round is week 2, the conference round is week 3
501 and the Super Bowl is week 4.
502
503 The year parameter specifies the season, and not necessarily the actual
504 year that a game was played in. For example, a Super Bowl taking place
505 in the year 2011 actually belongs to the 2010 season. Also, the year
506 parameter may be set to a list of seasons just like the week parameter.
507
508 If started is True, then only games that have already started (or are
509 about to start in less than 5 minutes) will be returned. Note that the
510 started parameter requires pytz to be installed. This is useful when
511 you only want to collect stats from games that have JSON data available
512 (as opposed to waiting for a 404 error from NFL.com).
513 """
514 infos = []
515 for (y, t, w, h, a), info in nflgame.schedule.games:
516 if year is not None:
517 if isinstance(year, list) and y not in year:
518 continue
519 if not isinstance(year, list) and y != year:
520 continue
521 if week is not None:
522 if isinstance(week, list) and w not in week:
523 continue
524 if not isinstance(week, list) and w != week:
525 continue
526 if home is not None and away is not None and home == away:
527 if h != home and a != home:
528 continue
529 else:
530 if home is not None and h != home:
531 continue
532 if away is not None and a != away:
533 continue
534 if t != kind:
535 continue
536 if started:
537 gametime = nflgame.live._game_datetime(info)
538 now = nflgame.live._now()
539 if gametime > now and (gametime - now).total_seconds() > 300:
540 continue
541 infos.append(info)
542 return infos
543