Frequently Asked Questions and Answers (FAQs)


Download Pre-Built Copies or Build Your Own

Q: Where can I get (download) pre-built copies e.g. football.db, worldcup.db, england.db etc.?

A: You can get (download) pre-built single-file SQLite databases copies (working anywhere, that is, Windows, Mac, Linux, etc.) on the releases page. For example, find the worldcup.db download at the /world-cup Releases page.

Note: For now only some datasets (e.g. worldcup.db) have pre-built database releases.

Q: How can I get started building my own up-to-date copy using the latest datasets?

A: The recommended quick starter way to build your own up-to-data (local) copy from the online datasets is using datafiles. See the /datafile repo for ready-to-use quick starter datafile samples.

Let’s build a copy of all world cups (from Uruguay 1930 to Russia 2018). Use the worldcup.rb datafile. Type:

$ sportdb new worldcup

This command will run the following steps:

That’s it. Now you will have a new up-to-date single-file sport.db SQLite database in your working folder.

If you have questions or commentary as you go along building your own up-to-date database copies, please post them to the forum / mailing list maybe someone can help you out. All the best. Good luck. Bonus: Why not write a step-by-step build guide yourself and share it with the world?

Real-Time Result / Score HTTP JSON API Web Services

Q: Is there any HTTP JSON API service to get live scores for [your event here] e.g. the World Cup 2018 in Russia, the English Premier League 2018/19, the Euro 2020, etc.?

A: football.db does NOT OFFER ANY REAL-TIME LIVE football results / scores services.

However, you can run your own HTTP JSON API web service. See the sport.db.starter kits to get started, for example.

Q: What’s the update frequency of the datasets?

A: It’s an open source (public domain) volunteer effort. Datasets get updated when they get updated, that is, there’s no schedule and no guarantee. If you need updates today you have at least two options:

Option 1) Contribute your updates to the datasets.

Option 2) Clone the datasets and update your own private or public copies yourself.

Contribute / Update Match Scores, Schedules, Leagues

Q: How can I contribute / update match scores, schedules, leagues, etc.?

A: Your contributions are welcome. It works like a wiki, that is, the datasets are plain text documents that anybody can update (if you’re an openfootball team member - you can update it directly in your browser or push your commits; otherwise you may use a pull request).

For example, to add the result for the Brazil vs Croatia match:

Thu Jun/12 17:00   Brazil  vs  Croatia

change the line to:

Thu Jun/12 17:00   Brazil  3-1 (1-1)  Croatia

Bonus: Let’s add the goal getters too. Example:

Thu Jun/12 17:00   Brazil  3-1 (1-1)  Croatia
                     [Neymar 29', 71' (pen.) Oscar 90+1';  Marcelo 11' (o.g.)]

That’s it.

League Standings / Stats

Q: How can I add league standings / tables (e.g. number of matches played, won-drawn-lost, goals scored, etc.)?

A: That’s the big plus using structured data. You can (auto-)calculate league standings using SQL queries and updates. Another big plus: Your standings will be always up-to-date (just recalculate - if out-of-date).

Note, you can use the built-in sportdb standing calculations. Still early and rough. For auto-calculating all league standings use, for example, in your build script:

EventStanding.recalc!   # and for all groups

You can see the calc “engine” code here [1]. The “engine” calculates:

Standing tables in the sportdb schema include:

For example, using the world cup datasets you can (auto-)calculate the all time standings:

 1  Brazil (BRA)                 97   67  15  15  210:88   216  19
 2  Germany (GER)                99   60  19  20  206:117  199  17
 3  Italy (ITA)                  80   44  21  15  126:74   153  17
 4  Argentina (ARG)              70   37  13  20  123:80   124  15
 5  England (ENG)                59   26  19  14   77:52    97  13
 6  Spain (ESP)                  56   28  12  16   88:59    96  13
 7  France (FRA)                 54   25  11  18   96:68    86  13
 8  Netherlands (NED)            43   22  10  11   71:44    76   9
 9  Uruguay (URU)                47   18  12  17   76:65    66  11
10  Sweden (SWE)                 46   16  13  17   74:69    61  11

Text Formtas (Match Schedule / Player / Squads Mini Languages)

Q: What kind of text format are you using? Why not use CSV, JSON, or [your data format here]?

A: Most football.db documents use “standard” plain text formats such as comma-separated values or key-value pairs with some exceptions.

The match schedules use a mini structured data language. Example:

