footballdata-api 2026.7.11 → 2026.7.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dc56c0d0418eab7317862787fc928fe1102785d1768f75b242fb3ab52e140b6
-  data.tar.gz: 83fcf18d6a491b1cc9cff38a38de13cbdfe184b9400ae78678aa479b5517ff92
+  metadata.gz: 301b4ba1575a7275090ed592dce4a7da171d739d3fbd7599a4b19794d589df0d
+  data.tar.gz: 467180eeb2bdd379d40fe46021748ddfca3ed72dab132aacdf397c762b155b5e
 SHA512:
-  metadata.gz: c3c0a16979fc71e903180ddae103249350461d48dab182f90afc94c06b1230e0c1de624b8c1517c79f3a80bb3fadf84d3d7519a64358a96e52fc877b7df6f803
-  data.tar.gz: 04ac3d92c132dcce5277300e8ffae5b46eaa16dcede2b780574dbf8a98c6b098fab1e9e2d27231e4fd0aab81a12b8dcc9205c3065f70f79aa48135b9f49894fd
+  metadata.gz: 0c103f1473a73a21a494b86e435182d6bfe22744b098b7f2a661b7ac2f66e4b6a81965f5d18ec0b726b950746496ce8ed44b96266a66256a625784d2f5b0ba86
+  data.tar.gz: 4d538238d329037c41ffbbe1cdfdb1f0c21309c50250c1e403855ed7599b02c459a5430d305b82e7929245c0c101d5781c3df41354b20fe233d2b496297a70f8

data/CHANGELOG.md

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

data/Manifest.txt

@@ -6,9 +6,9 @@ bin/fbdat
 config/leagues_tier1.csv
 lib/footballdata.rb
 lib/footballdata/convert-score.rb
+lib/footballdata/convert-stages.rb
+lib/footballdata/convert-teams.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

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
@@ -248,8 +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 )
-         convert_json( 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

data/lib/footballdata/{convert_json-teams.rb → convert-teams.rb}

@@ -43,9 +43,21 @@ note - for address "null null null",
 =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'],
@@ -57,8 +69,9 @@ def build_team( h )
               ##
               ##  or use country { code:, name }
               ## change to cc (country code) - why? why not?
-              country:   {  code: h['area']['code'],
-                            name: h['area']['name'] },
+              country:   {   name: country_name,
+                             code: country_code,
+                             code_bak: h['area']['code'] },
 
               count:      0,   ## track - match counts
         }
@@ -68,6 +81,7 @@ end
 
 
 class Teams
+
    def initialize
       @recs    = []
       @by_name = {}
@@ -79,9 +93,20 @@ class Teams
             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
+            ## 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
 
@@ -89,7 +114,10 @@ class Teams
 
    def find_by!( name: )
         rec = @by_name[ name ]
-        raise ArgumentError, "team >#{name}< not found; sorry"   if rec.nil?
+        if rec.nil?
+          raise ArgumentError, "team >#{name}< not found; sorry"
+        end
+
         rec
    end
 
@@ -110,6 +138,9 @@ class Teams
       end
    end
 
+   def each( &blk) @recs.each( &blk); end
+
+
 
    def as_json( id: false )
       if id

data/lib/footballdata/convert_csv.rb

@@ -1,75 +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'],   ## 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'],
-  '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
+  ##            e.g.  eng.1 =>  PL
   league_code = find_league!( league )
 
   matches_url = Metal.competition_matches_url( league_code, season.start_year )
@@ -79,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 )
@@ -95,131 +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 )
-
-
-# stat  =  Stat.new
+  recs = []
 
+  # 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']
 
+  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
-  end
+  ## 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
 
 
-    ### mods - rename club names
-    unless mods.nil? || mods.empty?
-      team1 = mods[ team1 ]      if mods[ team1 ]
-      team2 = mods[ team2 ]      if mods[ team2 ]
-    end
+  matchday = m['matchday']
+  matchday = nil     if matchday == 0   ## change 0 to nil (empty) too
 
 
-  ####
-  #   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 = ''
@@ -254,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
 
 
@@ -295,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,
@@ -331,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"
@@ -418,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
 
 
 
@@ -469,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 )

data/lib/footballdata/convert_json.rb

@@ -154,33 +154,7 @@ def self.convert_json( league:, season: )
   ## 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   # method convert_json
 
 
 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/version.rb

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

data/lib/footballdata.rb

@@ -38,8 +38,8 @@ require_relative 'footballdata/prettyprint'
 require_relative 'footballdata/mods'
 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-stages'
+require_relative 'footballdata/convert-teams'
 require_relative 'footballdata/convert-score'
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: footballdata-api
 version: !ruby/object:Gem::Version
-  version: 2026.7.11
+  version: 2026.7.12
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-11 00:00:00.000000000 Z
+date: 2026-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: leagues
@@ -105,9 +105,9 @@ files:
 - config/leagues_tier1.csv
 - lib/footballdata.rb
 - lib/footballdata/convert-score.rb
+- lib/footballdata/convert-stages.rb
+- lib/footballdata/convert-teams.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