footballdata-api 2026.7.2 → 2026.7.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 285333f5aeaa22a6e531e570f7d41ba43970f73d735e1faca3885d1e0c3387f7
-  data.tar.gz: 8e3fddb191ba66045b9c80526d80187b17ec05281603e17a8ea057c1779b6bd8
+  metadata.gz: 7dc56c0d0418eab7317862787fc928fe1102785d1768f75b242fb3ab52e140b6
+  data.tar.gz: 83fcf18d6a491b1cc9cff38a38de13cbdfe184b9400ae78678aa479b5517ff92
 SHA512:
-  metadata.gz: 54da6c832674994199a490fab7a047872f45c43b0e33f399a081e94ab38157168a6882e675fab18790f2a573011fdf8f698b9a8ac3a727af9626cd4794def106
-  data.tar.gz: bcff64f55b28e0e62b08d3f7b5e4bf739755c5bf832e6026318935329aebbc82aca3d8e03d7b9a6a49e851b6a7213133a06d7ab4d9c9b5b6bdfddf36596258bc
+  metadata.gz: c3c0a16979fc71e903180ddae103249350461d48dab182f90afc94c06b1230e0c1de624b8c1517c79f3a80bb3fadf84d3d7519a64358a96e52fc877b7df6f803
+  data.tar.gz: 04ac3d92c132dcce5277300e8ffae5b46eaa16dcede2b780574dbf8a98c6b098fab1e9e2d27231e4fd0aab81a12b8dcc9205c3065f70f79aa48135b9f49894fd

data/CHANGELOG.md

@@ -1,4 +1,4 @@
-### 2026.7.2
+### 2026.7.11
 ### 0.0.1 / 2024-07-03
 
 * Everything is new. First release.

data/Manifest.txt

@@ -6,7 +6,10 @@ bin/fbdat
 config/leagues_tier1.csv
 lib/footballdata.rb
 lib/footballdata/convert-score.rb
-lib/footballdata/convert.rb
+lib/footballdata/convert_csv.rb
+lib/footballdata/convert_json-stages.rb
+lib/footballdata/convert_json-teams.rb
+lib/footballdata/convert_json.rb
 lib/footballdata/download.rb
 lib/footballdata/leagues.rb
 lib/footballdata/mods.rb

data/bin/fbdat

