nba 0.1.1 → 0.2.0

data/lib/nba/box_score_four_factors_player_stat.rb

@@ -0,0 +1,185 @@
+require "shale"
+require "equalizer"
+
+module NBA
+  # Represents a player's four factors box score statistics for a game
+  class BoxScoreFourFactorsPlayerStat < Shale::Mapper
+    include Equalizer.new(:game_id, :player_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     stat.game_id #=> "0022400350"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_abbreviation
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     stat.team_abbreviation #=> "GSW"
+    #   @return [String] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] team_city
+    #   Returns the team city
+    #   @api public
+    #   @example
+    #     stat.team_city #=> "Golden State"
+    #   @return [String] the team city
+    attribute :team_city, Shale::Type::String
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     stat.player_id #=> 201939
+    #   @return [Integer] the player 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] the player name
+    attribute :player_name, Shale::Type::String
+
+    # @!attribute [rw] start_position
+    #   Returns the starting position
+    #   @api public
+    #   @example
+    #     stat.start_position #=> "G"
+    #   @return [String] the starting position
+    attribute :start_position, Shale::Type::String
+
+    # @!attribute [rw] comment
+    #   Returns any comment (e.g., "DNP - Rest")
+    #   @api public
+    #   @example
+    #     stat.comment #=> "DNP - Rest"
+    #   @return [String] the comment
+    attribute :comment, Shale::Type::String
+
+    # @!attribute [rw] min
+    #   Returns minutes played
+    #   @api public
+    #   @example
+    #     stat.min #=> "32:45"
+    #   @return [String] the minutes played
+    attribute :min, Shale::Type::String
+
+    # @!attribute [rw] efg_pct
+    #   Returns effective field goal percentage
+    #   @api public
+    #   @example
+    #     stat.efg_pct #=> 0.625
+    #   @return [Float] the effective field goal percentage
+    attribute :efg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fta_rate
+    #   Returns free throw attempt rate
+    #   @api public
+    #   @example
+    #     stat.fta_rate #=> 0.45
+    #   @return [Float] the free throw attempt rate
+    attribute :fta_rate, Shale::Type::Float
+
+    # @!attribute [rw] tov_pct
+    #   Returns turnover percentage
+    #   @api public
+    #   @example
+    #     stat.tov_pct #=> 12.3
+    #   @return [Float] the turnover percentage
+    attribute :tov_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb_pct
+    #   Returns offensive rebound percentage
+    #   @api public
+    #   @example
+    #     stat.oreb_pct #=> 3.2
+    #   @return [Float] the offensive rebound percentage
+    attribute :oreb_pct, Shale::Type::Float
+
+    # @!attribute [rw] opp_efg_pct
+    #   Returns opponent effective field goal percentage
+    #   @api public
+    #   @example
+    #     stat.opp_efg_pct #=> 0.485
+    #   @return [Float] the opponent effective field goal percentage
+    attribute :opp_efg_pct, Shale::Type::Float
+
+    # @!attribute [rw] opp_fta_rate
+    #   Returns opponent free throw attempt rate
+    #   @api public
+    #   @example
+    #     stat.opp_fta_rate #=> 0.28
+    #   @return [Float] the opponent free throw attempt rate
+    attribute :opp_fta_rate, Shale::Type::Float
+
+    # @!attribute [rw] opp_tov_pct
+    #   Returns opponent turnover percentage
+    #   @api public
+    #   @example
+    #     stat.opp_tov_pct #=> 15.6
+    #   @return [Float] the opponent turnover percentage
+    attribute :opp_tov_pct, Shale::Type::Float
+
+    # @!attribute [rw] opp_oreb_pct
+    #   Returns opponent offensive rebound percentage
+    #   @api public
+    #   @example
+    #     stat.opp_oreb_pct #=> 22.5
+    #   @return [Float] the opponent offensive rebound percentage
+    attribute :opp_oreb_pct, Shale::Type::Float
+
+    # Returns the player object
+    #
+    # @api public
+    # @example
+    #   stat.player #=> #<NBA::Player>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    # Returns whether the player started the game
+    #
+    # @api public
+    # @example
+    #   stat.starter? #=> true
+    # @return [Boolean] true if the player started
+    def starter?
+      !start_position.nil? && !start_position.empty?
+    end
+
+    # Returns the game object for this box score
+    #
+    # @api public
+    # @example
+    #   stat.game #=> #<NBA::Game>
+    # @return [Game, nil] the game object
+    def game
+      Games.find(game_id)
+    end
+  end
+end

data/lib/nba/box_score_four_factors_team_stat.rb

@@ -0,0 +1,141 @@
+require "shale"
+require "equalizer"
+
+module NBA
+  # Represents a team's four factors box score statistics for a game
+  class BoxScoreFourFactorsTeamStat < Shale::Mapper
+    include Equalizer.new(:game_id, :team_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     stat.game_id #=> "0022400350"
+    #   @return [String] the game ID
+    attribute :game_id, Shale::Type::String
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     stat.team_id #=> 1610612744
+    #   @return [Integer] the team ID
+    attribute :team_id, Shale::Type::Integer
+
+    # @!attribute [rw] team_name
+    #   Returns the team name
+    #   @api public
+    #   @example
+    #     stat.team_name #=> "Warriors"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] team_abbreviation
+    #   Returns the team abbreviation
+    #   @api public
+    #   @example
+    #     stat.team_abbreviation #=> "GSW"
+    #   @return [String] the team abbreviation
+    attribute :team_abbreviation, Shale::Type::String
+
+    # @!attribute [rw] team_city
+    #   Returns the team city
+    #   @api public
+    #   @example
+    #     stat.team_city #=> "Golden State"
+    #   @return [String] the team city
+    attribute :team_city, Shale::Type::String
+
+    # @!attribute [rw] min
+    #   Returns total minutes played
+    #   @api public
+    #   @example
+    #     stat.min #=> "240:00"
+    #   @return [String] the minutes
+    attribute :min, Shale::Type::String
+
+    # @!attribute [rw] efg_pct
+    #   Returns effective field goal percentage
+    #   @api public
+    #   @example
+    #     stat.efg_pct #=> 0.562
+    #   @return [Float] the effective field goal percentage
+    attribute :efg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fta_rate
+    #   Returns free throw attempt rate
+    #   @api public
+    #   @example
+    #     stat.fta_rate #=> 0.284
+    #   @return [Float] the free throw attempt rate
+    attribute :fta_rate, Shale::Type::Float
+
+    # @!attribute [rw] tov_pct
+    #   Returns turnover percentage
+    #   @api public
+    #   @example
+    #     stat.tov_pct #=> 14.5
+    #   @return [Float] the turnover percentage
+    attribute :tov_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb_pct
+    #   Returns offensive rebound percentage
+    #   @api public
+    #   @example
+    #     stat.oreb_pct #=> 22.2
+    #   @return [Float] the offensive rebound percentage
+    attribute :oreb_pct, Shale::Type::Float
+
+    # @!attribute [rw] opp_efg_pct
+    #   Returns opponent effective field goal percentage
+    #   @api public
+    #   @example
+    #     stat.opp_efg_pct #=> 0.485
+    #   @return [Float] the opponent effective field goal percentage
+    attribute :opp_efg_pct, Shale::Type::Float
+
+    # @!attribute [rw] opp_fta_rate
+    #   Returns opponent free throw attempt rate
+    #   @api public
+    #   @example
+    #     stat.opp_fta_rate #=> 0.310
+    #   @return [Float] the opponent free throw attempt rate
+    attribute :opp_fta_rate, Shale::Type::Float
+
+    # @!attribute [rw] opp_tov_pct
+    #   Returns opponent turnover percentage
+    #   @api public
+    #   @example
+    #     stat.opp_tov_pct #=> 17.8
+    #   @return [Float] the opponent turnover percentage
+    attribute :opp_tov_pct, Shale::Type::Float
+
+    # @!attribute [rw] opp_oreb_pct
+    #   Returns opponent offensive rebound percentage
+    #   @api public
+    #   @example
+    #     stat.opp_oreb_pct #=> 20.5
+    #   @return [Float] the opponent offensive rebound percentage
+    attribute :opp_oreb_pct, Shale::Type::Float
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    # Returns the game object for this box score
+    #
+    # @api public
+    # @example
+    #   stat.game #=> #<NBA::Game>
+    # @return [Game, nil] the game object
+    def game
+      Games.find(game_id)
+    end
+  end
+end

data/lib/nba/box_score_four_factors_v3.rb

@@ -0,0 +1,133 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "box_score_four_factors_player_stat"
+require_relative "box_score_four_factors_team_stat"
+require_relative "box_score_v3_helpers"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve four factors box score statistics using V3 API
+  module BoxScoreFourFactorsV3
+    # @return [String] JSON key for four factors box score data
+    BOX_SCORE_KEY = "boxScoreFourFactors".freeze
+    # @return [String] JSON key for player statistics
+    PLAYER_STATS = "PlayerStats".freeze
+    # @return [String] JSON key for team statistics
+    TEAM_STATS = "TeamStats".freeze
+
+    # Retrieves four factors player box score stats for a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScoreFourFactorsV3.player_stats(game: "0022400001")
+    #   stats.each { |stat| puts "#{stat.player_name}: #{stat.efg_pct}" }
+    # @param game [String, Integer] the game ID
+    # @param start_period [Integer] the starting period
+    # @param end_period [Integer] the ending period
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of player four factors stats
+    def self.player_stats(game:, start_period: 0, end_period: 0, client: CLIENT)
+      game_id = Utils.extract_id(game)
+      response = client.get(build_path(game_id, start_period, end_period))
+      parse_player_response(response, game_id)
+    end
+
+    # Retrieves four factors team box score stats for a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScoreFourFactorsV3.team_stats(game: "0022400001")
+    #   stats.each { |stat| puts "#{stat.team_abbreviation}: #{stat.efg_pct}" }
+    # @param game [String, Integer] the game ID
+    # @param start_period [Integer] the starting period
+    # @param end_period [Integer] the ending period
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of team four factors stats
+    def self.team_stats(game:, start_period: 0, end_period: 0, client: CLIENT)
+      game_id = Utils.extract_id(game)
+      response = client.get(build_path(game_id, start_period, end_period))
+      parse_team_response(response, game_id)
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(game_id, start_period, end_period)
+      "boxscorefourfactorsv3?GameID=#{game_id}&StartPeriod=#{start_period}" \
+        "&EndPeriod=#{end_period}&StartRange=0&EndRange=0&RangeType=0"
+    end
+    private_class_method :build_path
+
+    # Parses the API response into player stat objects
+    # @api private
+    # @return [Collection] collection of player stats
+    def self.parse_player_response(response, game_id)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      players = BoxScoreV3Helpers.extract_players(data, BOX_SCORE_KEY)
+      return Collection.new unless players
+
+      Collection.new(players.map { |p| build_player_stat(p, game_id) })
+    end
+    private_class_method :parse_player_response
+
+    # Parses the API response into team stat objects
+    # @api private
+    # @return [Collection] collection of team stats
+    def self.parse_team_response(response, game_id)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      teams = BoxScoreV3Helpers.extract_teams(data, BOX_SCORE_KEY)
+      return Collection.new unless teams
+
+      Collection.new(teams.map { |t| build_team_stat(t, game_id) })
+    end
+    private_class_method :parse_team_response
+
+    # Builds a player stat object from raw data
+    # @api private
+    # @return [BoxScoreFourFactorsPlayerStat] the player stat object
+    def self.build_player_stat(player, game_id)
+      stats = player.fetch("statistics", {})
+      BoxScoreFourFactorsPlayerStat.new(
+        **BoxScoreV3Helpers.player_identity(player, game_id),
+        min: stats["minutes"],
+        **four_factors_stats(stats)
+      )
+    end
+    private_class_method :build_player_stat
+
+    # Builds a team stat object from raw data
+    # @api private
+    # @return [BoxScoreFourFactorsTeamStat] the team stat object
+    def self.build_team_stat(team, game_id)
+      stats = team.fetch("statistics", {})
+      BoxScoreFourFactorsTeamStat.new(
+        **BoxScoreV3Helpers.team_identity(team, game_id),
+        min: stats["minutes"],
+        **four_factors_stats(stats)
+      )
+    end
+    private_class_method :build_team_stat
+
+    # Extracts four factors statistics from raw data
+    # @api private
+    # @return [Hash] four factors statistics
+    def self.four_factors_stats(stats)
+      {
+        efg_pct: stats["effectiveFieldGoalPercentage"],
+        fta_rate: stats["freeThrowAttemptRate"],
+        tov_pct: stats["teamTurnoverPercentage"],
+        oreb_pct: stats["offensiveReboundPercentage"],
+        opp_efg_pct: stats["oppEffectiveFieldGoalPercentage"],
+        opp_fta_rate: stats["oppFreeThrowAttemptRate"],
+        opp_tov_pct: stats["oppTurnoverPercentage"],
+        opp_oreb_pct: stats["oppOffensiveReboundPercentage"]
+      }
+    end
+    private_class_method :four_factors_stats
+  end
+end

data/lib/nba/box_score_hustle.rb

@@ -0,0 +1,226 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "box_score_hustle_player_stat"
+require_relative "box_score_hustle_team_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve hustle statistics for a game
+  module BoxScoreHustle
+    # Result set name for player stats
+    # @return [String] the result set name
+    PLAYER_STATS = "PlayerStats".freeze
+
+    # Result set name for team stats
+    # @return [String] the result set name
+    TEAM_STATS = "TeamStats".freeze
+
+    # Retrieves hustle statistics for players in a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScoreHustle.player_stats(game: "0022400001")
+    #   stats.each { |s| puts "#{s.player_name}: #{s.deflections} deflections" }
+    # @param game [String, Game] the game ID or Game object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of player hustle stats
+    def self.player_stats(game:, client: CLIENT)
+      game_id = Utils.extract_id(game)
+      path = "boxscorehustlev2?GameID=#{game_id}"
+      response = client.get(path)
+      parse_player_response(response, game_id)
+    end
+
+    # Retrieves hustle statistics for teams in a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScoreHustle.team_stats(game: "0022400001")
+    #   stats.each { |s| puts "#{s.team_name}: #{s.deflections} deflections" }
+    # @param game [String, Game] the game ID or Game object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of team hustle stats
+    def self.team_stats(game:, client: CLIENT)
+      game_id = Utils.extract_id(game)
+      path = "boxscorehustlev2?GameID=#{game_id}"
+      response = client.get(path)
+      parse_team_response(response, game_id)
+    end
+
+    # Parses player stats response
+    # @api private
+    # @param response [String, nil] the JSON response
+    # @param game_id [String] the game ID
+    # @return [Collection] collection of player stats
+    def self.parse_player_response(response, game_id)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data, PLAYER_STATS)
+      return Collection.new unless result_set
+
+      build_player_stats(result_set, game_id)
+    end
+    private_class_method :parse_player_response
+
+    # Parses team stats response
+    # @api private
+    # @param response [String, nil] the JSON response
+    # @param game_id [String] the game ID
+    # @return [Collection] collection of team stats
+    def self.parse_team_response(response, game_id)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data, TEAM_STATS)
+      return Collection.new unless result_set
+
+      build_team_stats(result_set, game_id)
+    end
+    private_class_method :parse_team_response
+
+    # Finds a result set by name
+    # @api private
+    # @param data [Hash] the parsed JSON
+    # @param name [String] the result set name
+    # @return [Hash, nil] the result set
+    def self.find_result_set(data, name)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs.fetch("name").eql?(name) }
+    end
+    private_class_method :find_result_set
+
+    # Builds player stats collection
+    # @api private
+    # @param result_set [Hash] the result set
+    # @param game_id [String] the game ID
+    # @return [Collection] collection of player stats
+    def self.build_player_stats(result_set, game_id)
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      stats = rows.map { |row| build_player_stat(headers, row, game_id) }
+      Collection.new(stats)
+    end
+    private_class_method :build_player_stats
+
+    # Builds team stats collection
+    # @api private
+    # @param result_set [Hash] the result set
+    # @param game_id [String] the game ID
+    # @return [Collection] collection of team stats
+    def self.build_team_stats(result_set, game_id)
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      stats = rows.map { |row| build_team_stat(headers, row, game_id) }
+      Collection.new(stats)
+    end
+    private_class_method :build_team_stats
+
+    # Builds a player stat
+    # @api private
+    # @param headers [Array<String>] the headers
+    # @param row [Array] the row data
+    # @param game_id [String] the game ID
+    # @return [BoxScoreHustlePlayerStat] the player stat
+    def self.build_player_stat(headers, row, game_id)
+      data = headers.zip(row).to_h
+      BoxScoreHustlePlayerStat.new(**player_stat_attributes(data, game_id))
+    end
+    private_class_method :build_player_stat
+
+    # Builds a team stat
+    # @api private
+    # @param headers [Array<String>] the headers
+    # @param row [Array] the row data
+    # @param game_id [String] the game ID
+    # @return [BoxScoreHustleTeamStat] the team stat
+    def self.build_team_stat(headers, row, game_id)
+      data = headers.zip(row).to_h
+      BoxScoreHustleTeamStat.new(**team_stat_attributes(data, game_id))
+    end
+    private_class_method :build_team_stat
+
+    # Combines player stat attributes
+    # @api private
+    # @param data [Hash] the raw data
+    # @param game_id [String] the game ID
+    # @return [Hash] the combined attributes
+    def self.player_stat_attributes(data, game_id)
+      player_identity(data, game_id).merge(hustle_stats(data), loose_ball_stats(data), box_out_stats(data))
+    end
+    private_class_method :player_stat_attributes
+
+    # Combines team stat attributes
+    # @api private
+    # @param data [Hash] the raw data
+    # @param game_id [String] the game ID
+    # @return [Hash] the combined attributes
+    def self.team_stat_attributes(data, game_id)
+      team_identity(data, game_id).merge(hustle_stats(data), loose_ball_stats(data), box_out_stats(data))
+    end
+    private_class_method :team_stat_attributes
+
+    # Extracts player identity attributes
+    # @api private
+    # @param data [Hash] the raw data
+    # @param game_id [String] the game ID
+    # @return [Hash] identity attributes
+    def self.player_identity(data, game_id)
+      {game_id: game_id, team_id: data.fetch("TEAM_ID"), team_abbreviation: data.fetch("TEAM_ABBREVIATION"),
+       team_city: data.fetch("TEAM_CITY"), player_id: data.fetch("PLAYER_ID"), player_name: data.fetch("PLAYER_NAME"),
+       start_position: data.fetch("START_POSITION"), comment: data.fetch("COMMENT"), min: data.fetch("MIN"), pts: data.fetch("PTS")}
+    end
+    private_class_method :player_identity
+
+    # Extracts team identity attributes
+    # @api private
+    # @param data [Hash] the raw data
+    # @param game_id [String] the game ID
+    # @return [Hash] identity attributes
+    def self.team_identity(data, game_id)
+      {game_id: game_id, team_id: data.fetch("TEAM_ID"), team_name: data.fetch("TEAM_NAME"),
+       team_abbreviation: data.fetch("TEAM_ABBREVIATION"), team_city: data.fetch("TEAM_CITY"),
+       min: data.fetch("MIN"), pts: data.fetch("PTS")}
+    end
+    private_class_method :team_identity
+
+    # Extracts hustle stats
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] hustle stats
+    def self.hustle_stats(data)
+      {contested_shots: data.fetch("CONTESTED_SHOTS"), contested_shots_2pt: data.fetch("CONTESTED_SHOTS_2PT"),
+       contested_shots_3pt: data.fetch("CONTESTED_SHOTS_3PT"), deflections: data.fetch("DEFLECTIONS"),
+       charges_drawn: data.fetch("CHARGES_DRAWN"), screen_assists: data.fetch("SCREEN_ASSISTS"),
+       screen_ast_pts: data.fetch("SCREEN_AST_PTS")}
+    end
+    private_class_method :hustle_stats
+
+    # Extracts loose ball stats
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] loose ball stats
+    def self.loose_ball_stats(data)
+      {loose_balls_recovered: data.fetch("LOOSE_BALLS_RECOVERED"),
+       off_loose_balls_recovered: data.fetch("OFF_LOOSE_BALLS_RECOVERED"),
+       def_loose_balls_recovered: data.fetch("DEF_LOOSE_BALLS_RECOVERED")}
+    end
+    private_class_method :loose_ball_stats
+
+    # Extracts box out stats
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] box out stats
+    def self.box_out_stats(data)
+      {box_outs: data.fetch("BOX_OUTS"), off_box_outs: data.fetch("OFF_BOX_OUTS"), def_box_outs: data.fetch("DEF_BOX_OUTS")}
+    end
+    private_class_method :box_out_stats
+  end
+end