nba 0.1.1 → 0.2.0

data/lib/nba/shot_chart_lineup_detail.rb

@@ -0,0 +1,109 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+require_relative "shot"
+require_relative "league"
+require_relative "response_parser"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve NBA shot chart lineup detail
+  module ShotChartLineupDetail
+    # Result set name for shot chart lineup detail
+    # @return [String] the result set name
+    DETAIL_SET = "ShotChartLineupDetail".freeze
+
+    # Result set name for league averages
+    # @return [String] the result set name
+    AVERAGE_SET = "ShotChartLineupLeagueAverage".freeze
+
+    # Retrieves shot chart lineup detail for a lineup group
+    #
+    # @api public
+    # @example
+    #   shots = NBA::ShotChartLineupDetail.all(group_id: 12345, season: 2023)
+    #   shots.each { |s| puts "#{s.player_name}: #{s.made? ? 'Made' : 'Missed'}" }
+    # @param group_id [Integer] the lineup group ID
+    # @param season [Integer] the season year (defaults to current season)
+    # @param season_type [String] the season type (Regular Season, Playoffs, etc.)
+    # @param context_measure [String] the context measure (FGA, FG3A, etc.)
+    # @param period [Integer] the period (0 for all periods)
+    # @param league [String, League] the league ID or League object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of shots
+    def self.all(group_id:, season: Utils.current_season, season_type: "Regular Season",
+      context_measure: "FGA", period: 0, league: League::NBA, client: CLIENT)
+      league_id = Utils.extract_league_id(league)
+      opts = {group_id: group_id, season: season, season_type: season_type,
+              context_measure: context_measure, period: period, league_id: league_id}
+      ResponseParser.parse(client.get(build_path(opts)), result_set: DETAIL_SET) do |data|
+        build_shot(data)
+      end
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(opts)
+      "shotchartlineupdetail?ContextMeasure=#{opts[:context_measure]}" \
+        "&GROUP_ID=#{opts[:group_id]}&LeagueID=#{opts[:league_id]}&Period=#{opts[:period]}" \
+        "&Season=#{Utils.format_season(opts[:season])}&SeasonType=#{opts[:season_type]}"
+    end
+    private_class_method :build_path
+
+    # Builds a Shot object from raw data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Shot] the shot object
+    def self.build_shot(data)
+      Shot.new(**shot_attributes(data))
+    end
+    private_class_method :build_shot
+
+    # Extracts shot attributes from data
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] shot attributes
+    def self.shot_attributes(data)
+      game_attributes(data).merge(player_attributes(data)).merge(shot_info_attributes(data))
+    end
+    private_class_method :shot_attributes
+
+    # Extracts game-related attributes
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] game attributes
+    def self.game_attributes(data)
+      {game_id: data["GAME_ID"], game_event_id: data["GAME_EVENT_ID"],
+       period: data["PERIOD"], minutes_remaining: data["MINUTES_REMAINING"],
+       seconds_remaining: data["SECONDS_REMAINING"]}
+    end
+    private_class_method :game_attributes
+
+    # Extracts player-related attributes
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] player attributes
+    def self.player_attributes(data)
+      {player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       team_id: data["TEAM_ID"], team_name: data["TEAM_NAME"]}
+    end
+    private_class_method :player_attributes
+
+    # Extracts shot info attributes
+    # @api private
+    # @param data [Hash] the row data
+    # @return [Hash] shot info attributes
+    def self.shot_info_attributes(data)
+      {action_type: data["ACTION_TYPE"], shot_type: data["SHOT_TYPE"],
+       shot_zone_basic: data["SHOT_ZONE_BASIC"],
+       shot_zone_area: data["SHOT_ZONE_AREA"],
+       shot_zone_range: data["SHOT_ZONE_RANGE"],
+       shot_distance: data["SHOT_DISTANCE"],
+       loc_x: data["LOC_X"], loc_y: data["LOC_Y"],
+       shot_attempted_flag: data["SHOT_ATTEMPTED_FLAG"],
+       shot_made_flag: data["SHOT_MADE_FLAG"]}
+    end
+    private_class_method :shot_info_attributes
+  end
+end

