nba 0.1.1 → 0.2.0

data/lib/nba/box_score_usage_team_stat.rb

@@ -0,0 +1,221 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a team's usage box score statistics for a game
+  class BoxScoreUsageTeamStat < 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] usg_pct
+    #   Returns usage percentage
+    #   @api public
+    #   @example
+    #     stat.usg_pct #=> 1.0
+    #   @return [Float] usage percentage
+    attribute :usg_pct, Shale::Type::Float
+
+    # @!attribute [rw] pct_fgm
+    #   Returns percentage of field goals made
+    #   @api public
+    #   @example
+    #     stat.pct_fgm #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_fgm, Shale::Type::Float
+
+    # @!attribute [rw] pct_fga
+    #   Returns percentage of field goals attempted
+    #   @api public
+    #   @example
+    #     stat.pct_fga #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_fga, Shale::Type::Float
+
+    # @!attribute [rw] pct_fg3m
+    #   Returns percentage of 3-pointers made
+    #   @api public
+    #   @example
+    #     stat.pct_fg3m #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_fg3m, Shale::Type::Float
+
+    # @!attribute [rw] pct_fg3a
+    #   Returns percentage of 3-pointers attempted
+    #   @api public
+    #   @example
+    #     stat.pct_fg3a #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_fg3a, Shale::Type::Float
+
+    # @!attribute [rw] pct_ftm
+    #   Returns percentage of free throws made
+    #   @api public
+    #   @example
+    #     stat.pct_ftm #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_ftm, Shale::Type::Float
+
+    # @!attribute [rw] pct_fta
+    #   Returns percentage of free throws attempted
+    #   @api public
+    #   @example
+    #     stat.pct_fta #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_fta, Shale::Type::Float
+
+    # @!attribute [rw] pct_oreb
+    #   Returns percentage of offensive rebounds
+    #   @api public
+    #   @example
+    #     stat.pct_oreb #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_oreb, Shale::Type::Float
+
+    # @!attribute [rw] pct_dreb
+    #   Returns percentage of defensive rebounds
+    #   @api public
+    #   @example
+    #     stat.pct_dreb #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_dreb, Shale::Type::Float
+
+    # @!attribute [rw] pct_reb
+    #   Returns percentage of total rebounds
+    #   @api public
+    #   @example
+    #     stat.pct_reb #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_reb, Shale::Type::Float
+
+    # @!attribute [rw] pct_ast
+    #   Returns percentage of assists
+    #   @api public
+    #   @example
+    #     stat.pct_ast #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_ast, Shale::Type::Float
+
+    # @!attribute [rw] pct_tov
+    #   Returns percentage of turnovers
+    #   @api public
+    #   @example
+    #     stat.pct_tov #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_tov, Shale::Type::Float
+
+    # @!attribute [rw] pct_stl
+    #   Returns percentage of steals
+    #   @api public
+    #   @example
+    #     stat.pct_stl #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_stl, Shale::Type::Float
+
+    # @!attribute [rw] pct_blk
+    #   Returns percentage of blocks
+    #   @api public
+    #   @example
+    #     stat.pct_blk #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_blk, Shale::Type::Float
+
+    # @!attribute [rw] pct_blka
+    #   Returns percentage of blocked attempts
+    #   @api public
+    #   @example
+    #     stat.pct_blka #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_blka, Shale::Type::Float
+
+    # @!attribute [rw] pct_pf
+    #   Returns percentage of personal fouls
+    #   @api public
+    #   @example
+    #     stat.pct_pf #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_pf, Shale::Type::Float
+
+    # @!attribute [rw] pct_pfd
+    #   Returns percentage of personal fouls drawn
+    #   @api public
+    #   @example
+    #     stat.pct_pfd #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_pfd, Shale::Type::Float
+
+    # @!attribute [rw] pct_pts
+    #   Returns percentage of points
+    #   @api public
+    #   @example
+    #     stat.pct_pts #=> 1.0
+    #   @return [Float] the percentage
+    attribute :pct_pts, 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_usage_v3.rb

