footballdata-api 2026.7.2 → 2026.7.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 285333f5aeaa22a6e531e570f7d41ba43970f73d735e1faca3885d1e0c3387f7
-  data.tar.gz: 8e3fddb191ba66045b9c80526d80187b17ec05281603e17a8ea057c1779b6bd8
+  metadata.gz: 301b4ba1575a7275090ed592dce4a7da171d739d3fbd7599a4b19794d589df0d
+  data.tar.gz: 467180eeb2bdd379d40fe46021748ddfca3ed72dab132aacdf397c762b155b5e
 SHA512:
-  metadata.gz: 54da6c832674994199a490fab7a047872f45c43b0e33f399a081e94ab38157168a6882e675fab18790f2a573011fdf8f698b9a8ac3a727af9626cd4794def106
-  data.tar.gz: bcff64f55b28e0e62b08d3f7b5e4bf739755c5bf832e6026318935329aebbc82aca3d8e03d7b9a6a49e851b6a7213133a06d7ab4d9c9b5b6bdfddf36596258bc
+  metadata.gz: 0c103f1473a73a21a494b86e435182d6bfe22744b098b7f2a661b7ac2f66e4b6a81965f5d18ec0b726b950746496ce8ed44b96266a66256a625784d2f5b0ba86
+  data.tar.gz: 4d538238d329037c41ffbbe1cdfdb1f0c21309c50250c1e403855ed7599b02c459a5430d305b82e7929245c0c101d5781c3df41354b20fe233d2b496297a70f8

data/CHANGELOG.md

@@ -1,4 +1,4 @@
-### 2026.7.2
+### 2026.7.12
 ### 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-stages.rb
+lib/footballdata/convert-teams.rb
+lib/footballdata/convert_csv.rb
+lib/footballdata/convert_json.rb
 lib/footballdata/download.rb
 lib/footballdata/leagues.rb
 lib/footballdata/mods.rb

data/README.md

@@ -84,10 +84,10 @@ require 'footballdata'
  'pt.1',
  'uefa.cl',
 ].each do |league|
-  Footballdata.convert( league: league, season: '2020/21' )
+  Footballdata.convert_csv( league: league, season: '2020/21' )
 end
 