data/lib/nba/shot_stat.rb

@@ -0,0 +1,174 @@
+require "equalizer"
+require "shale"
+require_relative "players"
+
+module NBA
+  # Represents a player's shot statistics
+  #
+  # @api public
+  class ShotStat < Shale::Mapper
+    include Equalizer.new(:player_id, :shot_type, :g)
+
+    # @!attribute [rw] player_id
+    #   Returns the player ID
+    #   @api public
+    #   @example
+    #     stat.player_id #=> 201939
+    #   @return [Integer, nil] the player's ID
+    attribute :player_id, Shale::Type::Integer
+
+    # @!attribute [rw] player_name_last_first
+    #   Returns the player name in "Last, First" format
+    #   @api public
+    #   @example
+    #     stat.player_name_last_first #=> "Curry, Stephen"
+    #   @return [String, nil] the player's name (last, first)
+    attribute :player_name_last_first, Shale::Type::String
+
+    # @!attribute [rw] sort_order
+    #   Returns the sort order
+    #   @api public
+    #   @example
+    #     stat.sort_order #=> 1
+    #   @return [Integer, nil] the sort order
+    attribute :sort_order, Shale::Type::Integer
+
+    # @!attribute [rw] gp
+    #   Returns games played
+    #   @api public
+    #   @example
+    #     stat.gp #=> 74
+    #   @return [Integer, nil] games played
+    attribute :gp, Shale::Type::Integer
+
+    # @!attribute [rw] g
+    #   Returns number of games
+    #   @api public
+    #   @example
+    #     stat.g #=> 74
+    #   @return [Integer, nil] games
+    attribute :g, Shale::Type::Integer
+
+    # @!attribute [rw] shot_type
+    #   Returns the shot type or category
+    #   @api public
+    #   @example
+    #     stat.shot_type #=> "Catch and Shoot"
+    #   @return [String, nil] the shot type or category
+    attribute :shot_type, Shale::Type::String
+
+    # @!attribute [rw] fga_frequency
+    #   Returns field goal attempt frequency
+    #   @api public
+    #   @example
+    #     stat.fga_frequency #=> 0.35
+    #   @return [Float, nil] field goal attempt frequency
+    attribute :fga_frequency, Shale::Type::Float
+
+    # @!attribute [rw] fgm
+    #   Returns field goals made
+    #   @api public
+    #   @example
+    #     stat.fgm #=> 7.2
+    #   @return [Float, nil] field goals made
+    attribute :fgm, Shale::Type::Float
+
+    # @!attribute [rw] fga
+    #   Returns field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fga #=> 15.3
+    #   @return [Float, nil] field goals attempted
+    attribute :fga, Shale::Type::Float
+
+    # @!attribute [rw] fg_pct
+    #   Returns field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg_pct #=> 0.472
+    #   @return [Float, nil] field goal percentage
+    attribute :fg_pct, Shale::Type::Float
+
+    # @!attribute [rw] efg_pct
+    #   Returns effective field goal percentage
+    #   @api public
+    #   @example
+    #     stat.efg_pct #=> 0.561
+    #   @return [Float, nil] effective field goal percentage
+    attribute :efg_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg2a_frequency
+    #   Returns 2-point field goal attempt frequency
+    #   @api public
+    #   @example
+    #     stat.fg2a_frequency #=> 0.45
+    #   @return [Float, nil] 2-point field goal attempt frequency
+    attribute :fg2a_frequency, Shale::Type::Float
+
+    # @!attribute [rw] fg2m
+    #   Returns 2-point field goals made
+    #   @api public
+    #   @example
+    #     stat.fg2m #=> 4.1
+    #   @return [Float, nil] 2-point field goals made
+    attribute :fg2m, Shale::Type::Float
+
+    # @!attribute [rw] fg2a
+    #   Returns 2-point field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fg2a #=> 7.8
+    #   @return [Float, nil] 2-point field goals attempted
+    attribute :fg2a, Shale::Type::Float
+
+    # @!attribute [rw] fg2_pct
+    #   Returns 2-point field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg2_pct #=> 0.526
+    #   @return [Float, nil] 2-point field goal percentage
+    attribute :fg2_pct, Shale::Type::Float
+
+    # @!attribute [rw] fg3a_frequency
+    #   Returns 3-point field goal attempt frequency
+    #   @api public
+    #   @example
+    #     stat.fg3a_frequency #=> 0.55
+    #   @return [Float, nil] 3-point field goal attempt frequency
+    attribute :fg3a_frequency, Shale::Type::Float
+
+    # @!attribute [rw] fg3m
+    #   Returns 3-point field goals made
+    #   @api public
+    #   @example
+    #     stat.fg3m #=> 4.8
+    #   @return [Float, nil] 3-point field goals made
+    attribute :fg3m, Shale::Type::Float
+
+    # @!attribute [rw] fg3a
+    #   Returns 3-point field goals attempted
+    #   @api public
+    #   @example
+    #     stat.fg3a #=> 11.2
+    #   @return [Float, nil] 3-point field goals attempted
+    attribute :fg3a, Shale::Type::Float
+
+    # @!attribute [rw] fg3_pct
+    #   Returns 3-point field goal percentage
+    #   @api public
+    #   @example
+    #     stat.fg3_pct #=> 0.428
+    #   @return [Float, nil] 3-point field goal percentage
+    attribute :fg3_pct, Shale::Type::Float
+
+    # Returns the player who took the shots
+    #
+    # @api public
+    # @example
+    #   stat.player #=> #<NBA::Player id=201939 ...>
+    # @return [Player, nil] the player object
+    def player
+      Players.find(player_id)
+    end
+  end
+end

