nba 0.1.1 → 0.2.0

data/lib/nba/league_dash_lineups.rb

@@ -0,0 +1,177 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league_dash_lineup_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide lineup statistics
+  #
+  # @api public
+  module LeagueDashLineups
+    # Result set name for lineups
+    # @return [String] the result set name
+    LINEUPS = "Lineups".freeze
+
+    # Regular season type constant
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Playoffs season type constant
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per game mode constant
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Totals mode constant
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Per 100 possessions mode constant
+    # @return [String] the per mode
+    PER_100 = "Per100Possessions".freeze
+
+    # Group quantity for 5-man lineups
+    # @return [Integer] the group quantity
+    FIVE_MAN = 5
+
+    # Group quantity for 4-man lineups
+    # @return [Integer] the group quantity
+    FOUR_MAN = 4
+
+    # Group quantity for 3-man lineups
+    # @return [Integer] the group quantity
+    THREE_MAN = 3
+
+    # Group quantity for 2-man lineups
+    # @return [Integer] the group quantity
+    TWO_MAN = 2
+
+    # Retrieves all league-wide lineup statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueDashLineups.all(season: 2024)
+    #   stats.first.group_name #=> "S. Curry - K. Thompson - ..."
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param group_quantity [Integer] the lineup size
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of lineup statistics
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME,
+      group_quantity: FIVE_MAN, client: CLIENT)
+      path = build_path(season, season_type: season_type, per_mode: per_mode, group_quantity: group_quantity)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API request path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, opts)
+      season_str = Utils.format_season(season)
+      "leaguedashlineups?LeagueID=00&Season=#{season_str}&SeasonType=#{opts.fetch(:season_type)}" \
+        "&PerMode=#{opts.fetch(:per_mode)}&GroupQuantity=#{opts.fetch(:group_quantity)}" \
+        "&MeasureType=Base&PlusMinus=N&PaceAdjust=N&Rank=N"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into stat objects
+    #
+    # @api private
+    # @return [Collection] collection of lineup stats
+    def self.parse_response(response)
+      return Collection.new if response.nil? || response.empty?
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      build_stats(result_set)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set by name
+    #
+    # @api private
+    # @return [Hash, nil] the result set hash or nil if not found
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(LINEUPS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds stats collection from result set
+    #
+    # @api private
+    # @return [Collection] the stats collection
+    def self.build_stats(result_set)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      Collection.new(rows.map { |row| build_stat(headers.zip(row).to_h) })
+    end
+    private_class_method :build_stats
+
+    # Builds a single stat object from API data
+    #
+    # @api private
+    # @return [LeagueDashLineupStat] the stat object
+    def self.build_stat(data)
+      LeagueDashLineupStat.new(**identity_info(data), **record_info(data), **shooting_info(data),
+        **counting_info(data))
+    end
+    private_class_method :build_stat
+
+    # Extracts identity information from data
+    #
+    # @api private
+    # @return [Hash] the identity information hash
+    def self.identity_info(data)
+      {group_set: data["GROUP_SET"], group_id: data["GROUP_ID"],
+       group_name: data["GROUP_NAME"], team_id: data["TEAM_ID"],
+       team_abbreviation: data["TEAM_ABBREVIATION"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts record information from data
+    #
+    # @api private
+    # @return [Hash] the record information hash
+    def self.record_info(data)
+      {gp: data["GP"], w: data["W"], l: data["L"],
+       w_pct: data["W_PCT"], min: data["MIN"]}
+    end
+    private_class_method :record_info
+
+    # Extracts shooting information from data
+    #
+    # @api private
+    # @return [Hash] the shooting information hash
+    def self.shooting_info(data)
+      {fgm: data["FGM"], fga: data["FGA"], fg_pct: data["FG_PCT"],
+       fg3m: data["FG3M"], fg3a: data["FG3A"], fg3_pct: data["FG3_PCT"],
+       ftm: data["FTM"], fta: data["FTA"], ft_pct: data["FT_PCT"]}
+    end
+    private_class_method :shooting_info
+
+    # Extracts counting information from data
+    #
+    # @api private
+    # @return [Hash] the counting information hash
+    def self.counting_info(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], tov: data["TOV"], stl: data["STL"],
+       blk: data["BLK"], blka: data["BLKA"], pf: data["PF"],
+       pfd: data["PFD"], pts: data["PTS"], plus_minus: data["PLUS_MINUS"]}
+    end
+    private_class_method :counting_info
+  end
+end

data/lib/nba/league_dash_opp_pt_shot.rb

@@ -0,0 +1,150 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league_dash_team_pt_shot_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide opponent tracking shot statistics (defensive)
+  #
+  # @api public
+  module LeagueDashOppPtShot
+    # Result set name for league dash opponent PT shots
+    # @return [String] the result set name
+    LEAGUE_DASH_PT_SHOTS = "LeagueDashPTShots".freeze
+
+    # Regular season type constant
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Playoffs season type constant
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per game mode constant
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Totals mode constant
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Retrieves all league-wide opponent tracking shot statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueDashOppPtShot.all(season: 2024)
+    #   stats.first.fg_pct #=> 0.472
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of opponent tracking shot statistics
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME, client: CLIENT)
+      path = build_path(season, season_type: season_type, per_mode: per_mode)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API request path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, opts)
+      season_str = Utils.format_season(season)
+      "leaguedashoppptshot?LeagueID=00&Season=#{season_str}" \
+        "&SeasonType=#{opts.fetch(:season_type)}&PerMode=#{opts.fetch(:per_mode)}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into stat objects
+    #
+    # @api private
+    # @return [Collection] collection of opponent PT shot stats
+    def self.parse_response(response)
+      return Collection.new if response.nil? || response.empty?
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      build_stats(result_set)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set by name
+    #
+    # @api private
+    # @return [Hash, nil] the result set hash or nil if not found
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(LEAGUE_DASH_PT_SHOTS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds stats collection from result set
+    #
+    # @api private
+    # @return [Collection] the stats collection
+    def self.build_stats(result_set)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      Collection.new(rows.map { |row| build_stat(headers.zip(row).to_h) })
+    end
+    private_class_method :build_stats
+
+    # Builds a single stat object from API data
+    #
+    # @api private
+    # @return [LeagueDashTeamPtShotStat] the stat object
+    def self.build_stat(data)
+      LeagueDashTeamPtShotStat.new(**identity_info(data), **shooting_info(data), **two_point_info(data),
+        **three_point_info(data))
+    end
+    private_class_method :build_stat
+
+    # Extracts identity information from data
+    #
+    # @api private
+    # @return [Hash] the identity information hash
+    def self.identity_info(data)
+      {team_id: data["TEAM_ID"], team_name: data["TEAM_NAME"],
+       team_abbreviation: data["TEAM_ABBREVIATION"], gp: data["GP"], g: data["G"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts shooting information from data
+    #
+    # @api private
+    # @return [Hash] the shooting information hash
+    def self.shooting_info(data)
+      {fga_frequency: data["FGA_FREQUENCY"], fgm: data["FGM"],
+       fga: data["FGA"], fg_pct: data["FG_PCT"], efg_pct: data["EFG_PCT"]}
+    end
+    private_class_method :shooting_info
+
+    # Extracts 2-point shooting information from data
+    #
+    # @api private
+    # @return [Hash] the 2-point shooting information hash
+    def self.two_point_info(data)
+      {fg2a_frequency: data["FG2A_FREQUENCY"], fg2m: data["FG2M"],
+       fg2a: data["FG2A"], fg2_pct: data["FG2_PCT"]}
+    end
+    private_class_method :two_point_info
+
+    # Extracts 3-point shooting information from data
+    #
+    # @api private
+    # @return [Hash] the 3-point shooting information hash
+    def self.three_point_info(data)
+      {fg3a_frequency: data["FG3A_FREQUENCY"], fg3m: data["FG3M"],
+       fg3a: data["FG3A"], fg3_pct: data["FG3_PCT"]}
+    end
+    private_class_method :three_point_info
+  end
+end

data/lib/nba/league_dash_player_bio_stat.rb

@@ -0,0 +1,217 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+require_relative "teams"
+
+module NBA
+  # Represents league-wide player biographical statistics
+  #
+  # @api public
+  class LeagueDashPlayerBioStat < Shale::Mapper
+    include Equalizer.new(:player_id, :team_id)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     stat.player_id #=> 201939
+    #   @return [Integer, nil] the player's ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name
+    #   Returns the player name
+    #   @api public
+    #   @example
+    #     stat.player_name #=> "Stephen Curry"
+    #   @return [String, nil] the player's name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.team_id #=> 1610612744
+    #   @return [Integer, nil] the team's ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_abbreviation
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     stat.team_abbreviation #=> "GSW"
+    #   @return [String, nil] the team's abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] age
+    #   Returns the player's age
+    #   @api public
+    #   @example
+    #     stat.age #=> 36
+    #   @return [Float, nil] the player's age
+    attribute :age, Shale::Type::Float
+
+    # @!attribute [rw] player_height
+    #   Returns the player's height as a formatted string
+    #   @api public
+    #   @example
+    #     stat.player_height #=> "6-2"
+    #   @return [String, nil] the player's height
+    attribute :player_height, Shale::Type::String
+
+    # @!attribute [rw] player_height_inches
+    #   Returns the player's height in inches
+    #   @api public
+    #   @example
+    #     stat.player_height_inches #=> 74
+    #   @return [Integer, nil] the player's height in inches
+    attribute :player_height_inches, Shale::Type::Integer
+
+    # @!attribute [rw] player_weight
+    #   Returns the player's weight in pounds
+    #   @api public
+    #   @example
+    #     stat.player_weight #=> 185
+    #   @return [Integer, nil] the player's weight
+    attribute :player_weight, Shale::Type::Integer
+
+    # @!attribute [rw] college
+    #   Returns the player's college
+    #   @api public
+    #   @example
+    #     stat.college #=> "Davidson"
+    #   @return [String, nil] the player's college
+    attribute :college, Shale::Type::String
+
+    # @!attribute [rw] country
+    #   Returns the player's country
+    #   @api public
+    #   @example
+    #     stat.country #=> "USA"
+    #   @return [String, nil] the player's country
+    attribute :country, Shale::Type::String
+
+    # @!attribute [rw] draft_year
+    #   Returns the player's draft year
+    #   @api public
+    #   @example
+    #     stat.draft_year #=> "2009"
+    #   @return [String, nil] the player's draft year
+    attribute :draft_year, Shale::Type::String
+
+    # @!attribute [rw] draft_round
+    #   Returns the player's draft round
+    #   @api public
+    #   @example
+    #     stat.draft_round #=> "1"
+    #   @return [String, nil] the player's draft round
+    attribute :draft_round, Shale::Type::String
+
+    # @!attribute [rw] draft_number
+    #   Returns the player's draft number
+    #   @api public
+    #   @example
+    #     stat.draft_number #=> "7"
+    #   @return [String, nil] the player's draft number
+    attribute :draft_number, Shale::Type::String
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 74
+    #   @return [Integer, nil] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] pts
+    #   Returns points per game
+    #   @api public
+    #   @example
+    #     stat.pts #=> 26.4
+    #   @return [Float, nil] points per game
+    attribute :pts, Shale::Type::Float
+
+    # @!attribute [rw] reb
+    #   Returns rebounds per game
+    #   @api public
+    #   @example
+    #     stat.reb #=> 5.2
+    #   @return [Float, nil] rebounds per game
+    attribute :reb, Shale::Type::Float
+
+    # @!attribute [rw] ast
+    #   Returns assists per game
+    #   @api public
+    #   @example
+    #     stat.ast #=> 6.1
+    #   @return [Float, nil] assists per game
+    attribute :ast, Shale::Type::Float
+
+    # @!attribute [rw] net_rating
+    #   Returns net rating
+    #   @api public
+    #   @example
+    #     stat.net_rating #=> 8.5
+    #   @return [Float, nil] net rating
+    attribute :net_rating, Shale::Type::Float
+
+    # @!attribute [rw] oreb_pct
+    #   Returns offensive rebound percentage
+    #   @api public
+    #   @example
+    #     stat.oreb_pct #=> 0.025
+    #   @return [Float, nil] offensive rebound percentage
+    attribute :oreb_pct, Shale::Type::Float
+
+    # @!attribute [rw] dreb_pct
+    #   Returns defensive rebound percentage
+    #   @api public
+    #   @example
+    #     stat.dreb_pct #=> 0.112
+    #   @return [Float, nil] defensive rebound percentage
+    attribute :dreb_pct, Shale::Type::Float
+
+    # @!attribute [rw] usg_pct
+    #   Returns usage percentage
+    #   @api public
+    #   @example
+    #     stat.usg_pct #=> 0.298
+    #   @return [Float, nil] usage percentage
+    attribute :usg_pct, Shale::Type::Float
+
+    # @!attribute [rw] ts_pct
+    #   Returns true shooting percentage
+    #   @api public
+    #   @example
+    #     stat.ts_pct #=> 0.621
+    #   @return [Float, nil] true shooting percentage
+    attribute :ts_pct, Shale::Type::Float
+
+    # @!attribute [rw] ast_pct
+    #   Returns assist percentage
+    #   @api public
+    #   @example
+    #     stat.ast_pct #=> 0.312
+    #   @return [Float, nil] assist percentage
+    attribute :ast_pct, Shale::Type::Float
+
+    # Returns the player
+    #
+    # @api public
+    # @example
+    #   stat.player #=> #<NBA::Player id=201939 ...>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team id=1610612744 ...>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end

data/lib/nba/league_dash_player_bio_stats.rb

@@ -0,0 +1,164 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league_dash_player_bio_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide player biographical statistics
+  #
+  # @api public
+  module LeagueDashPlayerBioStats
+    # Result set name for league dash player bio stats
+    # @return [String] the result set name
+    LEAGUE_DASH_PLAYER_BIO_STATS = "LeagueDashPlayerBioStats".freeze
+
+    # Regular season type constant
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Playoffs season type constant
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per game mode constant
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Totals mode constant
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Retrieves all league-wide player biographical statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueDashPlayerBioStats.all(season: 2024)
+    #   stats.first.college #=> "Davidson"
+    # @param season [Integer] the season year
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of player biographical statistics
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME, client: CLIENT)
+      path = build_path(season, season_type: season_type, per_mode: per_mode)
+      response = client.get(path)
+      parse_response(response)
+    end
+
+    # Builds the API request path
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_path(season, opts)
+      season_str = Utils.format_season(season)
+      "leaguedashplayerbiostats?LeagueID=00&Season=#{season_str}" \
+        "&SeasonType=#{opts.fetch(:season_type)}&PerMode=#{opts.fetch(:per_mode)}"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into stat objects
+    #
+    # @api private
+    # @return [Collection] collection of player bio stats
+    def self.parse_response(response)
+      return Collection.new if response.nil? || response.empty?
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      build_stats(result_set)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set by name
+    #
+    # @api private
+    # @return [Hash, nil] the result set hash or nil if not found
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(LEAGUE_DASH_PLAYER_BIO_STATS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds stats collection from result set
+    #
+    # @api private
+    # @return [Collection] the stats collection
+    def self.build_stats(result_set)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      Collection.new(rows.map { |row| build_stat(headers.zip(row).to_h) })
+    end
+    private_class_method :build_stats
+
+    # Builds a single stat object from API data
+    #
+    # @api private
+    # @return [LeagueDashPlayerBioStat] the stat object
+    def self.build_stat(data)
+      LeagueDashPlayerBioStat.new(**identity_info(data), **physical_info(data), **draft_info(data),
+        **stat_info(data), **advanced_info(data))
+    end
+    private_class_method :build_stat
+
+    # Extracts identity information from data
+    #
+    # @api private
+    # @return [Hash] the identity information hash
+    def self.identity_info(data)
+      {player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       team_id: data["TEAM_ID"], team_abbreviation: data["TEAM_ABBREVIATION"],
+       age: data["AGE"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts physical information from data
+    #
+    # @api private
+    # @return [Hash] the physical information hash
+    def self.physical_info(data)
+      {player_height: data["PLAYER_HEIGHT"],
+       player_height_inches: data["PLAYER_HEIGHT_INCHES"],
+       player_weight: data["PLAYER_WEIGHT"], college: data["COLLEGE"],
+       country: data["COUNTRY"]}
+    end
+    private_class_method :physical_info
+
+    # Extracts draft information from data
+    #
+    # @api private
+    # @return [Hash] the draft information hash
+    def self.draft_info(data)
+      {draft_year: data["DRAFT_YEAR"], draft_round: data["DRAFT_ROUND"],
+       draft_number: data["DRAFT_NUMBER"]}
+    end
+    private_class_method :draft_info
+
+    # Extracts basic stat information from data
+    #
+    # @api private
+    # @return [Hash] the stat information hash
+    def self.stat_info(data)
+      {gp: data["GP"], pts: data["PTS"], reb: data["REB"],
+       ast: data["AST"]}
+    end
+    private_class_method :stat_info
+
+    # Extracts advanced stat information from data
+    #
+    # @api private
+    # @return [Hash] the advanced stat information hash
+    def self.advanced_info(data)
+      {net_rating: data["NET_RATING"], oreb_pct: data["OREB_PCT"],
+       dreb_pct: data["DREB_PCT"], usg_pct: data["USG_PCT"],
+       ts_pct: data["TS_PCT"], ast_pct: data["AST_PCT"]}
+    end
+    private_class_method :advanced_info
+  end
+end