-Footballdata.convert( league: 'br.1', season: '2020' )
+Footballdata.convert_csv( league: 'br.1', season: '2020' )
 ```
 
 Note: By default all datasets get written into the `./o`

data/bin/fbdat

@@ -36,8 +36,10 @@ opts = {
    cached:  false,
    convert: true,
    file:    nil,
+   json:    nil,
 }
 
+
 parser = OptionParser.new do |parser|
   parser.banner = "Usage: #{$PROGRAM_NAME} [options] [args]"
 
@@ -51,6 +53,11 @@ parser = OptionParser.new do |parser|
     opts[:convert] = convert
   end
 
+  parser.on( "--json",
+               "turn on conversion to .json in #{Footballdata.config.convert.out_dir}" ) do |json|
+    opts[:json] = json
+  end
+
   parser.on( "--print", "--pp",
                  "pretty print cached data in #{Webcache.root}; no download & conversion") do |print|
     opts[:cached] = true
@@ -200,6 +207,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
 
@@ -243,7 +255,13 @@ if opts[:convert]
    puts "==> converting to .csv"
    datasets.each do |league_key, seasons|
       seasons.each do |season|
-         convert( league: league_key, season: season )
+       ### quick hack  - for json only conversion
+         if opts[:json]
+           convert_json( league: league_key, season: season )
+         else
+           convert_csv( league: league_key, season: season )
+           convert_json( league: league_key, season: season )
+         end
       end
    end
 end
@@ -257,4 +275,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-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-teams.rb

@@ -0,0 +1,155 @@
+
+=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 )
+
+  ##
+  ## note:  convert country code to "standard" fifa code
+  ##        use official fifa country code
+   country_name = h['area']['name']
+
+   country = Fifa.world.find_by_name( country_name )
+   if country.nil?
+     raise ArgumentError, "[fifa world] no country record found for #{country_name} for: #{h.inspect}"
+   end
+
+   country_code =  country.code
+
+
+      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:   {   name: country_name,
+                             code: country_code,
+                             code_bak: h['area']['code'] },
+
+              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
+
+            ## note - assert/make sure team name is uniq
+            if @by_name.has_key?(rec[:name])
+              raise ArgumentError, "duplicate team name - #{h.inspect}"
+            else
+              @by_name[rec[:name]] = rec
+            end
+
+            if rec[:name] != rec[:short_name]
+              if @by_name.has_key?(rec[:short_name])
+                 raise ArgumentError, "duplicate team (short) name - #{h.inspect}"
+              else
+                @by_name[rec[:short_name]] = rec
+              end
+            end
+       end
+   end
+
+
+
+   def find_by!( name: )
+        rec = @by_name[ name ]
+        if rec.nil?
+          raise ArgumentError, "team >#{name}< not found; sorry"
+        end
+
+        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 each( &blk) @recs.each( &blk); 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.rb → convert_csv.rb}

@@ -1,73 +1,50 @@
 
 module Footballdata
 
-#######
-##  map round-like to higher-level stages
-##      fix - map by league codes
-##              or * (all)
+
+####
+## beautify stages constant names
 STAGES = {
-  'REGULAR_SEASON'          => ['Regular'],
-
-  'QUALIFICATION'           => ['Qualifying'],
-  'PRELIMINARY_ROUND'       => ['Qualifying', 'Preliminary Round' ],
-  'PRELIMINARY_SEMI_FINALS' => ['Qualifying', 'Preliminary Semifinals' ],
-  'PRELIMINARY_FINAL'       => ['Qualifying', 'Preliminary Final' ],
-  '1ST_QUALIFYING_ROUND'    => ['Qualifying', 'Round 1' ],
-  '2ND_QUALIFYING_ROUND'    => ['Qualifying', 'Round 2' ],
-  '3RD_QUALIFYING_ROUND'    => ['Qualifying', 'Round 3' ],
-  'QUALIFICATION_ROUND_1'   => ['Qualifying', 'Round 1' ],
-  'QUALIFICATION_ROUND_2'   => ['Qualifying', 'Round 2' ],
-  'QUALIFICATION_ROUND_3'   => ['Qualifying', 'Round 3' ],
-  'ROUND_1'                 => ['Qualifying', 'Round 1'],    ##  use Qual. Round 1 - why? why not?
-  'ROUND_2'                 => ['Qualifying', 'Round 2'],
-  'ROUND_3'                 => ['Qualifying', 'Round 3'],
-  'PLAY_OFF_ROUND'          => ['Qualifying', 'Playoff Round'],
-  'PLAYOFF_ROUND_1'         => ['Qualifying', 'Playoff Round 1'],
-
-  'LEAGUE_STAGE'            => ['League'],
-  'GROUP_STAGE'             => ['Group'],
-  'PLAYOFFS'                => ['Playoffs'],
-
-  'ROUND_OF_16'             => ['Finals',     'Round of 16'],
-  'LAST_16'                 => ['Finals',     'Round of 16'],  ## use Last 16 - why? why not?
-  'QUARTER_FINALS'          => ['Finals',     'Quarterfinals'],
-  'SEMI_FINALS'             => ['Finals',     'Semifinals'],
-  'THIRD_PLACE'             => ['Finals',     'Third place play-off'],
-  'FINAL'                   => ['Finals',     'Final'],
+  'REGULAR_SEASON'          => 'Regular Season',
+
+  'QUALIFICATION'           => 'Qualification',
+  'PRELIMINARY_ROUND'       => 'Preliminary Round',
+  'PRELIMINARY_SEMI_FINALS' => 'Preliminary Semifinals',
+  'PRELIMINARY_FINAL'       => 'Preliminary Final',
+  '1ST_QUALIFYING_ROUND'    => '1st Qualifying Round',
+  '2ND_QUALIFYING_ROUND'    => '2nd Qualifying Round',
+  '3RD_QUALIFYING_ROUND'    => '3rd Qualifying Round',
+  'QUALIFICATION_ROUND_1'   => 'Qualification Round 1',
+  'QUALIFICATION_ROUND_2'   => 'Qualification Round 2',
+  'QUALIFICATION_ROUND_3'   => 'Qualification Round 3',
+  'ROUND_1'                 => 'Round 1',
+  'ROUND_2'                 => 'Round 2',
+  'ROUND_3'                 => 'Round 3',
+  'PLAY_OFF_ROUND'          => 'Playoff Round',
+  'PLAYOFF_ROUND_1'         => 'Playoff Round 1',
+
+  'LEAGUE_STAGE'            => 'League',      ## add Stage - why? why not?
+  'GROUP_STAGE'             => 'Group',
+  'PLAYOFFS'                => 'Playoffs',     ## -- used in champs
+  'PLAY_OFFS'               => 'Playoffs',     ## -- used in copa liber.
+
+  'LAST_32'                 => 'Round of 32',
+  'ROUND_OF_16'             => 'Round of 16',
+  'LAST_16'                 => 'Round of 16',  ## use Last 16 - why? why not?
+  'QUARTER_FINALS'          => 'Quarterfinals',
+  'SEMI_FINALS'             => 'Semifinals',
+  'THIRD_PLACE'             => 'Third place',
+  'FINAL'                   => 'Final',
 }
 
 
 
-
-
-def self.find_team_country_code( name, teams: )
-  ## add (fifa) country code e.g.
-  ##      Liverpool FC => Liverpool FC (ENG)
-  ##  or  Liverpool FC => Liverpool FC (URU)
-  rec = teams[ name ]
-  if rec.nil?
-    puts "!! ERROR - no team record found in teams.json for #{name}"
-    pp teams.keys
-    exit 1
-  end
-
-  country_name = rec['area']['name']
-  country  = Fifa.world.find_by_name( country_name )
-  if country.nil?
-    puts "!! ERROR - no country record found for #{country_name}"
-    exit 1
-  end
-
-  country.code
-end
-
-
-
-def self.convert( league:, season: )
+def self.convert_csv( 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
+  ##            e.g.  eng.1 =>  PL
   league_code = find_league!( league )
 
   matches_url = Metal.competition_matches_url( league_code, season.start_year )
@@ -77,6 +54,17 @@ def self.convert( league:, season: )
   data_teams     = Webcache.read_json( teams_url )
 
 
+  ## 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'] )
+
+
+
   ###
   ## todo/fix - use find_by!  - add upstream!!!
   league_info = LeagueCodes.find_by( code: league, season: season )
@@ -93,135 +81,102 @@ def self.convert( league:, season: )
                   'copa.l'].include?(league.downcase) ? true : false
 
 
+  mods = MODS[ league.downcase ] || {}
 
-  ## build a (reverse) team lookup by name
-  puts "#{data_teams['teams'].size} teams"
 
-  teams_by_name = data_teams['teams'].reduce( {} ) do |h,rec|
-     h[ rec['name'] ] = rec
-     h
-  end
-
-  ## pp teams_by_name.keys
-
-
-
-mods = MODS[ league.downcase ] || {}
-
-
-recs = []
-
-teams = Hash.new( 0 )
 
+  recs = []
 
-# stat  =  Stat.new
-
+  # stat  =  Stat.new
   ## track stage, match status et
   stats = { 'status'    => Hash.new(0),
             'stage'     => Hash.new(0),
            }
 
 
-
-
 matches = data[ 'matches']
 matches.each do |m|
   # stat.update( m )
 
-  ## use ? or N.N. or ? for nil  - why? why not?
-  team1 = m['homeTeam']['name'] || 'N.N.'
-  team2 = m['awayTeam']['name'] || 'N.N.'
+  # use ? or N.N. or ? for nil  - why? why not?
+  team1_name = m['homeTeam']['name']
+  team2_name = m['awayTeam']['name']
 
-   ## 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
+  team1 = team1_name ? teams.find_by!(name: team1_name ) : { name: 'N.N.' }
+  team2 = team2_name ? teams.find_by!(name: team2_name ) : { name: 'N.N.' }
 
 
+  ## use "normed" team names
+  team1_name = team1[:name]
+  team2_name = team2[:name]
 
-  score = m['score']
+  ### mods - rename club names
+  unless mods.nil? || mods.empty?
+      team1_name = mods[ team1_name ]      if mods[ team1_name ]
+      team2_name = mods[ team2_name ]      if mods[ team2_name ]
+  end
 
-  group = m['group']
-  ## GROUP_A
-  ##  shorten group to A|B|C etc.
-  if group && group =~ /^(GROUP_|Group )/
-        group =  group.sub( /^(GROUP_|Group )/, '' )
-  else
-      if group.nil?
-          group = ''
-      else
-          puts "!! WARN - group defined with NON GROUP!? >#{group}< reset to empty"
-          puts "            and matchday to >#{m['matchday']}<"
-          ## reset group to empty
-          group = ''
-      end
+  ####
+  #   auto-add (fifa) country code if int'l club tournament
+  if clubs_intl
+    if team1_name != 'N.N.'  ## note - ignore no team/placeholder (e.g. N.N)
+      team1_name = "#{team1_name} (#{team1[:country][:code]})"
+    end
+    if team2_name != 'N.N.'  ## note - ignore no team/placeholder (e.g. N.N)
+      team2_name = "#{team2_name} (#{team2[:country][:code]})"
+    end
   end
 
 
+
+
+
+  group     = m['group']
   stage_key = m['stage']
   stats['stage'][ stage_key ] += 1   ## track stage counts
+  ## add group stats?
 
 
-  stage, stage_round =  if group.empty?
-                          ## map stage to stage + round
-                          STAGES[ stage_key ]
-                        else
-                          ## if group defined ignore stage
-                          ##   hard-core always to group for now
-                           if stage_key != 'GROUP_STAGE'
-                              puts "!! WARN - group defined BUT stage set to >#{stage_key}<"
-                              puts "            and matchday to >#{m['matchday']}<"
-                           end
-                          ['Group', nil]
-                        end
+  ## GROUP_A
+  ##  shorten group to A|B|C etc.
+  if group
+    ## assert group only used with GROUP_STAGE
+   if stage_key != 'GROUP_STAGE'
+      raise ArgumentError,
+      "group defined BUT stage set to >#{stage_key}< (expected GROUP_STAGE)" +
+      "and matchday to >#{m['matchday']}<"
+    end
 
-  if stage.nil?
-      puts "!! ERROR - no stage mapping found for stage >#{stage_key}<"
-      exit 1
+    if group =~ /^(GROUP_|Group )/
+         group =  group.sub( /^(GROUP_|Group )/, '' )
+     else
+          raise ArgumentError,
+             "group defined with NON GROUP!? >#{group}< reset to empty"+
+             "            and matchday to >#{m['matchday']}<"
+     end
+  else  ## assume group.nil?
+      group = ''
   end
 
-  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.
-     matchday = matchday_num.to_s
-  else
-    ## note - if matchday/round defined, use it
-    ##        note - ignore possible leg in matchday for now
-    matchday =  stage_round
+
+
+  ## map stage to stage + round
+  ##   note - if no mapping defined; use (fallback to) upcase version
+  stage = STAGES[ stage_key ]
+
+  if stage.nil?
+      puts "!! WARN - no stage mapping found for stage >#{stage_key}<"
+      stage = stage_key
   end
 
 
-  teams[ team1 ] += 1
-  teams[ team2 ] += 1
 
+  matchday = m['matchday']
+  matchday = nil     if matchday == 0   ## change 0 to nil (empty) too
 
-    ### mods - rename club names
-    unless mods.nil? || mods.empty?
-      team1 = mods[ team1 ]      if mods[ team1 ]
-      team2 = mods[ team2 ]      if mods[ team2 ]
-    end
 
-  ####
-  #   auto-add (fifa) country code if int'l club tournament
-  if clubs_intl
-    ## note - use "original" name (not moded) for lookup
-    team1_org = m['homeTeam']['name']
-    team2_org = m['awayTeam']['name']
-    if team1_org   ## note - ignore no team/placeholder (e.g. N.N)
-      country_code = find_team_country_code( team1_org, teams: teams_by_name )
-      team1 = "#{team1} (#{country_code})"
-    end
-    if team2_org   ## note - ignore no team/placeholder (e.g. N.N)
-      country_code = find_team_country_code( team2_org, teams: teams_by_name )
-      team2 = "#{team2} (#{country_code})"
-    end
-  end
 
+    score = m['score']
 
 
     comments = ''
@@ -256,9 +211,8 @@ matches.each do |m|
       ht = ''
       comments = 'postponed'
     else
-      puts "!! ERROR: unsupported match status >#{m['status']}< - sorry:"
-      pp m
-      exit 1
+      raise ArgumentError,
+        "unsupported match status >#{m['status']}< - sorry:"
     end
 
 
@@ -297,14 +251,14 @@ matches.each do |m|
 
     recs << [stage,
              group,
-             matchday,
+             matchday.to_s,  ## not convert nil or Integer to str e.g. "", "1"
              date,
              time,
              timezone,
-             team1,
+             team1_name,
              ft,
              ht,
-             team2,
+             team2_name,
              et,
              pen,
              comments,
@@ -333,7 +287,7 @@ dates = "#{start_date.strftime('%b %-d')} - #{end_date.strftime('%b %-d')}"
 
 buf = ''
 buf << "#{season.key} (#{dates}) - "
-buf << "#{teams.keys.size} teams, "
+buf << "#{teams.size} teams, "
 buf << "#{recs.size} matches"
 # buf << "#{stat[:regular_season][:goals]} goals"
 buf << "\n"
@@ -420,27 +374,17 @@ recs, headers = vacuum( recs )
                              headers: headers )
 
 
-teams.each do |name, count|
-  rec = teams_by_name[ name ]
-  print "  #{count}x  "
-  print name
-  if rec
-    print " | #{rec['shortName']} "   if name != rec['shortName']
-    print " › #{rec['area']['name']}"
-    print "  - #{rec['address']}"
-  else
-    if name == 'N.N.'
-      ## ignore missing record
-    else
-      puts "!! ERROR  - no team record found in teams.json for #{name}"
-      exit 1
-    end
-  end
+teams.each do |rec|
+  print "  #{rec[:count]}x  "
+  print rec[:name]
+  print " | #{rec[:short_name]} "   if rec[:name] != rec[:short_name]
+  print " › #{rec[:country][:name]} (#{rec[:country][:code]})"
+  print "  - #{rec[:address]}"
   print "\n"
 end
 
 ## pp stat
-end   # method convert
+end   # method convert_csv
 
 
 
@@ -471,6 +415,9 @@ MIN_HEADERS = [   ## always keep even if all empty
 
 
 
+###
+###  move upstream to cocos!! (re)use vacuum_csv !!!!
+
 def self.vacuum( rows, headers: MAX_HEADERS, fixed_headers: MIN_HEADERS )
   ## check for unused columns and strip/remove
   counter = Array.new( MAX_HEADERS.size, 0 )
@@ -513,5 +460,3 @@ def self.vacuum( rows, headers: MAX_HEADERS, fixed_headers: MIN_HEADERS )
   [rows, headers]
 end
 end #  module Footballdata
-
-

data/lib/footballdata/convert_json.rb

@@ -0,0 +1,160 @@
+
+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_json
+
+
+end #  module Footballdata

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 = 12
   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-stages'
+require_relative 'footballdata/convert-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.12
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-07-12 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-stages.rb
+- lib/footballdata/convert-teams.rb
+- lib/footballdata/convert_csv.rb
+- lib/footballdata/convert_json.rb
 - lib/footballdata/download.rb
 - lib/footballdata/leagues.rb
 - lib/footballdata/mods.rb