data/lib/nba/standing.rb

@@ -0,0 +1,129 @@
+require "equalizer"
+require "shale"
+require_relative "teams"
+
+module NBA
+  # Represents a team's standing in the league
+  class Standing < Shale::Mapper
+    include Equalizer.new(:team_id)
+
+    # @!attribute [rw] team_id
+    #   Returns the team ID
+    #   @api public
+    #   @example
+    #     standing.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
+    #     standing.team_name #=> "Golden State Warriors"
+    #   @return [String] the team name
+    attribute :team_name, Shale::Type::String
+
+    # @!attribute [rw] conference
+    #   Returns the conference
+    #   @api public
+    #   @example
+    #     standing.conference #=> "West"
+    #   @return [String] the conference
+    attribute :conference, Shale::Type::String
+
+    # @!attribute [rw] division
+    #   Returns the division
+    #   @api public
+    #   @example
+    #     standing.division #=> "Pacific"
+    #   @return [String] the division
+    attribute :division, Shale::Type::String
+
+    # @!attribute [rw] wins
+    #   Returns the number of wins
+    #   @api public
+    #   @example
+    #     standing.wins #=> 45
+    #   @return [Integer] the number of wins
+    attribute :wins, Shale::Type::Integer
+
+    # @!attribute [rw] losses
+    #   Returns the number of losses
+    #   @api public
+    #   @example
+    #     standing.losses #=> 30
+    #   @return [Integer] the number of losses
+    attribute :losses, Shale::Type::Integer
+
+    # @!attribute [rw] win_pct
+    #   Returns the win percentage
+    #   @api public
+    #   @example
+    #     standing.win_pct #=> 0.600
+    #   @return [Float] the win percentage
+    attribute :win_pct, Shale::Type::Float
+
+    # @!attribute [rw] conference_rank
+    #   Returns the conference rank
+    #   @api public
+    #   @example
+    #     standing.conference_rank #=> 5
+    #   @return [Integer] the conference rank
+    attribute :conference_rank, Shale::Type::Integer
+
+    # @!attribute [rw] home_record
+    #   Returns the home record
+    #   @api public
+    #   @example
+    #     standing.home_record #=> "25-12"
+    #   @return [String] the home record
+    attribute :home_record, Shale::Type::String
+
+    # @!attribute [rw] road_record
+    #   Returns the road record
+    #   @api public
+    #   @example
+    #     standing.road_record #=> "20-18"
+    #   @return [String] the road record
+    attribute :road_record, Shale::Type::String
+
+    # @!attribute [rw] streak
+    #   Returns the current streak
+    #   @api public
+    #   @example
+    #     standing.streak #=> "W3"
+    #   @return [String] the current streak
+    attribute :streak, Shale::Type::String
+
+    # Returns the team object for this standing
+    #
+    # @api public
+    # @example
+    #   standing.team #=> #<NBA::Team>
+    #   standing.team.city #=> "San Francisco"
+    # @return [Team, nil] the team object
+    def team
+      Teams.find(team_id)
+    end
+
+    json do
+      map "team_id", to: :team_id
+      map "teamId", to: :team_id
+      map "team_name", to: :team_name
+      map "teamName", to: :team_name
+      map "conference", to: :conference
+      map "division", to: :division
+      map "wins", to: :wins
+      map "losses", to: :losses
+      map "win_pct", to: :win_pct
+      map "winPct", to: :win_pct
+      map "conference_rank", to: :conference_rank
+      map "conferenceRank", to: :conference_rank
+      map "home_record", to: :home_record
+      map "homeRecord", to: :home_record
+      map "road_record", to: :road_record
+      map "roadRecord", to: :road_record
+      map "streak", to: :streak
+    end
+  end
+end

