nba 0.1.1 → 0.2.0

data/lib/nba/league_dash_team_stat.rb

@@ -0,0 +1,275 @@
+require "equalizer"
+require "shale"
+
+module NBA
+  # Represents league-wide team statistics
+  class LeagueDashTeamStat < Shale::Mapper
+    include Equalizer.new(:team_id, :season_id)
+
+    # @!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 #=> "Golden State Warriors"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] season_id
+    #   Returns the season ID
+    #   @api public
+    #   @example
+    #     stat.season_id #=> "2024-25"
+    #   @return [String] the season ID
+    attribute :season_id, Shale::Type::String
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 82
+    #   @return [Integer] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] w
+    #   Returns wins
+    #   @api public
+    #   @example
+    #     stat.w #=> 53
+    #   @return [Integer] wins
+    attribute :w, Shale::Type::Integer
+
+    # @!attribute [rw] l
+    #   Returns losses
+    #   @api public
+    #   @example
+    #     stat.l #=> 29
+    #   @return [Integer] losses
+    attribute :l, Shale::Type::Integer
+
+    # @!attribute [rw] w_pct
+    #   Returns win percentage
+    #   @api public
+    #   @example
+    #     stat.w_pct #=> 0.646
+    #   @return [Float] win percentage
+    attribute :w_pct, Shale::Type::Float
+
+    # @!attribute [rw] min
+    #   Returns minutes per game
+    #   @api public
+    #   @example
+    #     stat.min #=> 240.0
+    #   @return [Float] minutes per game
+    attribute :min, Shale::Type::Float
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made per game
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 42.3
+    #   @return [Float] field goals made
+    attribute :fgm, Shale::Type::Float
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted per game
+    #   @api public
+    #   @example
+    #     stat.fga #=> 90.5
+    #   @return [Float] field goals attempted
+    attribute :fga, Shale::Type::Float
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.467
+    #   @return [Float] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns three pointers made per game
+    #   @api public
+    #   @example
+    #     stat.fg3m #=> 13.7
+    #   @return [Float] three pointers made
+    attribute :fg3m, Shale::Type::Float
+
+    # @!attribute [rw] fg3a
+    #   Returns three pointers attempted per game
+    #   @api public
+    #   @example
+    #     stat.fg3a #=> 38.2
+    #   @return [Float] three pointers attempted
+    attribute :fg3a, Shale::Type::Float
+
+    # @!attribute [rw] fg3_pct
+    #   Returns three point percentage
+    #   @api public
+    #   @example
+    #     stat.fg3_pct #=> 0.359
+    #   @return [Float] three point percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # @!attribute [rw] ftm
+    #   Returns free throws made per game
+    #   @api public
+    #   @example
+    #     stat.ftm #=> 17.5
+    #   @return [Float] free throws made
+    attribute :ftm, Shale::Type::Float
+
+    # @!attribute [rw] fta
+    #   Returns free throws attempted per game
+    #   @api public
+    #   @example
+    #     stat.fta #=> 22.3
+    #   @return [Float] free throws attempted
+    attribute :fta, Shale::Type::Float
+
+    # @!attribute [rw] ft_pct
+    #   Returns free throw percentage
+    #   @api public
+    #   @example
+    #     stat.ft_pct #=> 0.785
+    #   @return [Float] free throw percentage
+    attribute :ft_pct, Shale::Type::Float
+
+    # @!attribute [rw] oreb
+    #   Returns offensive rebounds per game
+    #   @api public
+    #   @example
+    #     stat.oreb #=> 10.2
+    #   @return [Float] offensive rebounds
+    attribute :oreb, Shale::Type::Float
+
+    # @!attribute [rw] dreb
+    #   Returns defensive rebounds per game
+    #   @api public
+    #   @example
+    #     stat.dreb #=> 34.5
+    #   @return [Float] defensive rebounds
+    attribute :dreb, Shale::Type::Float
+
+    # @!attribute [rw] reb
+    #   Returns total rebounds per game
+    #   @api public
+    #   @example
+    #     stat.reb #=> 44.7
+    #   @return [Float] total rebounds
+    attribute :reb, Shale::Type::Float
+
+    # @!attribute [rw] ast
+    #   Returns assists per game
+    #   @api public
+    #   @example
+    #     stat.ast #=> 27.8
+    #   @return [Float] assists
+    attribute :ast, Shale::Type::Float
+
+    # @!attribute [rw] tov
+    #   Returns turnovers per game
+    #   @api public
+    #   @example
+    #     stat.tov #=> 13.2
+    #   @return [Float] turnovers
+    attribute :tov, Shale::Type::Float
+
+    # @!attribute [rw] stl
+    #   Returns steals per game
+    #   @api public
+    #   @example
+    #     stat.stl #=> 7.5
+    #   @return [Float] steals
+    attribute :stl, Shale::Type::Float
+
+    # @!attribute [rw] blk
+    #   Returns blocks per game
+    #   @api public
+    #   @example
+    #     stat.blk #=> 5.2
+    #   @return [Float] blocks
+    attribute :blk, Shale::Type::Float
+
+    # @!attribute [rw] blka
+    #   Returns blocked attempts per game
+    #   @api public
+    #   @example
+    #     stat.blka #=> 4.8
+    #   @return [Float] blocked attempts
+    attribute :blka, Shale::Type::Float
+
+    # @!attribute [rw] pf
+    #   Returns personal fouls per game
+    #   @api public
+    #   @example
+    #     stat.pf #=> 18.5
+    #   @return [Float] personal fouls
+    attribute :pf, Shale::Type::Float
+
+    # @!attribute [rw] pfd
+    #   Returns personal fouls drawn per game
+    #   @api public
+    #   @example
+    #     stat.pfd #=> 19.2
+    #   @return [Float] personal fouls drawn
+    attribute :pfd, Shale::Type::Float
+
+    # @!attribute [rw] pts
+    #   Returns points per game
+    #   @api public
+    #   @example
+    #     stat.pts #=> 115.8
+    #   @return [Float] points
+    attribute :pts, Shale::Type::Float
+
+    # @!attribute [rw] plus_minus
+    #   Returns plus/minus per game
+    #   @api public
+    #   @example
+    #     stat.plus_minus #=> 5.2
+    #   @return [Float] plus/minus
+    attribute :plus_minus, Shale::Type::Float
+
+    # @!attribute [rw] gp_rank
+    #   Returns games played rank
+    #   @api public
+    #   @example
+    #     stat.gp_rank #=> 1
+    #   @return [Integer] games played rank
+    attribute :gp_rank, Shale::Type::Integer
+
+    # @!attribute [rw] w_rank
+    #   Returns wins rank
+    #   @api public
+    #   @example
+    #     stat.w_rank #=> 3
+    #   @return [Integer] wins rank
+    attribute :w_rank, Shale::Type::Integer
+
+    # @!attribute [rw] pts_rank
+    #   Returns points rank
+    #   @api public
+    #   @example
+    #     stat.pts_rank #=> 5
+    #   @return [Integer] points rank
+    attribute :pts_rank, Shale::Type::Integer
+
+    # Returns the team object
+    #
+    # @api public
+    # @example
+    #   stat.team #=> #<NBA::Team>
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+  end
+end

