fantasy_football_nerd 0.9.0 → 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eb05673e2ae71ef09f1f6f36d69689c0769c7602
+  data.tar.gz: ce806bf9400433cabd4c01fb09bd3db1f604e0c7
+SHA512:
+  metadata.gz: c451073cafd872881ad09a3f08c4d85678450579d660dcbb4783e246cb292d52cf23f91271c86a2abf089f51076e125f7de15a81b6bdb7dfb441851bf65f5c36
+  data.tar.gz: 9a8a1f831619960aaea70d6ebd802bd7c1b3a0f2c6818f881facb2408ff5a46fef51d2cb90de23521b7e83b378af2d4a6727c0046fdf9220011f69a411752588

data/README.md

@@ -1,22 +1,30 @@
-Fantasy Football Nerd API
-==========================
+Fantasy Football Nerd API Ruby Gem
+==================================
 
-This is a Ruby Gem for the [Fantasy Football Nerd API](http://www.fantasyfootballnerd.com/api).
+A Ruby Gem for the [Fantasy Football Nerd API](http://www.fantasyfootballnerd.com/api) which: 
 
-[Fantasy Football Nerd](http://www.fantasyfootballnerd.com) "takes the 'wisdom of the crowd' to a new level by aggregating the fantasy football rankings of the best fantasy football sites... and weighting the rankings based upon past accuracy."
+> takes the "wisdom of the crowd" to a new level by aggregating the fantasy football rankings of the best fantasy football sites on the planet to analyze the rankings given to each player to produce a consensus ranking.
 
-Fantasy Football Nerd provides an API with access to this fantasy football data:
+This gem currently supports all Level 1 and Level 2 streams which cost $9 per season -- a total no-brainer if you're into fantasy sports and programming. Give the man his money.  
 
-* Players List
-* Player Details (including recent articles)
-* Weekly Projections
-* Injury Reports
-* Preseason Draft Rankings (not currently supported)
-* Season Schedule (not currently supported)
+Here's what you get with $9 and this gem: 
 
+* Current Week
+* Team List
+* Season schedule
+* Player list
+* Bye weeks
+* Injuries
+* Auction draft values
+* Draft rankings - projected fantasy points for the entire season
+* Draft projections - projected stats for each scoring category for the entire season 
+* Weekly rankings - projected fantasy points (PPR || Standard)
+* Weekly projections - projected stats for each scoring category
 
-Full API access costs $9 for a season subsciption, though if you are a developer with a modicum of interest in Fantasy Football, this is the best $9 you will spend all season.
+v1.0
+----------------
 
+Fantasy Football Nerd recently overhauled to their API which a) drastically improved their service and b) completely deprecated the old API. The previous version of this gem won't work anymore so update your Gemfiles. 
 
 Cache your data!
 ----------------
@@ -24,148 +32,280 @@ Take heed to the warning on the [Fantasy Football Nerd API page](http://www.fant
 
 >The data does not generally change more than once or twice per day, so it becomes unnecessary to continually make the same calls. Please store the results locally and reference the cached responses... Your account may be suspended or API access revoked if you are found to be making excessive data calls.
 
-Seriously, FFN is not a big operation. Don't abuse their servers.
+Seriously, Fantasy Football Nerd is not a big operation. Don't abuse their servers.
 
 Setup
 =================
-Install the gem:
+First, [sign up](http://www.fantasyfootballnerd.com/create-account) for a Fantasy Football Nerd account. Then... 
 
-        gem install fantasy-football-nerd
+In plain ol' Ruby, install the gem:
 
-In plain ol' ruby, require it:
+```
+gem install fantasy_football_nerd
+```
 
-````ruby
-require 'rubygems'
-require 'fantasy-football-nerd'
-````
-
-In rails, add the gem to your gemfile:
+And require it:
 
 ````ruby
-gem 'fantasy-football-nerd'
+require 'rubygems'
+require 'fantasy_football_nerd'
 ````
 
-Set your FFN APIKey before making any calls:
+If you're using Rails, add the gem to your Gemfile and run ```bundle install```
 
 ````ruby
-FFNerd.api_key = 123456789
+gem 'fantasy_football_nerd'
 ````
 
-API Resources
-===================
-
-Currently, this gem provides access to four feeds:
+Before you can access the feeds you must set your API key (found on the [Fantasy Football Nerd API dashboard](http://www.fantasyfootballnerd.com/api)) via one of two ways: 
 
-* Player List
-* Player Detail
-* Weekly Projections
-* Injuries
-
-Player List
---------------------------
+Set an environment variable via the terminal. 
 
-````ruby
-FFNerd.player_list
+````term
+export FFNERD_API_KEY = 123456789
 ````
 
-Returns an array of players with attributes:
-
-````ruby
-player.player_id
-player.name
-player.position
-player.team
-````
+Set a class variable from your script. 
 
-Player Detail
-------------------------------
-
-````ruby
-player = FFNerd.player_detail(id)
-````
+```ruby
+FFNerd.api_key = 123456789
+```
 
-Returns a single player with attributes:
-````ruby
-player.id
-player.first_name
-player.last_name
-player.team
-player.position
-player.articles
-````
+API Resources
+===================
 
-<tt>player.articles</tt> is an array of articles:
+This gem supports all of Fantasy Football Nerd's Level 1 and Level 2 resources. Results are typically returned as an array of [ostructs](http://www.ruby-doc.org/stdlib-2.0/libdoc/ostruct/rdoc/OpenStruct.html) (which is basically a hash that you can access with "dot notation" as if it were an object instance variable). Fantasy Football Nerd returns keys in CamelCase, but that's not very Ruby like, so I've added snake_case attributes so that you can do ```player.displayName``` or ```player.display_name```, whichever suits your fancy. 
 
-````ruby
-article = player.articles.first
-article.title
-article.source
-article.published
-````
+Teams
+--------------------------
+Returns an array of teams. 
 
-Projections
----------------
+```ruby
+team = FFNerd.teams.first
+team.code        # "ARI"
+team.full_name   # "Arizona Cardinals"
+team.short_name  # "Arizona"
+```
 
-````ruby
-projections = FFNerd.projections(week)
-````
+Schedule
+--------------------------
+Returns an array of games. 
+
+```ruby
+game = FFNerd.schedule.first
+game.game_id         # "1"
+game.game_week       # "1"
+game.game_date       # "2013-09-05"
+game.away_team       # "BAL"
+game.home_team       # "DEN"
+```
+
+Players
+--------------------------
+Returns an array of players. 
+
+```ruby
+player = FFNerd.players.first
+player.player_id     # "2"
+player.active        # "1"
+player.jersey        # "3"
+player.lname         # "Anderson"
+player.fname         # "Derek"
+player.display_name  # "Derek Anderson"
+player.team          # "CAR"
+player.position      # "QB"
+player.height        # "6-6"
+player.weight        # "240"
+player.dob           # "1983-06-15"
+player.college       # "Oregon State"
+```
+
+Bye Weeks
+--------------------------
+Returns an array of the teams on bye for the given week. 
 
-Returns an array of players with attributes:
-````ruby
-player = projections.first
-player.id
-player.name
-player.team
-player.position
-player.rank
-player.projected_points #equivalent to player.projection.standard
-player.projection.week
-player.projection.standard
-player.projection.standard_low
-player.projection.standard_high
-player.projection.ppr
-player.projection.ppr_low
-player.projection.ppr_high
-````
+```ruby
+bye = FFNerd.byes(4).first
+bye.team         # "CAR"
+bye.bye_week     # "4"
+bye.display_name # "Carolina Panthers"
+```
 
 Injuries
----------------------
-
-````ruby
-injuries = FFNerd.injuries(week)
-````
+--------------------------
+Returns an array of injured players. Takes an optional parameter for the week number, or defaults to the current week. 
+
+```ruby
+injury = FFNerd.injuries(6)     # all injuries for week 6
+injury = FFNerd.injuries.first  # the first injury of the current week
+injury.week               # "1"
+injury.player_id          # "0"
+injury.player_name        # "Javier Arenas"
+injury.team               # "ARI"
+injury.position           # "CB"
+injury.injury             # "Hip"
+injury.practice_status    # "Full Practice"
+injury.game_status        # "Probable"
+injury.notes              # ""
+injury.last_update        # "2013-09-09"
+injury.practice_status_id # 0
+```
+
+
+Auction Values
+--------------------------
+Returns an array of draft auction values. 
+
+```ruby
+value = FFNerd.auction_values.first
+value.player_id     # "259"
+value.min_price     # "60"
+value.max_price     # "66"
+value.avg_price     # "63"
+value.display_name  # "Adrian Peterson"
+value.team          # "MIN"
+value.position      # "RB"
+```
+
+Current Week
+--------------------------
+Returns the current NFL week as an integer. 
 
-Returns an array of players with attributes:
+```ruby
+FFNerd.current_week  # 17
+```
 
-````ruby
-player = injuries.first
-player.id
-player.name
-player.team
-player.position
-player.injury.week
-player.injury.injury_desc
-player.injury.practice_status_desc
-player.injury.game_status_desc
-player.injury.last_update
-````
+Standard Draft Rankings
+--------------------------
+Returns an array of players according to their projected draft values based on standard scoring. In this example I'm looking at the fourth element in the array because the PPR and standard rankings don't deviate until then in the test data. 
+
+```ruby   
+player = FFNerd.standard_draft_rankings[3]
+player.playerId      # "1136"
+player.position      # "RB"
+player.displayName   # "C.J. Spiller"
+player.fname         # "C.J."
+player.lname         # "Spiller"
+player.team          # "BUF"
+player.byeWeek       # "12"
+player.nerdRank      # "6.140"
+player.positionRank  # "4"
+player.overallRank   # "4"
+```
+
+PPR Draft Rankings
+--------------------------
+Returns an array of players according to their projected draft values based on PPR scoring. 
+
+```ruby
+player = FFNerd.ppr_draft_rankings[3]
+player.player_id     # "454"
+player.position      # "WR"
+player.display_name  # "Calvin Johnson"
+player.fname         # "Calvin"
+player.lname         # "Johnson"
+player.team          # "DET"
+player.bye_week      # "9"
+player.nerd_rank     # "7.209"
+player.position_rank # "1"
+player.overall_rank  # "4"
+```
+
+Draft Projections
+--------------------------
+Returns an array of players with projected stats for a number of scoring categories. This data is useless once the season starts. 
+
+Must pass in a valid position of QB, RB, WR, TE, K, DEF.
+
+```ruby
+player = FFNerd.draft_projections('QB').first
+player.player_id         # "14"
+player.completions       # "422"
+player.attempts          # "640"
+player.passing_yards     # "4992"
+player.passing_td        # "40"
+player.passing_int       # "17"
+player.rush_yards        # "28"
+player.rush_td           # "1"
+player.fantasy_points    # "335"
+player.display_name      # "Drew Brees"
+player.team              # "NO"
+```
+
+Weekly Rankings
+--------------------------
+Returns an array of players with expected weekly fantasy points for both standard and PPR scoring. 
+
+Must requests a specific position: QB, RB, WR, TE, K, DEF. You can also send along the specific week number (1-17). If you omit a week, it defaults to the current week. 
+
+```ruby
+player = FFNerd.weekly_rankings('QB', 2).first
+player.week             # "2"
+player.player_id        # "14"
+player.name             # "Drew Brees"
+player.position         # "QB"
+player.team             # "NO"
+player.standard         # "24.80"
+player.standard_low     # "18.92"
+player.standard_high    # "32.00"
+player.ppr              # "24.80"
+player.ppr_low          # "18.92"
+player.ppr_high         # "32.00"
+player.injury           # nil
+player.practice_status  # nil
+player.game_status      # nil
+player.last_update      # nil
+```
+
+Weekly Projections
+--------------------------
+Returns an array of players with expected weekly values for each scoring category. 
+
+Must requests a specific position: QB, RB, WR, TE, K (But *NOT DEF!*). You can also send along the specific week number (1-17). If you omit a week, it defaults to the current week. 
+
+```ruby
+player = FFNerd.weekly_projections('QB', 1).first
+player.week             # "1"
+player.player_id        # "14"
+player.position         # "QB"
+player.pass_att         # "39.0"
+player.pass_cmp         # "25.0"
+player.pass_yds         # "317.0"
+player.pass_td          # "2.0"
+player.pass_int         # "1.0"
+player.rush_att         # "1.0"
+player.rush_yds         # "1.0"
+player.rush_td          # "0.0"
+player.fumbles_lost     # "0.0"
+player.receptions       # "0.0"
+player.rec_yds          # "0.0"
+player.rec_td           # "0.0"
+player.fg               # "0.0"
+player.fg_att           # "0.0"
+player.xp               # "0.0"
+player.def_int          # "0.0"
+player.def_fr           # "0.0"
+player.def_ff           # "0.0"
+player.def_sack         # "0.0"
+player.def_td           # "0.0"
+player.def_ret_td       # "0.0"
+player.def_safety       # "0.0"
+player.def_pa           # "0.0"
+player.def_yds_allowed  # "0.0"
+player.display_name     # "Drew Brees"
+player.team             # "NO"
+```
 
-Still To Come
-------------------
-I'll be adding this in the near future:
+Tests
+===================
 
-* Better error reporting
-* Schedule
-* Draft Rankings
+Set your API key to "test" to access FFNerd's test feeds. This is useful if you're developing your app prior to the beginning of the season or if you'd like to have a static dataset that won't change as the season progresses. All of the Rspec tests here use the test feeds. Speaking of rspec... 
 
-Tests
-------------------
-The gem includes extensive RSpec tests.
+This gem includes RSpec tests and uses VCR to cache http responses. If you're going to contribute, please write some tests. 
 
 Contributors
 -----------------
-This gem was created by:
-
-Greg Baugues ([greg@baugues.com](mailto:greg@baugues.com))
+Greg Baugues ([greg@baugues.com](mailto:greg@baugues.com))<br/>
+[www.baugues.com](http://www.baugues.com)
 
 

data/lib/fantasy_football_nerd.rb

@@ -1,237 +1,92 @@
-require 'nokogiri'
-require 'open-uri'
-require 'hashie'
+require 'json'
+require 'ostruct'
+require 'fantasy_football_nerd/request.rb'
+require 'fantasy_football_nerd/util.rb'
 
-class FFNerd
+POSITIONS = %w{QB RB WR TE K DEF}
 
-  BASE_URL = "http://api.fantasyfootballnerd.com"
+class FFNerd
+  @@api_key = nil
 
-  #############################################################################
-  # URL Generators
-  # These methods generate the URLs that will be used for the API calls
-  # feed_url() does most of the heavy lifting
-  # the others are to make things easier on the developer
-  #############################################################################
+  extend Request
 
   def self.api_key
+    @@api_key ||= ENV['FFNERD_API_KEY']
+    raise 'API key not set' if @@api_key.nil?
     @@api_key
   end
 
-  def self.api_key=(api_key)
-    @@api_key = api_key
-  end
-
-  def self.feed_url(feed, params = {} )
-    raise "api_key not set" if @@api_key.nil?
-    middle =
-      case feed
-      when :schedule        then 'ffnScheduleXML.php'
-      when :projections     then 'ffnSitStartXML.php'
-      when :injuries        then 'ffnInjuriesXML.php'
-      when :all_players     then 'ffnPlayersXML.php'
-      when :player          then 'ffnPlayerDetailsXML.php'
-      end
-    url = "#{BASE_URL}/#{middle}?apiKey=#{@@api_key}"
-    params.each { |key, value| url += "&#{key}=#{value}" }
-    url
+  def self.api_key=(key)
+    @@api_key = key
   end
 
-  def self.player_url(player_id)
-    feed_url(:player, 'playerId' => 13)
+  def self.current_week
+    player = request_service('schedule', api_key)
+    player['currentWeek']
   end
 
-  def self.projections_url(position, week)
-    position = position.to_s.upcase
-    feed_url(:projections, 'week' => week, 'position' => position)
+  def self.ostruct_request(service_name, json_key, extras = [])
+    data = request_service(service_name, api_key, extras)[json_key]
+    data = data.values.flatten if data.is_a? Hash
+    data.collect { |i| OpenStruct.new(i.add_snakecase_keys) }
   end
 
-  def self.injuries_url(week)
-    feed_url(:injuries, 'week' => week)
+  def self.teams
+    ostruct_request('nfl-teams', 'NFLTeams')
   end
 
-  def self.player_list_url
-    feed_url(:all_players)
-  end
-
-
-  #############################################################################
-  # Resource retreiver
-  # Connect to the API resource using the Url builders and Nokogiri
-  #############################################################################
-
-  def self.get_resource(url)
-    Nokogiri::HTML(open(url))
+  def self.schedule
+    ostruct_request('schedule', 'Schedule')
   end
 
-  #############################################################################
-  # Player List
-  # Grabs a list of all players
-  #############################################################################
-
-
-  def self.player_list
-    players = []
-    url     = player_list_url
-    doc     = get_resource(url)
-    doc.css('player').each do |data|
-      player = Hashie::Mash.new
-      player.id = data.attr('playerid').to_i
-      player.name = data.attr('name')
-      player.position = data.attr('position')
-      player.team = data.attr('team')
-      players << player
-    end
-    players
+  def self.players
+    ostruct_request('players', 'Players')
   end
 
-  #############################################################################
-  # Player Detail
-  # grabs player detail and related news articles
-  #############################################################################
-
-
-  def self.player_detail(player_id)
-    player = Hashie::Mash.new
-    url = player_url(player_id)
-    doc = get_resource(url)
-    player.first_name = doc.css('playerdetails firstname').text
-    player.last_name  = doc.css('playerdetails lastname').text
-    player.team       = doc.css('playerdetails team').text
-    player.position   = doc.css('playerdetails position').text
-    player.articles   = []
-    parse_articles(doc).each { |article| player.articles << article }
-    player
+  def self.byes(week)
+    raise "Must include a bye week between 4 and 12" unless (4..12).include?(week)
+    ostruct_request('byes', "Bye Week #{week}")
   end
 
-  #used by self.player to get articles
-  def self.parse_articles(doc)
-    articles = []
-    doc.css('article').each do |data|
-      article = Hashie::Mash.new
-      article.title     = data.css('title').text
-      article.source    = data.css('source').text
-      article.published = Date.parse(data.css('published').text)
-      articles << article
-    end
-    articles
+  def self.injuries(week = nil)
+    extras = [week]
+    ostruct_request('injuries', 'Injuries', extras)
   end
 
-  #############################################################################
-  # Projections
-  # retrieves weekly projections
-  #############################################################################
-
-  def self.projections(week, position = :all)
-    projections = []
-    position    = position.to_s.upcase
-    url         = projections_url(position, week)
-    doc         = get_resource(url)
-    doc.css('player').each do |data|
-      player = Hashie::Mash.new
-      player.name             = data.attr('name')
-      player.projected_points = data.attr('projectedpoints').to_f
-      player.team             = data.attr('team')
-      player.position         = data.attr('position')
-      player.id               = data.attr('playerid').to_i
-      player.rank             = data.attr('rank').to_i
-
-      #create and population player.projection
-      player.projection       = Hashie::Mash.new
-      player.projection.week  = data.attr('week').to_i
-      projections_map.each do |attribute, xml|
-        player.projection[attribute] = data.css("projections #{xml}").text.to_f
-      end
-
-      projections << player
-    end
-    projections
+  def self.auction_values
+    ostruct_request('auction', 'AuctionValues')
   end
 
-  def self.projections_map
-    {
-      standard: 'standard',
-      standard_low: 'standardlow',
-      standard_high: 'standardhigh',
-      ppr: 'ppr',
-      ppr_low: 'pprlow',
-      ppr_high: 'pprhigh'
-    }
+  def self.standard_draft_rankings
+    ostruct_request('draft-rankings', 'DraftRankings')
   end
 
-  #############################################################################
-  # Injuries
-  # retrieves weekly injuries
-  #############################################################################
-
-
-  def self.injuries(week)
-    players = []
-    url = injuries_url(week)
-    doc = get_resource(url)
-    #puts doc.css('injury')
-    doc.css('injury').each do |data|
-      player = Hashie::Mash.new
-
-      injury_player_data_map.each do |attribute, xml|
-        player[attribute] = data.css(xml).text
-      end
-
-      player.injury = Hashie::Mash.new
-      injury_data_map.each do |attribute, xml|
-        player.injury[attribute] = data.css(xml).text
-      end
-
-      #convert to more appropriate data types
-      player.id  = player.id.to_i
-      player.injury.week  = player.injury.week.to_i
-      player.injury.last_update = Date.parse(player.injury.last_update)
-
-      players << player
-    end
-    players
+  def self.ppr_draft_rankings
+    #appended a 1 to url for ppr rankings
+    ostruct_request('draft-rankings', 'DraftRankings', '1')
   end
 
-
-  def self.injury_data_map
-    {
-      week: 'week',
-      injury_desc: 'injurydesc',
-      practice_status_desc: 'practicestatusdesc',
-      game_status_desc: 'gamestatusdesc',
-      last_update: 'lastupdate'
-    }
+  def self.draft_projections(position)
+    raise "Must pass in a valid position" unless POSITIONS.include?(position)
+    ostruct_request('draft-projections', 'DraftProjections', [position])
   end
 
-  def self.injury_player_data_map
-    {
-      id: 'playerid',
-      name: 'playername',
-      team: 'team',
-      position: 'position'
-    }
+  def self.weekly_rankings(position, week = nil)
+    raise "Must pass in a valid position" unless POSITIONS.include?(position)
+    raise "Your (optional) week must be between 1 and 17" if week && !(1..17).include?(week)
+    week ||= current_week
+    extras = [position, week, 1]
+    ostruct_request('weekly-rankings', 'Rankings', extras)
   end
 
-  #############################################################################
-  # players
-  # The one method to rule them all
-  #############################################################################
-
-  def self.players(week, position = :all)
-    players = {}
-
-    FFNerd.projections(week).each do |player|
-      player.injured = false
-      players[player.id] = player
-    end
-
-    FFNerd.injuries(week).each do |player|
-      raise if players[player.id].nil?
-      players[player.id].injured = true
-      players[player.id].injury = player.injury
-    end
-
-    players.values
+  def self.weekly_projections(position, week = nil)
+    #FFNerd defaults to current week if week is left blank
+    raise "Weekly projections don't include DEF (but you can find those values in weekly rankings)" if position == "DEF"
+    raise "Must pass in a valid position" unless POSITIONS.include?(position)
+    raise "Your (optional) week must be between 1 and 17" if week && !(1..17).include?(week)
+    week ||= current_week
+    extras = [position, week]
+    ostruct_request('weekly-projections', 'Projections', extras)
   end
 
-
-end
+end