data/lib/nba/standings.rb

@@ -0,0 +1,75 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "standing"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve NBA standings
+  module Standings
+    # Retrieves all team standings
+    #
+    # @api public
+    # @example
+    #   standings = NBA::Standings.all
+    #   standings.each { |s| puts "#{s.conference_rank}. #{s.team_name}: #{s.wins}-#{s.losses}" }
+    # @param season [Integer] the season year (defaults to current season)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of standings
+    def self.all(season: Utils.current_season, client: CLIENT)
+      path = "leaguestandings?LeagueID=00&Season=#{Utils.format_season(season)}&SeasonType=Regular+Season"
+      ResponseParser.parse(client.get(path)) { |data| build_standing(data) }
+    end
+
+    # Retrieves standings for a specific conference
+    #
+    # @api public
+    # @example
+    #   western = NBA::Standings.conference("West")
+    # @param conference_name [String] the conference name (East or West)
+    # @param season [Integer] the season year
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of standings for the conference
+    def self.conference(conference_name, season: Utils.current_season, client: CLIENT)
+      Collection.new(all(season: season, client: client).select { |s| s.conference.eql?(conference_name) })
+    end
+
+    # Builds a standing from API data
+    # @api private
+    # @return [Standing]
+    def self.build_standing(data)
+      Standing.new(**team_info(data), **record_info(data))
+    end
+    private_class_method :build_standing
+
+    # Extracts team information from data
+    # @api private
+    # @return [Hash]
+    def self.team_info(data)
+      {team_id: data["TeamID"], team_name: data["TeamName"],
+       conference: data["Conference"], division: data["Division"]}
+    end
+    private_class_method :team_info
+
+    # Extracts record information from data
+    # @api private
+    # @return [Hash]
+    def self.record_info(data)
+      {wins: data["WINS"], losses: data["LOSSES"], win_pct: data["WinPCT"],
+       conference_rank: parse_conference_rank(data["ConferenceRecord"], data["PlayoffRank"]),
+       home_record: data["HOME"], road_record: data["ROAD"], streak: data["strCurrentStreak"]}
+    end
+    private_class_method :record_info
+
+    # Parses conference rank from conference record or playoff rank
+    #
+    # @api private
+    # @param conference_record [String, Integer, nil] the conference record
+    # @param playoff_rank [Integer, nil] the playoff rank
+    # @return [Integer, nil] the conference rank
+    def self.parse_conference_rank(conference_record, playoff_rank)
+      wins = conference_record.to_s.split("-").first
+      (wins.nil? || wins.empty?) ? playoff_rank : wins.to_i
+    end
+    private_class_method :parse_conference_rank
+  end
+end