Group A    |  Brazil    Croatia       Mexico     Cameroon
Group B    |  Spain     Netherlands   Chile      Australia

Matchday 1 |  Thu Jun/12
Matchday 2 |  Fri Jun/13

Group A:

(1) Thu Jun/12 17:00   Brazil  3-1 (1-1)  Croatia    @ Arena de São Paulo, São Paulo
                        [Neymar 29', 71' (pen.) Oscar 90+1'; Marcelo 11' (o.g.)]


(64) Sun Jul/13 16:00  Germany  1-0 a.e.t. (0-0, 0-0)  Argentina  @ Estádio do Maracanã, Rio de Janeiro
                        [Mario Götze 113']

The player documents use a mini structured data language. Example:

Júlio César|Júlio César SOARES DE ESPINDOLA,     3 Sep 1979, 186
T. Silva|Thiago SILVA|Thiago EMILIANO DA SILVA, 22 Sep 1984, 183
David Luiz|David Luiz MOREIRA MARINHO,          22 Apr 1987, 189
Marcelo|Marcelo VIEIRA DA SILVA JUNIOR,         12 May 1988, 174
Dante|Dante BONFIM COSTA SANTOS,                18 Oct 1983, 188

The squads / lineups documents use a mini structured data language. Example:

(12)  GK  Júlio César           #  79, Toronto (CAN)
 (3)  DF  Thiago Silva          #  45, Paris Saint-Germain (FRA)
 (4)  DF  David Luiz            #  35, Chelsea (ENG)
 (6)  DF  Marcelo               #  30, Real Madrid (ESP)
(13)  DF  Dante                 #  12, Bayern Munich (GER)

Bonus Exercise: Try to write by hand the schedule for the English Premier League - week-by-week - 380 matches all together, for example? Are you enjoying writing the match schedule in JSON? in CSV? in XML? in [your data format here]? Why not post an example (e.g. a link to a gist or to your document) to the forum / mailing list for comparison?

Now retry the exercise using the new mini language designed for making hand-crafting schedules as easy as possible. Any difference?

Q: Why? Why? Why?

A: The dataset sources are plain old text documents designed to be easy-to-read and easy-to-write. The idea is to make it work like a wiki, that is, just plain old text documents anyone can update.

Why like a wiki?

Question - What’s the best source for open “unstructured” football information in the real world in 2018? Of course, the Wikipedia! See, for example, the World Cup 2018 page, the World Cup 2018 squads page, or the World Cup 2018 Qualifiers page.

Thus, the idea is - why not build on what works and build a wiki for “structured” data e.g.

Q: What about Wikidata - Wikipedia’s Data Project?

A: Wikidata is a great initiative. Wikidata like the football.db uses “license-free” data, that is, data dedicated to the public domain.

Thus, an idea (and goal) is to work on syncying the data (from Wikidata to football.db and from football.db to Wikidata). Still very early. If you’re interested in making it happen or if you have any ideas, suggestions or insights, say hello on the forum / mailing list.

Export Formats (JSON, CSV, SQL)

Q: How can I get datasets in JSON, CSV, SQL or [your data format here]?

A: Get a copy of a pre-built database e.g. football.db, worldcup.db etc. It’s a single-file SQLite database (working anywhere, that is, Windows, Mac, Linux, etc.).

Option 1) No coding required. Use your SQLite tool of choice to export to CSV, JSON, SQL or [your data format here].

Option 2) Write your own (little) script (in Ruby, Python, etc.) that exports to CSV, JSON or [your data format here]. - Bonus: Share your scripts with the world.

Q: How can I get datasets in JSON, CSV or [your data format here] using [your database here] e.g. PostgreSQL, MySQL, etc.?

A: Load the datasets into your (SQL) database of choice e.g. PostgreSQL, MySQL, etc. and

Option 1) use your database tool of choice to export to CSV, JSON, SQL or [your data format here] etc. or

Option 2) use your language of choice and wipe up some code to export to CSV, JSON or [your data format here] etc. - Bonus: Share your code with the world.

Apps, Apps, Apps

Q: Any real world apps using this?

A: There’s no API key, there’s no registration, there’s no license for the datasets. You’re free to use whatever you need - no questions asked, no rights reserved. If you’re using the football.db datasets in your app, you’re welcome to tell the world (on the mailing list/forum) and you get listed here:

Questions? Comments?

Send them along to the forum. Thanks!

Edit Me! The football.db documentation site is a public GitHub repo. Please help by forking the repo and adding to it.