nba 0.1.1 → 0.2.0

data/lib/nba/box_score_scoring_player_stat.rb

@@ -0,0 +1,241 @@
+require "shale"
+require "equalizer"
+
+module NBA
+  # Represents a player's scoring box score statistics for a game
+  class BoxScoreScoringPlayerStat < Shale::Mapper
+    include Equalizer.new(:game_id, :player_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     stat.game_id #=> "0022400565"
+    #   @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 #=> "35:24"
+    #   @return [String] the minutes played
+    attribute :min, Shale::Type::String
+
+    # @!attribute [rw] pct_fga_2pt
+    #   Returns percentage of field goals from 2-point range
+    #   @api public
+    #   @example
+    #     stat.pct_fga_2pt #=> 0.45
+    #   @return [Float] the percentage
+    attribute :pct_fga_2pt, Shale::Type::Float
+
+    # @!attribute [rw] pct_fga_3pt
+    #   Returns percentage of field goals from 3-point range
+    #   @api public
+    #   @example
+    #     stat.pct_fga_3pt #=> 0.55
+    #   @return [Float] the percentage
+    attribute :pct_fga_3pt, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_2pt
+    #   Returns percentage of points from 2-point shots
+    #   @api public
+    #   @example
+    #     stat.pct_pts_2pt #=> 0.40
+    #   @return [Float] the percentage
+    attribute :pct_pts_2pt, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_2pt_mr
+    #   Returns percentage of points from mid-range 2-point shots
+    #   @api public
+    #   @example
+    #     stat.pct_pts_2pt_mr #=> 0.15
+    #   @return [Float] the percentage
+    attribute :pct_pts_2pt_mr, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_3pt
+    #   Returns percentage of points from 3-point shots
+    #   @api public
+    #   @example
+    #     stat.pct_pts_3pt #=> 0.50
+    #   @return [Float] the percentage
+    attribute :pct_pts_3pt, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_fb
+    #   Returns percentage of points from fast break
+    #   @api public
+    #   @example
+    #     stat.pct_pts_fb #=> 0.12
+    #   @return [Float] the percentage
+    attribute :pct_pts_fb, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_ft
+    #   Returns percentage of points from free throws
+    #   @api public
+    #   @example
+    #     stat.pct_pts_ft #=> 0.10
+    #   @return [Float] the percentage
+    attribute :pct_pts_ft, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_off_tov
+    #   Returns percentage of points off turnovers
+    #   @api public
+    #   @example
+    #     stat.pct_pts_off_tov #=> 0.18
+    #   @return [Float] the percentage
+    attribute :pct_pts_off_tov, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_paint
+    #   Returns percentage of points in the paint
+    #   @api public
+    #   @example
+    #     stat.pct_pts_paint #=> 0.35
+    #   @return [Float] the percentage
+    attribute :pct_pts_paint, Shale::Type::Float
+
+    # @!attribute [rw] pct_ast_2pm
+    #   Returns percentage of 2-point makes that were assisted
+    #   @api public
+    #   @example
+    #     stat.pct_ast_2pm #=> 0.65
+    #   @return [Float] the percentage
+    attribute :pct_ast_2pm, Shale::Type::Float
+
+    # @!attribute [rw] pct_uast_2pm
+    #   Returns percentage of 2-point makes that were unassisted
+    #   @api public
+    #   @example
+    #     stat.pct_uast_2pm #=> 0.35
+    #   @return [Float] the percentage
+    attribute :pct_uast_2pm, Shale::Type::Float
+
+    # @!attribute [rw] pct_ast_3pm
+    #   Returns percentage of 3-point makes that were assisted
+    #   @api public
+    #   @example
+    #     stat.pct_ast_3pm #=> 0.85
+    #   @return [Float] the percentage
+    attribute :pct_ast_3pm, Shale::Type::Float
+
+    # @!attribute [rw] pct_uast_3pm
+    #   Returns percentage of 3-point makes that were unassisted
+    #   @api public
+    #   @example
+    #     stat.pct_uast_3pm #=> 0.15
+    #   @return [Float] the percentage
+    attribute :pct_uast_3pm, Shale::Type::Float
+
+    # @!attribute [rw] pct_ast_fgm
+    #   Returns percentage of field goal makes that were assisted
+    #   @api public
+    #   @example
+    #     stat.pct_ast_fgm #=> 0.75
+    #   @return [Float] the percentage
+    attribute :pct_ast_fgm, Shale::Type::Float
+
+    # @!attribute [rw] pct_uast_fgm
+    #   Returns percentage of field goal makes that were unassisted
+    #   @api public
+    #   @example
+    #     stat.pct_uast_fgm #=> 0.25
+    #   @return [Float] the percentage
+    attribute :pct_uast_fgm, 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_scoring_team_stat.rb

@@ -0,0 +1,197 @@
+require "shale"
+require "equalizer"
+
+module NBA
+  # Represents a team's scoring box score statistics for a game
+  class BoxScoreScoringTeamStat < Shale::Mapper
+    include Equalizer.new(:game_id, :team_id)
+
+    # @!attribute [rw] game_id
+    #   Returns the game ID
+    #   @api public
+    #   @example
+    #     stat.game_id #=> "0022400565"
+    #   @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] pct_fga_2pt
+    #   Returns percentage of field goals from 2-point range
+    #   @api public
+    #   @example
+    #     stat.pct_fga_2pt #=> 0.52
+    #   @return [Float] the percentage
+    attribute :pct_fga_2pt, Shale::Type::Float
+
+    # @!attribute [rw] pct_fga_3pt
+    #   Returns percentage of field goals from 3-point range
+    #   @api public
+    #   @example
+    #     stat.pct_fga_3pt #=> 0.48
+    #   @return [Float] the percentage
+    attribute :pct_fga_3pt, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_2pt
+    #   Returns percentage of points from 2-point shots
+    #   @api public
+    #   @example
+    #     stat.pct_pts_2pt #=> 0.42
+    #   @return [Float] the percentage
+    attribute :pct_pts_2pt, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_2pt_mr
+    #   Returns percentage of points from mid-range 2-point shots
+    #   @api public
+    #   @example
+    #     stat.pct_pts_2pt_mr #=> 0.18
+    #   @return [Float] the percentage
+    attribute :pct_pts_2pt_mr, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_3pt
+    #   Returns percentage of points from 3-point shots
+    #   @api public
+    #   @example
+    #     stat.pct_pts_3pt #=> 0.45
+    #   @return [Float] the percentage
+    attribute :pct_pts_3pt, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_fb
+    #   Returns percentage of points from fast break
+    #   @api public
+    #   @example
+    #     stat.pct_pts_fb #=> 0.15
+    #   @return [Float] the percentage
+    attribute :pct_pts_fb, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_ft
+    #   Returns percentage of points from free throws
+    #   @api public
+    #   @example
+    #     stat.pct_pts_ft #=> 0.13
+    #   @return [Float] the percentage
+    attribute :pct_pts_ft, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_off_tov
+    #   Returns percentage of points off turnovers
+    #   @api public
+    #   @example
+    #     stat.pct_pts_off_tov #=> 0.16
+    #   @return [Float] the percentage
+    attribute :pct_pts_off_tov, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts_paint
+    #   Returns percentage of points in the paint
+    #   @api public
+    #   @example
+    #     stat.pct_pts_paint #=> 0.38
+    #   @return [Float] the percentage
+    attribute :pct_pts_paint, Shale::Type::Float
+
+    # @!attribute [rw] pct_ast_2pm
+    #   Returns percentage of 2-point makes that were assisted
+    #   @api public
+    #   @example
+    #     stat.pct_ast_2pm #=> 0.70
+    #   @return [Float] the percentage
+    attribute :pct_ast_2pm, Shale::Type::Float
+
+    # @!attribute [rw] pct_uast_2pm
+    #   Returns percentage of 2-point makes that were unassisted
+    #   @api public
+    #   @example
+    #     stat.pct_uast_2pm #=> 0.30
+    #   @return [Float] the percentage
+    attribute :pct_uast_2pm, Shale::Type::Float
+
+    # @!attribute [rw] pct_ast_3pm
+    #   Returns percentage of 3-point makes that were assisted
+    #   @api public
+    #   @example
+    #     stat.pct_ast_3pm #=> 0.88
+    #   @return [Float] the percentage
+    attribute :pct_ast_3pm, Shale::Type::Float
+
+    # @!attribute [rw] pct_uast_3pm
+    #   Returns percentage of 3-point makes that were unassisted
+    #   @api public
+    #   @example
+    #     stat.pct_uast_3pm #=> 0.12
+    #   @return [Float] the percentage
+    attribute :pct_uast_3pm, Shale::Type::Float
+
+    # @!attribute [rw] pct_ast_fgm
+    #   Returns percentage of field goal makes that were assisted
+    #   @api public
+    #   @example
+    #     stat.pct_ast_fgm #=> 0.78
+    #   @return [Float] the percentage
+    attribute :pct_ast_fgm, Shale::Type::Float
+
+    # @!attribute [rw] pct_uast_fgm
+    #   Returns percentage of field goal makes that were unassisted
+    #   @api public
+    #   @example
+    #     stat.pct_uast_fgm #=> 0.22
+    #   @return [Float] the percentage
+    attribute :pct_uast_fgm, 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_scoring_v3.rb

@@ -0,0 +1,170 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "box_score_scoring_player_stat"
+require_relative "box_score_scoring_team_stat"
+require_relative "box_score_v3_helpers"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve scoring box score statistics using V3 API
+  module BoxScoreScoringV3
+    # @return [String] JSON key for scoring box score data
+    BOX_SCORE_KEY = "boxScoreScoring".freeze
+    # @return [String] JSON key for player statistics
+    PLAYER_STATS = "PlayerStats".freeze
+    # @return [String] JSON key for team statistics
+    TEAM_STATS = "TeamStats".freeze
+
+    # Retrieves scoring player box score stats for a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScoreScoringV3.player_stats(game: "0022400001")
+    #   stats.each { |stat| puts "#{stat.player_name}: #{stat.pct_pts_paint}" }
+    # @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 scoring 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 scoring team box score stats for a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScoreScoringV3.team_stats(game: "0022400001")
+    #   stats.each { |stat| puts "#{stat.team_abbreviation}: #{stat.pct_pts_paint}" }
+    # @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 scoring 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)
+      "boxscorescoringv3?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 [BoxScoreScoringPlayerStat] the player stat object
+    def self.build_player_stat(player, game_id)
+      stats = player.fetch("statistics", {})
+      BoxScoreScoringPlayerStat.new(
+        **BoxScoreV3Helpers.player_identity(player, game_id),
+        min: stats["minutes"],
+        **scoring_stats(stats)
+      )
+    end
+    private_class_method :build_player_stat
+
+    # Builds a team stat object from raw data
+    # @api private
+    # @return [BoxScoreScoringTeamStat] the team stat object
+    def self.build_team_stat(team, game_id)
+      stats = team.fetch("statistics", {})
+      BoxScoreScoringTeamStat.new(
+        **BoxScoreV3Helpers.team_identity(team, game_id),
+        min: stats["minutes"],
+        **scoring_stats(stats)
+      )
+    end
+    private_class_method :build_team_stat
+
+    # Extracts scoring statistics from raw data
+    # @api private
+    # @return [Hash] scoring statistics
+    def self.scoring_stats(stats)
+      shot_distribution(stats).merge(assist_distribution(stats))
+    end
+    private_class_method :scoring_stats
+
+    # Extracts shot distribution statistics from raw data
+    # @api private
+    # @return [Hash] shot distribution statistics
+    def self.shot_distribution(stats)
+      attempt_distribution(stats).merge(points_distribution(stats))
+    end
+    private_class_method :shot_distribution
+
+    # Extracts attempt distribution statistics from raw data
+    # @api private
+    # @return [Hash] attempt distribution statistics
+    def self.attempt_distribution(stats)
+      {pct_fga_2pt: stats["percentageFieldGoalsAttempted2pt"],
+       pct_fga_3pt: stats["percentageFieldGoalsAttempted3pt"],
+       pct_pts_2pt: stats["percentagePoints2pt"],
+       pct_pts_2pt_mr: stats["percentagePointsMidrange2pt"],
+       pct_pts_3pt: stats["percentagePoints3pt"]}
+    end
+    private_class_method :attempt_distribution
+
+    # Extracts points distribution statistics from raw data
+    # @api private
+    # @return [Hash] points distribution statistics
+    def self.points_distribution(stats)
+      {pct_pts_fb: stats["percentagePointsFastBreak"],
+       pct_pts_ft: stats["percentagePointsFreeThrow"],
+       pct_pts_off_tov: stats["percentagePointsOffTurnovers"],
+       pct_pts_paint: stats["percentagePointsPaint"]}
+    end
+    private_class_method :points_distribution
+
+    # Extracts assist distribution statistics from raw data
+    # @api private
+    # @return [Hash] assist distribution statistics
+    def self.assist_distribution(stats)
+      {
+        pct_ast_2pm: stats["percentageAssisted2pt"],
+        pct_uast_2pm: stats["percentageUnassisted2pt"],
+        pct_ast_3pm: stats["percentageAssisted3pt"],
+        pct_uast_3pm: stats["percentageUnassisted3pt"],
+        pct_ast_fgm: stats["percentageAssistedFieldGoals"],
+        pct_uast_fgm: stats["percentageUnassistedFieldGoals"]
+      }
+    end
+    private_class_method :assist_distribution
+  end
+end