data/lib/nba/static.rb

@@ -0,0 +1,107 @@
+require_relative "data"
+require_relative "team"
+
+module NBA
+  # Provides static data lookup for teams without API calls
+  #
+  # @api public
+  module Static
+    # Retrieves all NBA teams
+    #
+    # @api public
+    # @example
+    #   teams = NBA::Static.teams
+    #   teams.size #=> 30
+    # @return [Array<Hash>] array of team hashes
+    def self.teams
+      Data::TEAMS
+    end
+
+    # Finds a team by ID
+    #
+    # @api public
+    # @example
+    #   team = NBA::Static.find_team_by_id(1610612744)
+    #   team[:full_name] #=> "Golden State Warriors"
+    # @param id [Integer] the team ID
+    # @return [Hash, nil] the team hash or nil if not found
+    def self.find_team_by_id(id)
+      Data::TEAMS.find { |t| t.fetch(:id).eql?(id) }
+    end
+
+    # Finds a team by abbreviation
+    #
+    # @api public
+    # @example
+    #   team = NBA::Static.find_team_by_abbreviation("GSW")
+    #   team[:full_name] #=> "Golden State Warriors"
+    # @param abbreviation [String] the team abbreviation
+    # @return [Hash, nil] the team hash or nil if not found
+    def self.find_team_by_abbreviation(abbreviation)
+      Data::TEAMS.find { |t| t.fetch(:abbreviation).casecmp?(abbreviation) }
+    end
+
+    # Finds teams by city name
+    #
+    # @api public
+    # @example
+    #   teams = NBA::Static.find_teams_by_city("Los Angeles")
+    #   teams.size #=> 2
+    # @param city [String] the city name (case-insensitive, partial match)
+    # @return [Array<Hash>] array of matching team hashes
+    def self.find_teams_by_city(city)
+      pattern = Regexp.new(Regexp.escape(city), Regexp::IGNORECASE)
+      Data::TEAMS.select { |t| pattern.match?(t.fetch(:city)) }
+    end
+
+    # Finds teams by state name
+    #
+    # @api public
+    # @example
+    #   teams = NBA::Static.find_teams_by_state("California")
+    #   teams.size #=> 4
+    # @param state [String] the state name (case-insensitive, partial match)
+    # @return [Array<Hash>] array of matching team hashes
+    def self.find_teams_by_state(state)
+      pattern = Regexp.new(Regexp.escape(state), Regexp::IGNORECASE)
+      Data::TEAMS.select { |t| pattern.match?(t.fetch(:state)) }
+    end
+
+    # Finds teams by nickname
+    #
+    # @api public
+    # @example
+    #   team = NBA::Static.find_team_by_nickname("Warriors")
+    #   team[:city] #=> "San Francisco"
+    # @param nickname [String] the team nickname (case-insensitive)
+    # @return [Hash, nil] the team hash or nil if not found
+    def self.find_team_by_nickname(nickname)
+      Data::TEAMS.find { |t| t.fetch(:nickname).casecmp?(nickname) }
+    end
+
+    # Finds teams by full name
+    #
+    # @api public
+    # @example
+    #   teams = NBA::Static.find_teams_by_full_name("Warriors")
+    #   teams.first[:city] #=> "San Francisco"
+    # @param name [String] the name to search (case-insensitive, partial match)
+    # @return [Array<Hash>] array of matching team hashes
+    def self.find_teams_by_full_name(name)
+      pattern = Regexp.new(Regexp.escape(name), Regexp::IGNORECASE)
+      Data::TEAMS.select { |t| pattern.match?(t.fetch(:full_name)) }
+    end
+
+    # Finds teams by year founded
+    #
+    # @api public
+    # @example
+    #   teams = NBA::Static.find_teams_by_year_founded(1946)
+    #   teams.size #=> 4
+    # @param year [Integer] the founding year
+    # @return [Array<Hash>] array of matching team hashes
+    def self.find_teams_by_year_founded(year)
+      Data::TEAMS.select { |t| t.fetch(:year_founded).eql?(year) }
+    end
+  end
+end