data/lib/nba/league_dash_team_stats.rb

@@ -0,0 +1,172 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "league_dash_team_stat"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve league-wide team statistics
+  module LeagueDashTeamStats
+    # Result set name
+    # @return [String] the result set name
+    LEAGUE_DASH_TEAM_STATS = "LeagueDashTeamStats".freeze
+
+    # Regular season type
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Playoffs season type
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Per game mode
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Totals mode
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Per 100 possessions mode
+    # @return [String] the per mode
+    PER_100 = "Per100Possessions".freeze
+
+    # Retrieves league-wide team statistics
+    #
+    # @api public
+    # @example
+    #   stats = NBA::LeagueDashTeamStats.all(season: 2024)
+    #   stats.each { |s| puts "#{s.team_name}: #{s.pts} PPG" }
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs)
+    # @param per_mode [String] the per mode (PerGame, Totals, Per100Possessions)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of team stats
+    def self.all(season: Utils.current_season, season_type: REGULAR_SEASON, per_mode: PER_GAME, client: CLIENT)
+      path = build_path(season, season_type, per_mode)
+      response = client.get(path)
+      parse_response(response, season)
+    end
+
+    # Builds the API path
+    # @api private
+    # @param season [Integer] the season
+    # @param season_type [String] the season type
+    # @param per_mode [String] the per mode
+    # @return [String] the path
+    def self.build_path(season, season_type, per_mode)
+      "leaguedashteamstats?Conference=&DateFrom=&DateTo=&Division=&GameScope=&GameSegment=&Height=&" \
+        "ISTRound=&LastNGames=0&LeagueID=00&Location=&MeasureType=Base&Month=0&OpponentTeamID=0&Outcome=&" \
+        "PORound=0&PaceAdjust=N&PerMode=#{per_mode}&Period=0&PlayerExperience=&PlayerPosition=&PlusMinus=N&" \
+        "Rank=Y&Season=#{Utils.format_season(season)}&SeasonSegment=&SeasonType=#{season_type}&ShotClockRange=&" \
+        "StarterBench=&TeamID=0&TwoWay=0&VsConference=&VsDivision="
+    end
+    private_class_method :build_path
+
+    # Parses the API response
+    # @api private
+    # @param response [String, nil] the JSON response
+    # @param season [Integer] the season
+    # @return [Collection] collection of team stats
+    def self.parse_response(response, season)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      return Collection.new unless result_set
+
+      build_team_stats(result_set, Utils.format_season(season))
+    end
+    private_class_method :parse_response
+
+    # Finds the result set
+    # @api private
+    # @param data [Hash] the parsed JSON
+    # @return [Hash, nil] the result set
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs.fetch("name").eql?(LEAGUE_DASH_TEAM_STATS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds team stats collection
+    # @api private
+    # @param result_set [Hash] the result set
+    # @param season_id [String] the season ID
+    # @return [Collection] collection of team stats
+    def self.build_team_stats(result_set, season_id)
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      stats = rows.map { |row| build_team_stat(headers, row, season_id) }
+      Collection.new(stats)
+    end
+    private_class_method :build_team_stats
+
+    # Builds a single team stat
+    # @api private
+    # @param headers [Array<String>] the headers
+    # @param row [Array] the row data
+    # @param season_id [String] the season ID
+    # @return [LeagueDashTeamStat] the team stat
+    def self.build_team_stat(headers, row, season_id)
+      data = headers.zip(row).to_h
+      LeagueDashTeamStat.new(**team_stat_attributes(data, season_id))
+    end
+    private_class_method :build_team_stat
+
+    # Combines all team stat attributes
+    # @api private
+    # @param data [Hash] the raw data
+    # @param season_id [String] the season ID
+    # @return [Hash] the combined attributes
+    def self.team_stat_attributes(data, season_id)
+      identity_attributes(data, season_id).merge(shooting_attributes(data), counting_attributes(data), rank_attributes(data))
+    end
+    private_class_method :team_stat_attributes
+
+    # Extracts identity attributes
+    # @api private
+    # @param data [Hash] the raw data
+    # @param season_id [String] the season ID
+    # @return [Hash] identity attributes
+    def self.identity_attributes(data, season_id)
+      {team_id: data.fetch("TEAM_ID"), team_name: data.fetch("TEAM_NAME"), season_id: season_id,
+       gp: data.fetch("GP"), w: data.fetch("W"), l: data.fetch("L"), w_pct: data.fetch("W_PCT"), min: data.fetch("MIN")}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts shooting attributes
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] shooting attributes
+    def self.shooting_attributes(data)
+      {fgm: data.fetch("FGM"), fga: data.fetch("FGA"), fg_pct: data.fetch("FG_PCT"), fg3m: data.fetch("FG3M"), fg3a: data.fetch("FG3A"),
+       fg3_pct: data.fetch("FG3_PCT"), ftm: data.fetch("FTM"), fta: data.fetch("FTA"), ft_pct: data.fetch("FT_PCT")}
+    end
+    private_class_method :shooting_attributes
+
+    # Extracts counting attributes
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] counting attributes
+    def self.counting_attributes(data)
+      {oreb: data.fetch("OREB"), dreb: data.fetch("DREB"), reb: data.fetch("REB"), ast: data.fetch("AST"), tov: data.fetch("TOV"),
+       stl: data.fetch("STL"), blk: data.fetch("BLK"), blka: data.fetch("BLKA"), pf: data.fetch("PF"), pfd: data.fetch("PFD"),
+       pts: data.fetch("PTS"), plus_minus: data.fetch("PLUS_MINUS")}
+    end
+    private_class_method :counting_attributes
+
+    # Extracts rank attributes
+    # @api private
+    # @param data [Hash] the raw data
+    # @return [Hash] rank attributes
+    def self.rank_attributes(data)
+      {gp_rank: data.fetch("GP_RANK"), w_rank: data.fetch("W_RANK"), pts_rank: data.fetch("PTS_RANK")}
+    end
+    private_class_method :rank_attributes
+  end
+end