@@ -200,6 +200,11 @@ autofiller = ->(league_query) {
 datasets = if opts[:file]
               read_leagueset( opts[:file], autofill: autofiller )
            else
+
+               ### todo or fix/fix/fix - change to build_leagueset
+               ##                       and reserve parse_leagueset( txt ) for
+               ##                                  read_leagueset with inline text
+
               parse_leagueset_args( args, autofill: autofiller )
            end
 
@@ -244,6 +249,7 @@ if opts[:convert]
    datasets.each do |league_key, seasons|
       seasons.each do |season|
          convert( league: league_key, season: season )
+         convert_json( league: league_key, season: season )
       end
    end
 end
@@ -257,4 +263,3 @@ Footballdata.main( ARGV )
 
 
 puts "bye"
-

data/config/leagues_tier1.csv

@@ -1,44 +1,44 @@
 key, code, seasons
 
-eng.1,    PL,    2024/25 2023/24 2022/23 2021/22 2020/21
+eng.1,    PL,    2026/27 2025/26 2024/25 2023/24 2022/23 2021/22 2020/21
     # incl. team(s) from wales
-eng.2,    ELC,    2024/25 2023/24 2022/23 2021/22 2020/21
+eng.2,    ELC,    2026/27 2025/26 2024/25 2023/24 2022/23 2021/22 2020/21
      #  PL  - Premier League, England        27 seasons | 2019-08-09 - 2020-07-25 / matchday 31
      #  ELC - Championship,  England         3 seasons | 2019-08-02 - 2020-07-22 / matchday 38
 
-es.1,    PD,    2024/25 2023/24 2022/23 2021/22 2020/21
+es.1,    PD,    2026/27 2025/26 2024/25 2023/24 2022/23 2021/22 2020/21
     # PD  - Primera Division, Spain          27 seasons | 2019-08-16 - 2020-07-19 / matchday 31
 
-pt.1,     PPL,    2024/25 2023/24 2022/23 2021/22 2020/21
+pt.1,     PPL,    2026/27 2025/26 2024/25 2023/24 2022/23 2021/22 2020/21
     # PPL - Primeira Liga, Portugal        9 seasons | 2019-08-10 - 2020-07-26 / matchday 28
 
-de.1,     BL1,    2024/25 2023/24 2022/23 2021/22 2020/21
+de.1,     BL1,    2026/27 2025/26 2024/25 2023/24 2022/23 2021/22 2020/21
     # BL1 - Bundesliga, Germany        24 seasons | 2019-08-16 - 2020-06-27 / matchday 34
 
-nl.1,     DED,    2024/25 2023/24 2022/23 2021/22 2020/21
+nl.1,     DED,    2026/27 2025/26 2024/25 2023/24 2022/23 2021/22 2020/21
     # DED - Eredivisie, Netherlands    10 seasons | 2019-08-09 - 2020-03-08 / matchday 34
 
-fr.1,     FL1,    2024/25 2023/24 2022/23 2021/22 2020/21
+fr.1,     FL1,    2026/27 2025/26 2024/25 2023/24 2022/23 2021/22 2020/21
     # incl. team(s) monaco
 
-it.1,      SA,    2024/25 2023/24 2022/23 2021/22 2020/21
+it.1,      SA,    2026/27 2025/26 2024/25 2023/24 2022/23 2021/22 2020/21
     # SA  - Serie A, Italy          15 seasons | 2019-08-24 - 2020-08-02 / matchday 27
 
-br.1,       BSA,     2025 2024 2023 2022 2021 2020
+br.1,       BSA,     2026 2025 2024 2023 2022 2021 2020
 
 
 ########
 ## int'l cups
-uefa.cl,    CL,    2024/25 2023/24 2022/23 2021/22 2020/21
+uefa.cl,    CL,    2025/26 2024/25 2023/24 2022/23 2021/22 2020/21
     ## note: cl is country code for chile!! - use champs - why? why not?
     ##  was europe.cl / cl
     ## todo/check: use champs and NOT cl - why? why not?
 
-copa.l,     CLI,    2025 2024 2023 2022 2021
+copa.l,     CLI,    2026 2025 2024 2023 2022 2021
    ## Copa Libertadores
 
 
 ############
 ## national teams
 euro,       EC,   2024 2021
-world,      WC,   2022
+world,      WC,   2026 2022

data/lib/footballdata/convert-score.rb

@@ -1,6 +1,15 @@
 
 module Footballdata
 
+##
+## note - "weirdo" rule
+##   fullTime is only "classic" fulltime if REGULAR
+##
+##  otherwise fullTime is aggregate of extraTime AND penalties!!
+##
+##
+
+
 def self.convert_score( score )
   ## duration: REGULAR  · PENALTY_SHOOTOUT  · EXTRA_TIME
   ft, ht, et, pen = ["","","",""]
@@ -41,4 +50,54 @@ def self.convert_score( score )
 
   [ft,ht,et,pen]
 end
+
+
+
+def self.convert_score_to_hash( score )
+  ## duration: REGULAR  · PENALTY_SHOOTOUT  · EXTRA_TIME
+
+  if score['duration'] == 'REGULAR'
+    { ft: [score['fullTime']['home'],
+           score['fullTime']['away']],
+      ht: [score['halfTime']['home'],
+           score['halfTime']['away']]
+    }
+  elsif score['duration'] == 'EXTRA_TIME'
+    { et: [score['regularTime']['home']+score['extraTime']['home'],
+           score['regularTime']['away']+score['extraTime']['away']],
+      ft: [score['regularTime']['home'],
+           score['regularTime']['away']],
+      ht: [score['halfTime']['home'],
+           score['halfTime']['away']]
+    }
+
+  elsif score['duration'] == 'PENALTY_SHOOTOUT'
+    if score['extraTime']
+      ## quick & dirty hack - calc et via regulartime+extratime
+      { pen: [score['penalties']['home'],
+              score['penalties']['away']],
+        et:  [score['regularTime']['home']+score['extraTime']['home'],
+              score['regularTime']['away']+score['extraTime']['away']],
+        ft:  [score['regularTime']['home'],
+              score['regularTime']['away']],
+        ht:  [score['halfTime']['home'],
+              score['halfTime']['away']]
+      }
+    else  ### south american-style (no extra time)
+        ## quick & dirty hacke - calc ft via fullTime-penalties
+       { pen: [score['penalties']['home'],
+               score['penalties']['away']],
+         ft:  [score['fullTime']['home']-score['penalties']['home'],
+               score['fullTime']['away']-score['penalties']['away']],
+         ht:  [score['halfTime']['home'],
+               score['halfTime']['away']]
+       }
+    end
+  else
+    raise ArgumentError, "!! unknown score duration - #{score.inspect}"
+  end
+end
+
+
+
 end  # module Footballdata

data/lib/footballdata/{convert.rb → convert_csv.rb}

@@ -26,8 +26,10 @@ STAGES = {
 
   'LEAGUE_STAGE'            => ['League'],
   'GROUP_STAGE'             => ['Group'],
-  'PLAYOFFS'                => ['Playoffs'],
+  'PLAYOFFS'                => ['Playoffs'],   ## used in champs
+  'PLAY_OFFS'               => ['Playoffs'],   ## used in copa liber.
 
+  'LAST_32'                 => ['Finals',     'Round of 32'],
   'ROUND_OF_16'             => ['Finals',     'Round of 16'],
   'LAST_16'                 => ['Finals',     'Round of 16'],  ## use Last 16 - why? why not?
   'QUARTER_FINALS'          => ['Finals',     'Quarterfinals'],
@@ -67,7 +69,7 @@ def self.convert( league:, season: )
 
   season = Season( season )   ## cast (ensure) season class (NOT string, integer, etc.)
 
-  ### note - find_league returns the metal_league_code 
+  ### note - find_league returns the metal_league_code
   league_code = find_league!( league )
 
   matches_url = Metal.competition_matches_url( league_code, season.start_year )
@@ -132,12 +134,6 @@ matches.each do |m|
   team1 = m['homeTeam']['name'] || 'N.N.'
   team2 = m['awayTeam']['name'] || 'N.N.'
 
-   ## auto-fix copa.l 2024
-   ##  !! ERROR: unsupported match status >IN_PLAY< - sorry:
-   if m['status'] == 'IN_PLAY' &&
-      team1 == 'Club Aurora' && team2 == 'FBC Melgar'
-        m['status'] = 'FINISHED'
-   end
 
 
 
@@ -185,6 +181,7 @@ matches.each do |m|
   matchday_num = m['matchday']
   matchday_num = nil   if matchday_num == 0   ## change 0 to nil (empty) too
 
+
   if stage_round.nil?  ## e.g. Regular, League, Group, Playoffs
      ## keep/assume matchday number is matchday .e.g
      ##   matchday 1, 2 etc.
@@ -206,6 +203,7 @@ matches.each do |m|
       team2 = mods[ team2 ]      if mods[ team2 ]
     end
 
+
   ####
   #   auto-add (fifa) country code if int'l club tournament
   if clubs_intl
@@ -513,5 +511,3 @@ def self.vacuum( rows, headers: MAX_HEADERS, fixed_headers: MIN_HEADERS )
   [rows, headers]
 end
 end #  module Footballdata
-
-

data/lib/footballdata/convert_json-stages.rb

@@ -0,0 +1,20 @@
+
+class Stages
+   def initialize
+      @recs = {}
+   end
+
+   def add_matches( matches )
+       matches.each do |m|
+            name  =  m['stage']
+            rec =  @recs[name] ||= { name: name,
+                                     count: 0    }
+            rec[:count] +=1
+       end
+   end
+
+   def as_json() @recs.values; end
+
+   def size() @recs.size; end
+
+end  # class Stages

data/lib/footballdata/convert_json-teams.rb

@@ -0,0 +1,124 @@
+
+=begin
+
+note - for address "null null null",
+   is   street + city + postal_code/
+
+
+ {"area"=>{"id"=>2061, "name"=>"Cyprus", "code"=>"CYP", "flag"=>nil},
+    "id"=>11034,
+    "name"=>"Paphos FC",
+    "shortName"=>"Paphos FC",
+    "tla"=>"AEP",
+    "address"=>"null null null",
+    "website"=>nil,
+    "founded"=>nil,
+    "clubColors"=>nil,
+    "venue"=>"Alphamega Stadium",
+
+ {"area"=>{"id"=>2119, "name"=>"Kazakhstan", "code"=>"KAZ", "flag"=>nil},
+    "id"=>10601,
+    "name"=>"FK Kairat",
+    "shortName"=>"FK Kairat",
+    "tla"=>"KAI",
+    "address"=>"null null null",
+    "website"=>nil,
+    "founded"=>nil,
+    "clubColors"=>nil,
+    "venue"=>nil,
+
+     {"area"=>{"id"=>2060, "name"=>"Curaçao", "code"=>"CUW", "flag"=>"https://crests.football-data.org/curacao.svg"},
+    "id"=>9460,
+    "name"=>"Curaçao",
+    "shortName"=>"Curaçao",
+    "tla"=>"CUW",
+    "address"=>"null null null",
+    "website"=>nil,
+    "founded"=>nil,
+    "clubColors"=>nil,
+    "venue"=>nil,
+
+
+
+=end
+
+
+
+def build_team( h )
+
+      rec = { id:         h['id'],
+              name:       h['name'],
+              short_name: h['shortName'],
+              code:       h['tla'],
+              address:    h['address'],    ###  street / city / postal_code
+              founded:    h['founded'],
+              ground:     h['venue'],     ### use stadium or venue ??
+
+              ##
+              ##  or use country { code:, name }
+              ## change to cc (country code) - why? why not?
+              country:   {  code: h['area']['code'],
+                            name: h['area']['name'] },
+
+              count:      0,   ## track - match counts
+        }
+
+     rec
+end
+
+
+class Teams
+   def initialize
+      @recs    = []
+      @by_name = {}
+   end
+
+
+   def add( recs )
+       recs.each do |h|
+            rec = build_team( h )
+            @recs << rec
+
+            ## todo/fix - make sure team name is uniq!!!!
+            @by_name[rec[:name]]       = rec
+            @by_name[rec[:short_name]] = rec
+       end
+   end
+
+
+
+   def find_by!( name: )
+        rec = @by_name[ name ]
+        raise ArgumentError, "team >#{name}< not found; sorry"   if rec.nil?
+        rec
+   end
+
+
+   def add_matches( matches )  ## use/rename to add_matches - why? why not?
+      matches.each do |m|
+
+        ## note - skip teams without name (e.g. N.N.)
+        if m['homeTeam']['name']
+          rec = find_by!( name: m['homeTeam']['name'] )
+          rec[:count] += 1
+        end
+
+        if m['awayTeam']['name']
+          rec = find_by!( name: m['awayTeam']['name'] )
+          rec[:count] += 1
+        end
+      end
+   end
+
+
+   def as_json( id: false )
+      if id
+        @recs
+      else
+        @recs.map { |rec| rec.except(:id ) }
+      end
+   end
+
+   def size() @recs.size; end
+
+end  # class Teams

data/lib/footballdata/convert_json.rb

@@ -0,0 +1,186 @@
+
+module Footballdata
+
+
+
+
+
+def self.convert_json( league:, season: )
+
+  season = Season( season )   ## cast (ensure) season class (NOT string, integer, etc.)
+
+  ### note - find_league returns the metal_league_code
+  league_code = find_league!( league )
+
+  matches_url = Metal.competition_matches_url( league_code, season.start_year )
+  teams_url   = Metal.competition_teams_url(   league_code, season.start_year )
+
+  data           = Webcache.read_json( matches_url )
+  data_teams     = Webcache.read_json( teams_url )
+
+
+  ## note - for international club tournaments
+  ##         auto-add (fifa) country code e.g.
+  ##      Liverpool FC  => Liverpool FC (ENG)
+  ##
+  ##  todo/fix -  move flag to league_info via .csv config - why? why not?
+  ## clubs_intl  =  ['uefa.cl',
+  ##                 'copa.l'].include?(league.downcase) ? true : false
+
+  ## build a team lookup by name (& short_name)
+
+  teams = Teams.new
+  teams.add( data_teams['teams'] )
+  puts "#{teams.size} team(s)"
+
+  ## add/update match counts
+  teams.add_matches( data['matches'] )
+
+
+  stages = Stages.new
+  stages.add_matches( data['matches'] )
+
+
+  recs = []
+
+
+  ## track (meta stats) stage, match status et
+  stats = {  status: Hash.new(0),   ## e.g. TIMED,etc
+             score:  Hash.new(0),   ## e.g.  REGULAR,etc.
+           }
+
+
+
+
+  data[ 'matches'].each do |m|
+
+     ## use ? or N.N. or ? for nil  - why? why not?
+     team1_name = m['homeTeam']['name']
+     team2_name = m['awayTeam']['name']
+
+     team1 = team1_name ? teams.find_by!(name: team1_name ) : { name: 'N.N.' }
+     team2 = team2_name ? teams.find_by!(name: team2_name ) : { name: 'N.N.' }
+
+
+  stage = m['stage']
+  group = m['group']
+
+  matchday = m['matchday']
+  matchday = nil       if matchday == 0   ## change 0 to nil (empty) too
+
+
+    stats[:status][m['status']]           += 1  ## track status counts
+    stats[:score][m['score']['duration']] += 1
+
+    case m['status']
+    when 'SCHEDULED', 'TIMED',
+         'PAUSED',    'IN_PLAY'   ## IN_PLAY, PAUSED
+      score = []
+    when 'FINISHED'
+      score = convert_score_to_hash( m['score'] )
+    when 'AWARDED'   # AWARDED
+      assert( m['score']['duration'] == 'REGULAR', 'score.duration REGULAR expected' )
+      score = [m['score']['fullTime']['home'],
+               m['score']['fullTime']['away']]
+    when 'CANCELLED'
+      ## note cancelled might have scores!! -- add/fix later!!!
+      ##   ht only or ft+ht!!!  (see fr 2021/22)
+      ## score = convert_score_to_hash( m['score'] )
+      ##
+      ##  note - there is cancelled (e.g. not/played)  AND
+      ##                  annulled/voided (e.g. played!! with score)
+      score = []
+    when 'POSTPONED'
+      score = []
+    else
+      raise ArgumentError,
+              "unsupported match status >#{m['status']}< - sorry: #{m.pretty_inspect}"
+    end
+
+
+
+    rec = {
+        status: m['status'],
+        stage:    stage
+    }
+
+
+    utc = UTC.strptime( m['utcDate'], '%Y-%m-%dT%H:%M:%SZ' )
+    assert( utc.strftime( '%Y-%m-%dT%H:%M:%SZ' ) == m['utcDate'], 'utc time mismatch' )
+
+
+    ## do NOT add time if status is SCHEDULED
+    ##                        or POSTPONED for now
+    ##   otherwise assume time always present - why? why not?
+    ##
+    ## assume NOT valid utc time if 00:00
+    if utc.hour == 0 && utc.min == 0 &&
+       ['SCHEDULED','POSTPONED'].include?( m['status'] )
+       ## assume local date - why? why not?
+       rec[:date]     = utc.strftime( '%Y-%m-%d' )
+    else
+       rec[:date_utc] = utc.strftime( '%Y-%m-%dT%H:%M:%SZ' )
+    end
+
+
+
+    rec[:group]     =   group      if group
+    rec[:matchday]  =   matchday   if matchday
+
+    rec[:team1] =  team1[:name]
+    rec[:team2] =  team2[:name]
+
+    rec[:score] = score     unless score.empty?
+
+
+    recs << rec
+  end
+
+
+  stats[:matches] = recs.size
+  stats[:teams]   = teams.size
+
+  data = {
+     slug:   league,
+     season: season.to_s,
+     meta:   stats,
+     stages: stages.as_json,
+     teams:  teams.as_json,
+     matches: recs
+  }
+
+
+  path = "#{config.convert.out_dir}/#{season.to_path}/#{league.downcase}.json"
+  ## note: change season_key from 2019/20 to 2019-20  (for path/directory!!!!)
+  puts "  writing to >#{path}<"
+  write_json( path, data )
+end   # method convert
+
+
+end #  module Footballdata
+
+
+
+__END__
+
+## note: get season from first match
+##   assert - all other matches include the same season
+## e.g.
+# "season": {
+#  "id": 154,
+#  "startDate": "2018-08-03",
+#  "endDate": "2019-05-05",
+#  "currentMatchday": 46
+# }
+
+start_date = Date.strptime( matches[0]['season']['startDate'], '%Y-%m-%d' )
+end_date   = Date.strptime( matches[0]['season']['endDate'],   '%Y-%m-%d' )
+
+dates = "#{start_date.strftime('%b %-d')} - #{end_date.strftime('%b %-d')}"
+
+buf = ''
+buf << "#{season.key} (#{dates}) - "
+buf << "#{teams.keys.size} teams, "
+buf << "#{recs.size} matches"
+# buf << "#{stat[:regular_season][:goals]} goals"
+buf << "\n"

data/lib/footballdata/download.rb

@@ -53,6 +53,7 @@ class Metal
 
     request_headers = request_headers.merge( headers )   unless headers.empty?
 
+    ## pp request_headers
 
     ## note: add format: 'json' for pretty printing json (before) save in cache
     response = Webget.call( url, headers: request_headers )
@@ -117,10 +118,12 @@ class Metal
    get( "#{BASE_URL}/teams/#{id}" )
  end
 
- def self.match( id )
-   get( "#{BASE_URL}/matches/#{id}" )
+
+ def self.match( id, headers: {} )
+   get( "#{BASE_URL}/matches/#{id}", headers: headers )
  end
 
+
  def self.person( id )
   get( "#{BASE_URL}/persons/#{id}" )
  end

data/lib/footballdata/leagues.rb

@@ -1,3 +1,10 @@
+
+##
+##  todo/fix cleanup
+##    use a "generic" record for lookup
+##
+
+
 module Footballdata
 
   def self.find_league!( league )
@@ -48,4 +55,3 @@ module Footballdata
      seasons
   end
 end   #  module Footballdata
-

data/lib/footballdata/version.rb

@@ -2,7 +2,7 @@
 module FootballdataApi
   MAJOR = 2026    ## todo: namespace inside version or something - why? why not??
   MINOR = 7
-  PATCH = 2
+  PATCH = 11
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 
   def self.version

data/lib/footballdata.rb

@@ -36,8 +36,13 @@ require_relative 'footballdata/download'
 require_relative 'footballdata/prettyprint'
 
 require_relative 'footballdata/mods'
-require_relative 'footballdata/convert'
+require_relative 'footballdata/convert_csv'
+require_relative 'footballdata/convert_json'
+require_relative 'footballdata/convert_json-stages'
+require_relative 'footballdata/convert_json-teams'
 require_relative 'footballdata/convert-score'
+
+
 require_relative 'footballdata/teams'
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: footballdata-api
 version: !ruby/object:Gem::Version
-  version: 2026.7.2
+  version: 2026.7.11
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: leagues
@@ -105,7 +105,10 @@ files:
 - config/leagues_tier1.csv
 - lib/footballdata.rb
 - lib/footballdata/convert-score.rb
-- lib/footballdata/convert.rb
+- lib/footballdata/convert_csv.rb
+- lib/footballdata/convert_json-stages.rb
+- lib/footballdata/convert_json-teams.rb
+- lib/footballdata/convert_json.rb
 - lib/footballdata/download.rb
 - lib/footballdata/leagues.rb
 - lib/footballdata/mods.rb