@@ -0,0 +1,169 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "box_score_usage_player_stat"
+require_relative "box_score_usage_team_stat"
+require_relative "box_score_v3_helpers"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve usage box score statistics using V3 API
+  module BoxScoreUsageV3
+    # @return [String] JSON key for usage box score data
+    BOX_SCORE_KEY = "boxScoreUsage".freeze
+    # @return [String] JSON key for player statistics
+    PLAYER_STATS = "PlayerStats".freeze
+    # @return [String] JSON key for team statistics
+    TEAM_STATS = "TeamStats".freeze
+
+    # Retrieves usage player box score stats for a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScoreUsageV3.player_stats(game: "0022400001")
+    #   stats.each { |stat| puts "#{stat.player_name}: #{stat.usg_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 usage 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 usage team box score stats for a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScoreUsageV3.team_stats(game: "0022400001")
+    #   stats.each { |stat| puts "#{stat.team_abbreviation}: #{stat.usg_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 usage 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)
+      "boxscoreusagev3?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 [BoxScoreUsagePlayerStat] the player stat object
+    def self.build_player_stat(player, game_id)
+      stats = player.fetch("statistics", {})
+      BoxScoreUsagePlayerStat.new(
+        **BoxScoreV3Helpers.player_identity(player, game_id),
+        min: stats["minutes"],
+        **usage_stats(stats)
+      )
+    end
+    private_class_method :build_player_stat
+
+    # Builds a team stat object from raw data
+    # @api private
+    # @return [BoxScoreUsageTeamStat] the team stat object
+    def self.build_team_stat(team, game_id)
+      stats = team.fetch("statistics", {})
+      BoxScoreUsageTeamStat.new(
+        **BoxScoreV3Helpers.team_identity(team, game_id),
+        min: stats["minutes"],
+        **usage_stats(stats)
+      )
+    end
+    private_class_method :build_team_stat
+
+    # Extracts usage statistics from raw data
+    # @api private
+    # @return [Hash] usage statistics
+    def self.usage_stats(stats)
+      core_usage(stats).merge(shooting_usage(stats), other_usage(stats))
+    end
+    private_class_method :usage_stats
+
+    # Extracts core usage statistics from raw data
+    # @api private
+    # @return [Hash] core usage statistics
+    def self.core_usage(stats)
+      {
+        usg_pct: stats["usagePercentage"],
+        pct_fgm: stats["percentageFieldGoalsMade"],
+        pct_fga: stats["percentageFieldGoalsAttempted"],
+        pct_fg3m: stats["percentageThreePointersMade"],
+        pct_fg3a: stats["percentageThreePointersAttempted"],
+        pct_ftm: stats["percentageFreeThrowsMade"],
+        pct_fta: stats["percentageFreeThrowsAttempted"]
+      }
+    end
+    private_class_method :core_usage
+
+    # Extracts shooting usage statistics from raw data
+    # @api private
+    # @return [Hash] shooting usage statistics
+    def self.shooting_usage(stats)
+      {
+        pct_oreb: stats["percentageReboundsOffensive"],
+        pct_dreb: stats["percentageReboundsDefensive"],
+        pct_reb: stats["percentageReboundsTotal"],
+        pct_ast: stats["percentageAssists"],
+        pct_tov: stats["percentageTurnovers"]
+      }
+    end
+    private_class_method :shooting_usage
+
+    # Extracts other usage statistics from raw data
+    # @api private
+    # @return [Hash] other usage statistics
+    def self.other_usage(stats)
+      {
+        pct_stl: stats["percentageSteals"],
+        pct_blk: stats["percentageBlocks"],
+        pct_blka: stats["percentageBlocksAgainst"],
+        pct_pf: stats["percentageFoulsPersonal"],
+        pct_pfd: stats["percentageFoulsDrawn"],
+        pct_pts: stats["percentagePoints"]
+      }
+    end
+    private_class_method :other_usage
+  end
+end

data/lib/nba/box_score_v3_helpers.rb

