openfootball / worldcup.json

Free open public domain football data for the world cups in JSON incl. Qatar 2022, Russia 2018 and more - No API key required ;-)

worldcup.json

Free open public domain football data for the world cups in the JSON (JavaScript Object Notation) data interchange format incl. Qatar 2022, Russia 2018 and more - No API key required ;-).

Example - World Cup in Russia 2018 Match Schedule (Fixtures and Results) - 2018/worldcup.json:

{
  "name": "World Cup 2018",
  "rounds": [
    {
      "name": "Matchday 1",
      "matches": [
        {
          "num": 1,
          "date": "2018-06-14",
          "time": "18:00",
          "team1": { "name": "Russia",       "code": "RUS" },
          "team2": { "name": "Saudi Arabia", "code": "KSA" },
          "score1":  5,
          "score2":  0,
          "score1i": 2,
          "score2i": 0,
          "goals1": [
            { "name": "Gazinsky",   "minute": 12,              "score1": 1, "score2": 0 },
            { "name": "Cheryshev",  "minute": 43,              "score1": 2, "score2": 0 },
            { "name": "Dzyuba",     "minute": 71,              "score1": 3, "score2": 0 },
            { "name": "Cheryshev",  "minute": 90, "offset": 1, "score1": 4, "score2": 0 },
            { "name": "Golovin",    "minute": 90, "offset": 4, "score1": 5, "score2": 0 }
          ],
          "goals2": [],
          "group": "Group A",
          "stadium": { "key": "luzhniki", "name": "Luzhniki Stadium" },
          "city": "Moscow",
          "timezone": "UTC+3"
        }
      ]
    },
    {
      "name": "Matchday 2",
      "matches": [
        {
          "num": 2,
          "date": "2018-06-15",
          "time": "17:00",
          "team1": { "name": "Egypt",   "code": "EGY" },
          "team2": { "name": "Uruguay", "code": "URU" },
          "score1":  0,
          "score2":  1,
          "score1i": 0,
          "score2i": 0,
          "goals1": [],
          "goals2": [
            { "name": "Giménez",  "minute": 89,  "score1": 0, "score2": 1 }
          ],
          "group": "Group A",
          "stadium": { "key": "ekaterinburg", "name": "Ekaterinburg Arena" },
          "city": "Ekaterinburg",
          "timezone": "UTC+5"
        },
        ...
      ],
    },
  ],
}

How to Use the Public JSON HTTP API (Micro) Web Service - No API Key Required ;-)

Use the "raw" links served by GitHub (otherwise you get the complete "formatted" GitHub web page). Example:

$ curl https://raw.githubusercontent.com/openfootball/worldcup.json/master/2018/worldcup.json

Updates / Contributions Welcome - Please Update the Source Text Files

Note: The JSON files get (auto-)generated using the football.db datasets, thus, please do NOT edit the JSON files but the source text files in the world cup (and friends) repos e.g.:

• World Cups in /worldcup
• National Teams in /national-teams
• Stadiums in /stadiums
• and so on

Note: For the World Cup 2022 please update the source text file /worldcup/2022--qatar/cup.txt for the group stage and /worldcup/2022--qatar/cup_finals.txt for the knockout (quarter-finals, semi-finals, etc.) stage.

Contributions Welcome - Add Your Leagues and Tournaments!

Any leagues or tournaments missing? Contributions welcome! For starting your own repo from scratch see the League Quick Starter Kit.

License

The worldcup.json schema, data and scripts are dedicated to the public domain. Use it as you please with no restrictions whatsoever.

Projects in the Real-World Using worldcup.json

World Cup 2018

Yes, you're more than welcome to send a pull request (PR) with your project!

• https://github.com/sportdb/footty -- command line tool in ruby; shows todays' matches or yesterdays' or tomorrows' or all past or all upcoming

• https://github.com/geeknat/heyrussia -- command line tool in go; shows matches, stadiums, groups, standings, etc.

Feel free to add your project here!

Questions? Comments?

Send them along to the Open Sports & Friends Forum/Mailing List. Thanks!

worldcup.json's Issues

Question: Updates?

@geraldb Will the scores be updated regularly during the cup?

Change to Unix timestamp.

This way, you don't have to deal with time zones or manually editing dates/times.

What does score1i mean?

score1 is obvious, but what is score1i?

Repeated match dates

Have you considered moving match date one level up to the match day level? All the matches on the same match day have the same dates. That may remove some duplicate dates.

Latest match days missing

Matches for England v. Panama, Senegal v. Japan, Colombia v. Poland, Russia v. Uruguay, Egypt v. Saudi Arabi, Portugal v. Iran, and Spain v. Morocco are missing.

For record, those scores are:
England 6 - 1 Panama
Senegal 2 - 2 Japan
Colombia 3 - 0 Poland
Russia 1 - 3 Uruguay
Egypt 1 - 2 Saudi Arabi
Portugal 1 - 1 Iran
Spain 2 - 2 Morocco

Position for teams on same points do not reflect FIFA group results

The dataset currently has Spain as pos: 2 and Portugal as pos: 3 in Group B.

Looking at the official FIFA site (https://www.fifa.com/worldcup/groups/) and other organisations such as BBC, ESPN, they all seem to have Portugal as 2 and Spain as 3.

It would be useful to reflect the public facing version of the group results if possible.

As far as I can tell, the actual rules for tiebreakers seem to be the following:

• Goal difference in all group matches
• Goals scored in all group matches
• Head-to-head points between the teams concerned
• Goal difference in the group matches between the teams concerned
• Goals scored in group matches between the teams concerned
• Points obtained in fair play conduct *(yellow cards = -1, indirect red card = -3, direct red card = -4, yellow card and direct red = -5)
• Drawing of lots by the FIFA Organising Committee

Latest Match Results / Missing - Please, Update

FYI: I am just a random nobody - there's no budget and no time - what do you expect what I can do for you today?

You're more than welcome to help out and contribute. A good first start would be helping with match results / updates. To quote from the README:

Updates / Contributions Welcome - Please Update the Source Text Files

Note: The JSON files get (auto-)generated using the football.db datasets, thus, please do NOT
edit the JSON files but the source text files in the world cup (and friends) repos e.g.:

• World Cups in /world-cup
• National Teams in /national-teams
• Stadiums in /stadiums
• and so on

Note: For the World Cup 2018 please update the source text file
/world-cup/2018--russia/cup.txt for the group stage and
/world-cup/2018--russia/cup_finals.txt for the knockout (quarter-finals, semi-finals, etc.) stage.

Please update the world-cup Scores!!!

My company is relying on it for our sweepstakes!!

I'm confused

You have closed several issues asking that are asking for updates, but your read me explicitly states not to modify the JSONs.

update Real-Time

Hi.. How often do you update /worldcup.json?

If I Need a Real-Time
I need to do