data/lib/nba/league_game_finder.rb

@@ -0,0 +1,170 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "utils"
+
+require_relative "found_game"
+
+module NBA
+  # Provides methods to find games based on criteria
+  module LeagueGameFinder
+    # Result set name for team games
+    # @return [String] the result set name
+    TEAM_GAMES = "TeamGameFinderResults".freeze
+
+    # Result set name for player games
+    # @return [String] the result set name
+    PLAYER_GAMES = "PlayerGameFinderResults".freeze
+
+    # Season type constant for regular season
+    # @return [String] the season type
+    REGULAR_SEASON = "Regular Season".freeze
+
+    # Season type constant for playoffs
+    # @return [String] the season type
+    PLAYOFFS = "Playoffs".freeze
+
+    # Finds games for a team
+    #
+    # @api public
+    # @example
+    #   games = NBA::LeagueGameFinder.by_team(team: NBA::Team::GSW)
+    #   games.each { |g| puts "#{g.game_date}: #{g.matchup} - #{g.wl}" }
+    # @param team [Integer, Team] the team ID or Team object
+    # @param season [Integer, nil] the season year (nil for all seasons)
+    # @param season_type [String] the season type
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of found games
+    def self.by_team(team:, season: nil, season_type: REGULAR_SEASON, client: CLIENT)
+      team_id = Utils.extract_id(team)
+      path = build_team_path(team_id, season, season_type)
+      response = client.get(path)
+      parse_response(response, TEAM_GAMES)
+    end
+
+    # Finds games for a player
+    #
+    # @api public
+    # @example
+    #   games = NBA::LeagueGameFinder.by_player(player: 201939)
+    #   games.each { |g| puts "#{g.game_date}: #{g.matchup} - #{g.pts} pts" }
+    # @param player [Integer, Player] the player ID or Player object
+    # @param season [Integer, nil] the season year (nil for all seasons)
+    # @param season_type [String] the season type
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of found games
+    def self.by_player(player:, season: nil, season_type: REGULAR_SEASON, client: CLIENT)
+      player_id = Utils.extract_id(player)
+      path = build_player_path(player_id, season, season_type)
+      response = client.get(path)
+      parse_response(response, PLAYER_GAMES)
+    end
+
+    # Builds the API path for team game finder
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_team_path(team_id, season, season_type)
+      path = "leaguegamefinder?TeamID=#{team_id}&SeasonType=#{season_type}&LeagueID=00"
+      path += "&Season=#{Utils.format_season(season)}" if season
+      path
+    end
+    private_class_method :build_team_path
+
+    # Builds the API path for player game finder
+    #
+    # @api private
+    # @return [String] the request path
+    def self.build_player_path(player_id, season, season_type)
+      path = "leaguegamefinder?PlayerID=#{player_id}&SeasonType=#{season_type}&LeagueID=00"
+      path += "&Season=#{Utils.format_season(season)}" if season
+      path
+    end
+    private_class_method :build_player_path
+
+    # Parses the API response into found game objects
+    #
+    # @api private
+    # @return [Collection] collection of found games
+    def self.parse_response(response, result_set_name)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data, result_set_name)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      games = rows.map { |row| build_found_game(headers, row) }
+      Collection.new(games)
+    end
+    private_class_method :parse_response
+
+    # Finds the result set in the response
+    #
+    # @api private
+    # @return [Hash, nil] the result set hash
+    def self.find_result_set(data, name)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(name) }
+    end
+    private_class_method :find_result_set
+
+    # Builds a FoundGame object from raw data
+    #
+    # @api private
+    # @return [FoundGame] the found game object
+    def self.build_found_game(headers, row)
+      data = headers.zip(row).to_h
+      FoundGame.new(**found_game_attributes(data))
+    end
+    private_class_method :build_found_game
+
+    # Combines all found game attributes
+    #
+    # @api private
+    # @return [Hash] the combined attributes
+    def self.found_game_attributes(data)
+      identity_attributes(data).merge(shooting_attributes(data), counting_attributes(data))
+    end
+    private_class_method :found_game_attributes
+
+    # Extracts identity attributes from data
+    #
+    # @api private
+    # @return [Hash] identity attributes
+    def self.identity_attributes(data)
+      {season_id: data["SEASON_ID"], team_id: data["TEAM_ID"],
+       team_abbreviation: data["TEAM_ABBREVIATION"], team_name: data["TEAM_NAME"],
+       game_id: data["GAME_ID"], game_date: data["GAME_DATE"],
+       matchup: data["MATCHUP"], wl: data["WL"], min: data["MIN"]}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts shooting attributes from data
+    #
+    # @api private
+    # @return [Hash] shooting attributes
+    def self.shooting_attributes(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_attributes
+
+    # Extracts counting stats attributes from data
+    #
+    # @api private
+    # @return [Hash] counting attributes
+    def self.counting_attributes(data)
+      {pts: data["PTS"], oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], stl: data["STL"], blk: data["BLK"],
+       tov: data["TOV"], pf: data["PF"], plus_minus: data["PLUS_MINUS"]}
+    end
+    private_class_method :counting_attributes
+  end
+end