@@ -0,0 +1,144 @@
+module NBA
+  # Shared helper methods for V3 box score modules
+  # @api private
+  module BoxScoreV3Helpers
+    # Extracts player identity attributes from V3 API format
+    # @api private
+    # @return [Hash] player identity attributes
+    def self.player_identity(player, game_id)
+      {game_id: game_id, team_id: player["teamId"],
+       team_abbreviation: player["teamTricode"],
+       team_city: player["teamCity"],
+       player_id: player["personId"],
+       player_name: build_player_name(player),
+       start_position: player["position"],
+       comment: player["comment"]}
+    end
+
+    # Extracts team identity attributes from V3 API format
+    # @api private
+    # @return [Hash] team identity attributes
+    def self.team_identity(team, game_id)
+      {game_id: game_id, team_id: team["teamId"],
+       team_name: team["teamName"],
+       team_abbreviation: team["teamTricode"],
+       team_city: team["teamCity"]}
+    end
+
+    # Builds player full name from first and family name
+    # @api private
+    # @param player [Hash] player data from V3 API
+    # @return [String] player full name
+    def self.build_player_name(player)
+      first = player["firstName"]
+      last = player["familyName"]
+      "#{first} #{last}".strip
+    end
+
+    # Extracts all players from box score data
+    # @api private
+    # @param data [Hash] parsed JSON response
+    # @param box_score_key [String] key to access box score data
+    # @return [Array, nil] array of player data or nil if not found
+    def self.extract_players(data, box_score_key)
+      box_score = data[box_score_key]
+      return unless box_score
+
+      home = box_score.dig("homeTeam", "players") || []
+      away = box_score.dig("awayTeam", "players") || []
+      home + away
+    end
+
+    # Extracts both teams from box score data
+    # @api private
+    # @param data [Hash] parsed JSON response
+    # @param box_score_key [String] key to access box score data
+    # @return [Array, nil] array of team data or nil if not found
+    def self.extract_teams(data, box_score_key)
+      box_score = data[box_score_key]
+      return unless box_score
+
+      [box_score["homeTeam"], box_score["awayTeam"]].compact
+    end
+
+    # Extracts shooting statistics from V3 API format
+    # @api private
+    # @return [Hash] shooting statistics
+    def self.shooting_stats(stats)
+      field_goal_stats(stats).merge(free_throw_stats(stats))
+    end
+
+    # Extracts field goal statistics from V3 API format
+    # @api private
+    # @param stats [Hash] statistics data from V3 API
+    # @return [Hash] field goal statistics
+    def self.field_goal_stats(stats)
+      {fgm: stats["fieldGoalsMade"], fga: stats["fieldGoalsAttempted"],
+       fg_pct: stats["fieldGoalsPercentage"], fg3m: stats["threePointersMade"],
+       fg3a: stats["threePointersAttempted"], fg3_pct: stats["threePointersPercentage"]}
+    end
+
+    # Extracts free throw statistics from V3 API format
+    # @api private
+    # @param stats [Hash] statistics data from V3 API
+    # @return [Hash] free throw statistics
+    def self.free_throw_stats(stats)
+      {ftm: stats["freeThrowsMade"], fta: stats["freeThrowsAttempted"],
+       ft_pct: stats["freeThrowsPercentage"]}
+    end
+
+    # Extracts counting statistics from V3 API format
+    # @api private
+    # @return [Hash] counting statistics
+    def self.counting_stats(stats)
+      rebound_stats(stats).merge(other_counting_stats(stats))
+    end
+
+    # Extracts rebound and assist statistics from V3 API format
+    # @api private
+    # @param stats [Hash] statistics data from V3 API
+    # @return [Hash] rebound and assist statistics
+    def self.rebound_stats(stats)
+      {oreb: stats["reboundsOffensive"], dreb: stats["reboundsDefensive"],
+       reb: stats["reboundsTotal"], ast: stats["assists"]}
+    end
+
+    # Extracts other counting statistics from V3 API format
+    # @api private
+    # @param stats [Hash] statistics data from V3 API
+    # @return [Hash] steals, blocks, turnovers, fouls, points, plus/minus
+    def self.other_counting_stats(stats)
+      {stl: stats["steals"], blk: stats["blocks"],
+       tov: stats["turnovers"], pf: stats["foulsPersonal"],
+       pts: stats["points"], plus_minus: stats["plusMinusPoints"]}
+    end
+
+    # Extracts advanced rating statistics from V3 API format
+    # @api private
+    # @return [Hash] rating statistics
+    def self.advanced_rating_stats(stats)
+      {e_off_rating: stats["estimatedOffensiveRating"], off_rating: stats["offensiveRating"],
+       e_def_rating: stats["estimatedDefensiveRating"], def_rating: stats["defensiveRating"],
+       e_net_rating: stats["estimatedNetRating"], net_rating: stats["netRating"]}
+    end
+
+    # Extracts advanced efficiency statistics from V3 API format
+    # @api private
+    # @return [Hash] efficiency statistics
+    def self.advanced_efficiency_stats(stats)
+      {ast_pct: stats["assistPercentage"], ast_tov: stats["assistToTurnover"],
+       ast_ratio: stats["assistRatio"], oreb_pct: stats["reboundsOffensivePercentage"],
+       dreb_pct: stats["reboundsDefensivePercentage"], reb_pct: stats["reboundsPercentage"],
+       tov_pct: stats["turnoverPercentage"], efg_pct: stats["effectiveFieldGoalPercentage"],
+       ts_pct: stats["trueShootingPercentage"], pie: stats["playerImpactEstimate"]}
+    end
+
+    # Extracts advanced tempo statistics from V3 API format
+    # @api private
+    # @return [Hash] tempo statistics
+    def self.advanced_tempo_stats(stats)
+      {e_pace: stats["estimatedPace"], pace: stats["pace"],
+       pace_per40: stats["pacePer40"], poss: stats["possessions"]}
+    end
+  end
+end