footballdata-api 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 16f099d030a007993b7289956e920fd89baff6abc506feeca3dad792453efe76
+  data.tar.gz: 8f3d2df27a3dc12cc15fa2a8ee0dcd42a51ed793261a2ab2795020147596e7f6
+SHA512:
+  metadata.gz: cca1d63da2e1823a3c9cc2636953da2f691101c32b63f5004c5349338d9dd75099ac993786e038cf3e2ea8a41f3ac1ce7510cdf148f1f13a98d360203613cf99
+  data.tar.gz: 6030f680eb2e5dadd269ee78bd778c1b465914702e20fe98e55e0967346feb67a6b74d8a965dea73ce62b9c8f457ba1de811d02e26a603b90ff4d3a160b8ee99

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+### 0.2.0
+
+### 0.0.1 / 2024-07-03
+
+* Everything is new. First release.
+

data/Manifest.txt

@@ -0,0 +1,15 @@
+CHANGELOG.md
+Manifest.txt
+README.md
+Rakefile
+bin/fbdat
+lib/footballdata.rb
+lib/footballdata/convert.rb
+lib/footballdata/download.rb
+lib/footballdata/generator.rb
+lib/footballdata/leagues.rb
+lib/footballdata/mods.rb
+lib/footballdata/prettyprint.rb
+lib/footballdata/stat.rb
+lib/footballdata/teams.rb
+lib/footballdata/version.rb

data/README.md

