# AhlScraper This gem scrapes the AHL website for team, game, playoff bracket, player, or season data and returns it to you in an easy to use format. ## Installation Add this line to your application's Gemfile: ```ruby gem 'ahl_scraper' ``` And then execute: $ bundle install Or install it yourself as: $ gem install ahl_scraper ## Requirements - Ruby 2.7+ ## Documentation Check out the [Wiki page](https://github.com/notnotjeff/ahl_scraper/wiki) for additional documentation. ## Usage This gem is divided into multiple modules that provide you with an assortment of methods to access data from the AHL website: - [Seasons](#seasons) - `list` - `retrieve` - `retrieve_all` - [Games](#games) - `list` - `retrieve` - [Players](#players) - `retrieve` - [Teams](#teams) - `list` - [PlayoffBrackets](#playoffbrackets) - `retrieve` - [RosterPlayers](#rosterplayers) - `retrieve_all` - [PlayerGames](#playergames) - `list` - [TeamGames](#teamgames) - `list` ### Seasons #### list Returns a list of all seasons as an array of `SeasonListItem` objects: ```ruby require "ahl_scraper" AhlScraper::Seasons.list #=> [#72, :season_type=>:playoffs, :name=>"2021 Playoffs"}>, #68, :season_type=>:regular, :name=>"2020-21 Regular Season"}>, #67, :season_type=>:all_star, :name=>"2020 All-Star Challenge"}>, #65, :season_type=>:regular, :name=>"2019-20 Regular Season"}>, # ... #] ``` #### retrieve(season_id) Returns a `Season` object which has full details on a single season by passing in the season id: ```ruby require "ahl_scraper" AhlScraper::Seasons.retrieve(68) #=> #68, :season_type=>:regular, :start_year=>2020, :end_year=>2021, :start_date=>"Mon, Feb 1 2020", :end_date=>"Sat, Jun 8 2021", ... > ``` #### retrieve_all Get an array of `Season` objects with full details on each season: ```ruby require "ahl_scraper" AhlScraper::Seasons.retrieve_all #=> [#, #, # ...] ``` ### Games #### list(season_id) Returns a list of `GameListItem` objects for all games in a season by passing in the season id: ```ruby require "ahl_scraper" AhlScraper::Games.list(68) #=> [#"Fri, Feb 5", :id=>1022050, :status=>"Final", :game_sheet_url=>"https://lscluster.hockeytech.com/game_reports/official-game-report.php?client_code=ahl&game_id=1022050&lang_id=1", :game_center_url=>"https://theahl.com/stats/game-center/1022050", :home_team_city=>"Providence", :home_team_score=>4, :home_team_id=>309, :away_team_city=>"Bridgeport", :away_team_score=>1, :away_team_id=>317, :game_report_url=>"https://lscluster.hockeytech.com/game_reports/text-game-report.php?client_code=ahl&game_id=1022050&lang_id=1"}>, #"Fri, Feb 5", :id=>1022051, :status=>"Final", :game_sheet_url=>"https://lscluster.hockeytech.com/game_reports/official-game-report.php?client_code=ahl&game_id=1022051&lang_id=1", :game_center_url=>"https://theahl.com/stats/game-center/1022051", :home_team_city=>"Rochester", :home_team_score=>2, :home_team_id=>323, :away_team_city=>"Utica", :away_team_score=>3, :away_team_id=>390, :game_report_url=>"https://lscluster.hockeytech.com/game_reports/text-game-report.php?client_code=ahl&game_id=1022051&lang_id=1"}>, #... #] ``` #### retrieve(game_id) Get a `Game` object which has full details on a single game by passing in a game id: ```ruby require "ahl_scraper" AhlScraper::Games.retrieve(1022050) #=> #1022050, :season_type=>:regular, :info=>#"Friday, February 05, 2021", :name=>"BRI @ PRO", :id=>1022050, :end_time=>"3:15 pm", ... > ``` You can also pass in a `season_type` symbol (`:regular`, `:all_star`, `:exhibition`, or `:playoffs`) as the second parameter to skip an additional HTTP request being made by the scraper in order to fetch it: ```ruby require "ahl_scraper" AhlScraper::Games.retrieve(1022050, :regular) #=> #1022050, :season_type=>:regular, :info=>#"Friday, February 05, 2021", :name=>"BRI @ PRO", :id=>1022050, :end_time=>"3:15 pm", ... > ``` ### Players #### retrieve(player_id) Returns a `Player` object which has full details on a player by passing their id: ```ruby require "ahl_scraper" AhlScraper::Players.retrieve(6845) #=> #6845, :current_age=>0.2534e2, :position=>"D", :first_name=>"Sebastian", :handedness=>"L", :last_name=>"Aho", :birthplace=>"Umea, Sweden", :height=>"5-11", :birthdate=>"1996-02-17", :draft_year=>2014, :weight=>177, :name=>"Sebastian Aho", :jersey_number=>28}> ``` ### Teams #### list(season_id) Returns a list of `TeamListItem` objects for every team in a season by passing the season id: ```ruby require "ahl_scraper" AhlScraper::Teams.list(68) #=> [#309, :name=>"y - Providence Bruins", :season_id=>68}>, #307, :name=>"Hartford Wolf Pack", :season_id=>68}>, #317, :name=>"Bridgeport Sound Tigers", :season_id=>68}>, #319, :name=>"y - Hershey Bears", :season_id=>68}>, #313, :name=>"Lehigh Valley Phantoms", :season_id=>68}>, #324, :name=>"Syracuse Crunch", :season_id=>68}>, #... #] ``` ### PlayoffBrackets #### retrieve(season_id) Get a `PlayoffBracket` object which has series breakdowns for an entire playoff season by passing season id: ```ruby require "ahl_scraper" AhlScraper::PlayoffBrackets.retrieve(64) #=> #"https://lscluster.hockeytech.com/download.php?file_path=img/playoffs_64.jpg&client_code=ahl", :rounds=>[#[#"A", :games=>[#"", :id=>1019529, :home_team=>309, :status=>"Final", :home_score=>4, :away_score=>5, :away_team=>384, :if_necessary?=>false, :date=>"2019-04-20 19:05:00"}>, #"", :id=>1019530, :home_team=>309, :status=>"Final", :home_score=>4, :away_score=>2, :away_team=>384, :if_necessary?=>false, :date=>"2019-04-21 17:05:00"}>, ``` ### RosterPlayers #### retrieve_all(team_id, season_id) Returns an array of `RosterPlayer` objects which provide information on all of a teams roster players. Pass the team id and the season id: ```ruby require "ahl_scraper" AhlScraper::RosterPlayers.retrieve_all(335, 68) #=> [#6379, :current_age=>0.2521e2, :season_id=>68, :position=>"C", :handedness=>"L", :birthplace=>"Saskatoon, SK", :birthdate=>"1996-04-03", :height=>"6-0", :draft_year=>2014, :weight=>203, :rookie?=>false, :team_id=>335, :name=>"Rourke Chartier", :jersey_number=>15}>, #1844, :current_age=>0.3416e2, :season_id=>68, :position=>"LW", :handedness=>"L", :birthplace=>"Toronto, ON", :birthdate=>"1987-04-25", :height=>"5-11", :draft_year=>2005, :weight=>207, :rookie?=>false, :team_id=>335, :name=>"Richard Clune", :jersey_number=>17}>, #5660, :current_age=>0.2914e2, :season_id=>68, :position=>"LW", :handedness=>"L", :birthplace=>"Morristown, NJ", :birthdate=>"1992-04-30", :height=>"6-0", :draft_year=>2010, :weight=>200, :rookie?=>false, :team_id=>335, :name=>"Kenny Agostino", :jersey_number=>18}>, #... #] ``` ### PlayerGames #### list(player_id, season_id) Returns an array of `SkaterGameListItem` or `GoalieGameListItem` objects (depending on player position) which provide information on each game a player has played that season. Pass the player id and the season id: ```ruby require "ahl_scraper" AhlScraper::PlayerGames.list(304, 1) #=> [#"2005-10-08", :game_id=>1001046, :shots=>2, :goals_sh=>0, :game_name=>"BNG @ PHI", :game_winning_goals=>0, :plus_minus=>-1, :assists=>1, :points=>1, :shootout_goals=>0, :penalty_minutes=>0, :shootout_attempts=>0, :goals=>0, :goals_pp=>0}>, #"2005-10-15", :game_id=>1001069, :shots=>4, :goals_sh=>0, ... ] ``` ### TeamGames #### list(team_id, season_id) Returns an array of `TeamGameListItem` objects which provide information on each game a team has played that season. Pass the team id and the season id: ```ruby require "ahl_scraper" AhlScraper::TeamGames.list(335, 61) #=> [#false, :status=>"Final", :game_id=>1018347, :away_team=>{:id=>335, :city=>"Toronto"}, :home_team=>{:id=>390, :city=>"Utica"}, :game_name=>"Toronto @ Utica", :game_report_url=>"https://lscluster.hockeytech.com/game_reports/text-game-report.php?client_code=ahl&game_id=1018347&lang_id=1", :game_sheet_url=>"https://lscluster.hockeytech.com/game_reports/official-game-report.php?client_code=ahl&game_id=1018347&lang_id=1", :game_center_url=>"https://theahl.com/stats/game-center/1018347", :home_score=>3, :away_score=>7, :date=>"Fri, Oct 5"}>, ...] ``` ## Development After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). ## Contributing Bug reports and pull requests are welcome on GitHub at https://github.com/notnotjeff/ahl_scraper. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/ahl_scraper/blob/master/CODE_OF_CONDUCT.md). ## License The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). ## Code of Conduct Everyone interacting in the AhlScraper project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/ahl_scraper/blob/master/CODE_OF_CONDUCT.md).