nba 0.1.1 → 0.2.0

data/lib/nba/box_score_player_stat.rb

@@ -0,0 +1,273 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents a player's box score statistics for a game
+  class BoxScorePlayerStat < 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] fgm
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 10
+    #   @return [Integer] field goals made
+    attribute :fgm, Shale::Type::Integer
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fga #=> 20
+    #   @return [Integer] field goals attempted
+    attribute :fga, Shale::Type::Integer
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.500
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns three-pointers made
+    #   @api public
+    #   @example
+    #     stat.fg3m #=> 5
+    #   @return [Integer] three-pointers made
+    attribute :fg3m, Shale::Type::Integer
+
+    # @!attribute [rw] fg3a
+    #   Returns three-pointers attempted
+    #   @api public
+    #   @example
+    #     stat.fg3a #=> 12
+    #   @return [Integer] three-pointers attempted
+    attribute :fg3a, Shale::Type::Integer
+
+    # @!attribute [rw] fg3_pct
+    #   Returns three-point percentage
+    #   @api public
+    #   @example
+    #     stat.fg3_pct #=> 0.417
+    #   @return [Float] three-point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns free throws made
+    #   @api public
+    #   @example
+    #     stat.ftm #=> 8
+    #   @return [Integer] free throws made
+    attribute :ftm, Shale::Type::Integer
+
+    # @!attribute [rw] fta
+    #   Returns free throws attempted
+    #   @api public
+    #   @example
+    #     stat.fta #=> 9
+    #   @return [Integer] free throws attempted
+    attribute :fta, Shale::Type::Integer
+
+    # @!attribute [rw] ft_pct
+    #   Returns free throw percentage
+    #   @api public
+    #   @example
+    #     stat.ft_pct #=> 0.889
+    #   @return [Float] free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns offensive rebounds
+    #   @api public
+    #   @example
+    #     stat.oreb #=> 2
+    #   @return [Integer] offensive rebounds
+    attribute :oreb, Shale::Type::Integer
+
+    # @!attribute [rw] dreb
+    #   Returns defensive rebounds
+    #   @api public
+    #   @example
+    #     stat.dreb #=> 6
+    #   @return [Integer] defensive rebounds
+    attribute :dreb, Shale::Type::Integer
+
+    # @!attribute [rw] reb
+    #   Returns total rebounds
+    #   @api public
+    #   @example
+    #     stat.reb #=> 8
+    #   @return [Integer] total rebounds
+    attribute :reb, Shale::Type::Integer
+
+    # @!attribute [rw] ast
+    #   Returns assists
+    #   @api public
+    #   @example
+    #     stat.ast #=> 11
+    #   @return [Integer] assists
+    attribute :ast, Shale::Type::Integer
+
+    # @!attribute [rw] stl
+    #   Returns steals
+    #   @api public
+    #   @example
+    #     stat.stl #=> 3
+    #   @return [Integer] steals
+    attribute :stl, Shale::Type::Integer
+
+    # @!attribute [rw] blk
+    #   Returns blocks
+    #   @api public
+    #   @example
+    #     stat.blk #=> 1
+    #   @return [Integer] blocks
+    attribute :blk, Shale::Type::Integer
+
+    # @!attribute [rw] tov
+    #   Returns turnovers
+    #   @api public
+    #   @example
+    #     stat.tov #=> 4
+    #   @return [Integer] turnovers
+    attribute :tov, Shale::Type::Integer
+
+    # @!attribute [rw] pf
+    #   Returns personal fouls
+    #   @api public
+    #   @example
+    #     stat.pf #=> 2
+    #   @return [Integer] personal fouls
+    attribute :pf, Shale::Type::Integer
+
+    # @!attribute [rw] pts
+    #   Returns points
+    #   @api public
+    #   @example
+    #     stat.pts #=> 33
+    #   @return [Integer] points
+    attribute :pts, Shale::Type::Integer
+
+    # @!attribute [rw] plus_minus
+    #   Returns plus/minus
+    #   @api public
+    #   @example
+    #     stat.plus_minus #=> 12
+    #   @return [Integer] plus/minus
+    attribute :plus_minus, Shale::Type::Integer
+
+    # 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_player_track.rb

@@ -0,0 +1,223 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "box_score_player_track_stat"
+require_relative "box_score_player_track_team_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve player tracking statistics for a game
+  module BoxScorePlayerTrack
+    # 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 player tracking statistics for players in a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScorePlayerTrack.player_stats(game: "0022400001")
+    #   stats.each { |s| puts "#{s.player_name}: #{s.distance} miles, #{s.touches} touches" }
+    # @param game [String, Game] the game ID or Game object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of player tracking stats
+    def self.player_stats(game:, client: CLIENT)
+      game_id = Utils.extract_id(game)
+      path = "boxscoreplayertrackv3?GameID=#{game_id}"
+      response = client.get(path)
+      parse_player_response(response, game_id)
+    end
+
+    # Retrieves player tracking statistics for teams in a game
+    #
+    # @api public
+    # @example
+    #   stats = NBA::BoxScorePlayerTrack.team_stats(game: "0022400001")
+    #   stats.each { |s| puts "#{s.team_name}: #{s.distance} miles, #{s.touches} touches" }
+    # @param game [String, Game] the game ID or Game object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of team tracking stats
+    def self.team_stats(game:, client: CLIENT)
+      game_id = Utils.extract_id(game)
+      path = "boxscoreplayertrackv3?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 [BoxScorePlayerTrackStat] the player stat
+    def self.build_player_stat(headers, row, game_id)
+      data = headers.zip(row).to_h
+      BoxScorePlayerTrackStat.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 [BoxScorePlayerTrackTeamStat] the team stat
+    def self.build_team_stat(headers, row, game_id)
+      data = headers.zip(row).to_h
+      BoxScorePlayerTrackTeamStat.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(tracking_stats(data), passing_stats(data), shooting_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(tracking_stats(data), passing_stats(data), shooting_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")}
+    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")}
+    end
+    private_class_method :team_identity
+
+    # Extracts tracking stats
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] tracking stats
+    def self.tracking_stats(data)
+      {speed: data.fetch("SPD"), distance: data.fetch("DIST"), oreb_chances: data.fetch("ORBC"), dreb_chances: data.fetch("DRBC"),
+       reb_chances: data.fetch("RBC"), touches: data.fetch("TCHS")}
+    end
+    private_class_method :tracking_stats
+
+    # Extracts passing stats
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] passing stats
+    def self.passing_stats(data)
+      {secondary_ast: data.fetch("SAST"), ft_ast: data.fetch("FTAST"), passes: data.fetch("PASS"), ast: data.fetch("AST")}
+    end
+    private_class_method :passing_stats
+
+    # Extracts shooting stats
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] shooting stats
+    def self.shooting_stats(data)
+      {cfgm: data.fetch("CFGM"), cfga: data.fetch("CFGA"), cfg_pct: data.fetch("CFG_PCT"),
+       ufgm: data.fetch("UFGM"), ufga: data.fetch("UFGA"), ufg_pct: data.fetch("UFG_PCT"),
+       dfgm: data.fetch("DFGM"), dfga: data.fetch("DFGA"), dfg_pct: data.fetch("DFG_PCT")}
+    end
+    private_class_method :shooting_stats
+  end
+end