@@ -0,0 +1,165 @@
+# footballdata-api  - get football data via Daniel Freitag's football-data.org api v4  
+
+
+* home  :: [github.com/sportdb/sport.db](https://github.com/sportdb/sport.db)
+* bugs  :: [github.com/sportdb/sport.db/issues](https://github.com/sportdb/sport.db/issues)
+* gem   :: [rubygems.org/gems/footballdata-api](https://rubygems.org/gems/footballdata-api)
+* rdoc  :: [rubydoc.info/gems/footballdata-api](http://rubydoc.info/gems/footballdata-api)
+
+
+
+## Usage
+
+
+[Daniel Freitag](https://www.football-data.org/about)'s dev-friendly football API
+offers a free to use plan
+for 12 leagues (API key sign-up and use required).
+See [`football-data.org` »](https://www.football-data.org)
+
+
+**Step 0 - Setup Secrets**
+
+Set the API key / token in the env(ironement).
+Example:
+
+```
+set FOOTBALLDATA=1234567890abcdef1234567890abcdef
+```
+
+
+**Step 1 - Download Match Schedules**
+
+Download the match schedules (in json) via api calls
+to your (local) web cache (in `~/.cache`).
+Note: The free trier has a 10 request/minute limit,
+thus, sleep/wait 10 secs after every request
+(should result in ~6 requests/minute).
+
+
+``` ruby
+require 'footballdata'
+
+
+# download up (ongoing) 2020 or 2020/21 seasons
+Webget.config.sleep  = 10
+
+Footballdata.schedule( league: 'eng.1', season: '2020/21' )
+Footballdata.schedule( league: 'eng.2', season: '2020/21' )
+
+Footballdata.schedule( league: 'de.1', season: '2020/21' )
+Footballdata.schedule( league: 'es.1', season: '2020/21' )
+
+Footballdata.schedule( league: 'fr.1', season: '2020/21' )
+Footballdata.schedule( league: 'it.1', season: '2020/21' )
+
+Footballdata.schedule( league: 'nl.1', season: '2020/21' )
+Footballdata.schedule( league: 'pt.1', season: '2020/21' )
+
+Footballdata.schedule( league: 'cl',   season: '2020/21' )
+
+# note: Brasileirão - season is a calendar year (NOT an academic year)
+Footballdata.schedule( league: 'br.1', season: '2020' )
+```
+
+Note: You can find all downloaded match schedules
+in your (local) web cache (in `~/.cache/api.football-data.org`) as pretty printed json documents.
+
+
+
+
+**Step 2 - Convert (Cached) Match Schedules to Records**
+
+Convert the (cached) match schedules
+in JSON to the one-line, one-match & one-file, one-season
+"standard" [Football.CSV format](https://github.com/footballcsv). Example:
+
+``` ruby
+require 'footballdata'
+
+['eng.1', 'eng.2',
+ 'de.1',
+ 'es.1',
+ 'fr.1',
+ 'it.1',
+ 'nl.1',
+ 'pt.1',
+ 'cl',
+].each do |league|
+  Footballdata.convert( league: league, season: '2020/21' )
+end
+
+Footballdata.convert( league: 'br.1', season: '2020' )
+```
+
+Note: By default all datasets get written into the `./o`
+directory.  Use `Footballdata.config.convert.out_dir`
+to change the output directory.
+
+The English Premier League (`eng.1`) results in `./o/2020-21/eng.1.csv`:
+
+```
+Matchday,Date,Team 1,FT,HT,Team 2,Comments
+1,Sun Sep 13 2020,Manchester City FC,(*),,Aston Villa FC,postponed
+1,Sun Sep 13 2020,Burnley FC,(*),,Manchester United FC,postponed
+1,Sat Sep 12 2020,Fulham FC,0-3,0-1,Arsenal FC,
+1,Sat Sep 12 2020,Crystal Palace FC,1-0,1-0,Southampton FC,
+1,Sat Sep 12 2020,Liverpool FC,4-3,3-2,Leeds United FC,
+1,Sat Sep 12 2020,West Ham United FC,0-2,0-0,Newcastle United FC,
+1,Sun Sep 13 2020,West Bromwich Albion FC,0-3,0-0,Leicester City FC,
+1,Sun Sep 13 2020,Tottenham Hotspur FC,0-1,0-0,Everton FC,
+1,Mon Sep 14 2020,Sheffield United FC,0-2,0-2,Wolverhampton Wanderers FC,
+1,Mon Sep 14 2020,Brighton & Hove Albion FC,1-3,0-1,Chelsea FC,
+2,Sat Sep 19 2020,Everton FC,5-2,2-1,West Bromwich Albion FC,
+2,Sat Sep 19 2020,Leeds United FC,4-3,2-1,Fulham FC,
+2,Sat Sep 19 2020,Manchester United FC,1-3,0-1,Crystal Palace FC,
+2,Sat Sep 19 2020,Arsenal FC,2-1,1-1,West Ham United FC,
+2,Sun Sep 20 2020,Southampton FC,2-5,1-1,Tottenham Hotspur FC,
+2,Sun Sep 20 2020,Newcastle United FC,0-3,0-2,Brighton & Hove Albion FC,
+2,Sun Sep 20 2020,Chelsea FC,0-2,0-0,Liverpool FC,
+2,Sun Sep 20 2020,Leicester City FC,4-2,1-1,Burnley FC,
+2,Mon Sep 21 2020,Aston Villa FC,1-0,0-0,Sheffield United FC,
+2,Mon Sep 21 2020,Wolverhampton Wanderers FC,1-3,0-2,Manchester City FC,
+...
+```
+
+Or the Brasileirão (`br.1`) in  `./o/2020/br.1.csv`:
+
+```
+Matchday,Date,Team 1,FT,HT,Team 2,Comments
+1,Sat Aug 8 2020,Fortaleza EC,0-2,0-2,CA Paranaense,
+1,Sat Aug 8 2020,Coritiba FBC,0-1,0-0,SC Internacional,
+1,Sun Aug 9 2020,SC Recife,3-2,3-1,Ceará SC,
+1,Sun Aug 9 2020,Santos FC,1-1,0-0,RB Bragantino,
+1,Sun Aug 9 2020,CR Flamengo,0-1,0-1,CA Mineiro,
+1,Sun Aug 9 2020,Goiás EC,(*),,São Paulo FC,postponed
+1,Sun Aug 9 2020,Grêmio FBPA,1-0,1-0,Fluminense FC,
+1,Sun Aug 9 2020,SE Palmeiras,(*),,CR Vasco da Gama,postponed
+2,Wed Aug 12 2020,CA Mineiro,3-2,0-2,SC Corinthians Paulista,
+2,Wed Aug 12 2020,CA Paranaense,2-1,1-1,Goiás EC,
+2,Wed Aug 12 2020,RB Bragantino,1-1,1-0,Botafogo FR,
+2,Wed Aug 12 2020,AC Goianiense,3-0,2-0,CR Flamengo,
+2,Wed Aug 12 2020,EC Bahia,1-0,1-0,Coritiba FBC,
+2,Thu Aug 13 2020,Fluminense FC,1-1,1-1,SE Palmeiras,
+2,Thu Aug 13 2020,Ceará SC,1-1,1-0,Grêmio FBPA,
+2,Thu Aug 13 2020,São Paulo FC,1-0,1-0,Fortaleza EC,
+2,Thu Aug 13 2020,SC Internacional,2-0,0-0,Santos FC,
+2,Thu Aug 13 2020,CR Vasco da Gama,2-0,2-0,SC Recife,
+...
+```
+
+
+
+That's it for now.
+
+
+
+## License
+
+The `footballdata` scripts are dedicated to the public domain.
+Use it as you please with no restrictions whatsoever.
+
+
+## Questions? Comments?
+
+Yes, you can. More than welcome.
+See [Help & Support »](https://github.com/openfootball/help)

data/Rakefile

@@ -0,0 +1,33 @@
+require 'hoe'
+require './lib/footballdata/version.rb'
+
+Hoe.spec 'footballdata-api' do
+
+  self.version = FootballdataApi::VERSION
+
+  self.summary = "footballdata-api - get football data via Daniel Freitag's football-data.org api v4"
+  self.description = summary
+
+  self.urls = { home: 'https://github.com/sportdb/sport.db' }
+
+  self.author = 'Gerald Bauer'
+  self.email  = 'gerald.bauer@gmail.com'
+
+  # switch extension to .markdown for gihub formatting
+  self.readme_file  = 'README.md'
+  self.history_file = 'CHANGELOG.md'
+
+  self.extra_deps = [
+    ['tzinfo'],
+    ['season-formats'], 
+    ['webget'],    
+    ['cocos'],  ## later pull in with sportsdb-writers
+  ]
+
+  self.licenses = ['Public Domain']
+
+  self.spec_extras = {
+   required_ruby_version: '>= 2.2.2'
+  }
+
+end

data/bin/fbdat

@@ -0,0 +1,200 @@
+#!/usr/bin/env ruby
+
+## tip: to test run:
+##   ruby -I ./lib bin/fbdat
+
+require 'footballdata'
+
+
+load_env   ## use dotenv (.env)
+
+
+Webcache.root =  if File.exist?( '/sports/cache' )
+                     puts "  setting web cache to >/sports/cache<"
+                     '/sports/cache'
+                 else 
+                     './cache'
+                 end
+
+## note -  free tier (tier one) plan - 10 requests/minute   
+##              (one request every 6 seconds 6*10=60 secs)
+##     10 API calls per minute max.
+##  note - default sleep (delay in secs) is 3 sec(s)
+Webget.config.sleep  = 10
+
+
+
+
+require 'optparse'
+
+
+
+module Footballdata
+def self.main( args=ARGV )
+
+opts = {}
+parser = OptionParser.new do |parser|
+  parser.banner = "Usage: #{$PROGRAM_NAME} [options]"
+
+  parser.on( "--cache", "--cached", "--offline",
+               "use cached data in #{Webcache.root}" ) do |cached|
+    opts[:cached] = cached
+  end
+end
+parser.parse!( args )
+
+puts "OPTS:"
+p opts
+puts "ARGV:"
+p args
+
+
+## try special args
+
+if ['plan', 'plans', 
+    'comp', 'comps'].include?(args[0]) 
+
+    if opts[:cached]
+        ## do nothing
+    else    
+      Metal.competitions( auth: true )   ## get free tier (TIER_ONE) with auth (token)
+    end
+
+  url = Metal.competitions_url
+  pp url
+  #=> "http://api.football-data.org/v4/competitions"
+   
+  data = Webcache.read_json( url )
+  pp data
+    
+  comps = data['competitions']  
+  comps.each do |rec|
+      print "==> "
+      print "#{rec['area']['name']} (#{rec['area']['code']}) - "
+      print "#{rec['name']} (#{rec['code']}) -- "
+      print "#{rec['plan']} #{rec['type']}, "
+      print "#{rec['numberOfAvailableSeasons']} season(s)"
+      print "\n"
+  
+      print "     #{rec['currentSeason']['startDate']} - #{rec['currentSeason']['endDate']} "  
+      print "@ #{rec['currentSeason']['currentMatchday']}"
+      print "\n"
+  end
+  
+  puts "  #{comps.size} competition(s)"
+  exit 0
+end
+
+
+###
+#  pretty print today's matches  (tomorrow/yesterday/etc.)
+
+
+##
+## note - cannot use t for today (used for tomorrow)
+##             find a different shortcode - why? why not?
+
+### note - today is default if no args passed in!!!
+
+##
+## todo - add more date offsets - t+2,t+3,t+4, etc.
+
+date =  if ['y', 'yesterday', 't-1', '-1'].include?( args[0] )
+            Date.today-1       
+        elsif ['t', 'tomorrow', 't+1', '1', '+1'].include?( args[0] )
+            Date.today+1        
+        elsif ['m', 'match', 'matches', 'today'].include?( args[0] || 'today' )  ## make default - why? why not?
+            Date.today
+        else
+            nil
+        end
+
+if date
+  if opts[:cached] 
+      ## do nothing
+  else
+     Metal.todays_matches( date )
+  end
+
+  data = Webcache.read_json( Metal.todays_matches_url( date ) )
+  pp data
+
+  last_comp = nil
+  data['matches'].each do |rec|
+    ## only print competition header if different from last match
+    comp = fmt_competition( rec )
+    puts comp   if comp != last_comp
+    
+    puts fmt_match( rec )
+
+    last_comp = comp
+  end
+  exit 0
+end
+
+
+
+###
+#  league and season - pretty print matches
+#
+##  samples:
+##   national teams
+##    EC 2024  - euro
+##    EC 2021
+##    WC 2022  - world cup
+##   club cups intl
+##    CL 2023  - (uefa/european) champions league
+##    CLI 2204 - (south american) copa libertadores
+##   club leagues 
+##    PL 2024  - england premiere league
+
+
+league_code       = args[0] || 'PL'
+
+###  convenience helpers - lets you use eng.1, euro, etc.
+## check if mapping for league_code
+if LEAGUES.has_key?( league_code.downcase )
+  league_code = LEAGUES[ league_code.downcase ]
+else
+   ## assume  "native" code
+   ##  always upcase e.g. pl => PL etc.
+   league_code = league_code.upcase
+end
+
+
+season            = Season( args[1] ||  
+                             (league_code == 'EC' ? '2024' : '2024/25'))
+
+season_start_year  = season.start_year   ## use year - why? why not?
+
+pp league_code, season_start_year
+
+if opts[:cached]
+    ## do nothing
+else
+    ## download dataset(s)
+    ## try download
+    Metal.matches( league_code, 
+                   season_start_year )
+end    
+
+url = Metal.competition_matches_url( league_code, 
+                                      season_start_year )
+pp url
+#=> "http://api.football-data.org/v4/competitions/EC/matches?season=2024"
+
+data = Webcache.read_json( url )
+## pp data
+
+pp_matches( data )
+
+end  # def self.main
+end  # module Footballdata
+
+
+
+Footballdata.main( ARGV )
+
+
+puts "bye"
+