# football.json is a public domain fixture feed you can curl

> The openfootball football.json repository publishes match fixtures and results as JSON for a long list of leagues, regenerated once a day from the Football.TXT sources. The data is in the public domain with no restrictions, and the one sharp edge is that the JSON is generated, so edits belong in the upstream country repositories, not here.

**openfootball/football.json** — Free open public domain football data in JSON incl. English Premier League, Bundesliga, Primera División, Serie A and more - No API key required ;-)

- Repository: https://github.com/openfootball/football.json
- Stars: 1,047 · Forks: 220
- Language: Unknown
- License: CC0-1.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/openfootball-football-json

## A daily job that regenerates the season from upstream

football.json is a set of free, open, public domain football datasets, meaning match fixtures and results, in the JSON data interchange format. The repository description leads with the useful part for an engineer: no API key required.

The update mechanism is a GitHub action. The datasets for the latest season, which the readme identifies as 2026 and 2026/27, get auto-updated once a day at 5 o'clock UTC from the upstream Football.TXT datasets, and the action log is linked so you can see the runs. There is also a package.json at the root with the name football.json, version 1.0.0, the author Gerald Bauer, and the licence field set to Public Domain.

The league coverage is the reason most people come here. It covers the English Premier League plus the Championship, League One and League Two, the Deutsche Bundesliga with the 2. Bundesliga and 3. Liga, the Spanish Primera División and Segunda División, the Italian Serie A and Serie B, the French Ligue 1 and Ligue 2, and the description says and much more.

The repository layout is seasons, and the directories are named for the season. It runs from 2010-11 through 2025-26 and 2026-27, and it also has calendar year directories, 2019, 2020, 2025 and 2026, which is where tournaments that are not played on a season calendar end up.

The audience is developers building anything that shows fixtures: a fan site, a fantasy football helper, a match prediction experiment, a test fixture for a data pipeline. The data is small, the licence is permissive, and there is no service to depend on.

## The JSON shape is a round, a date, two teams and a score

The example in the readme is a Premier League 2015/16 match schedule, and the file is a single object with a name and a matches array. Each match has a round, a date, team1, team2, and a score object whose ft key holds the full time goals as a two element array.

```json
{
  "name": "Premier League 2015/16",
  "matches": [
        {
          "round": "Matchday 1",
          "date":  "2015-08-08",
          "team1": "Manchester United",
          "team2": "Tottenham Hotspur",
          "score": { "ft": [1, 0] }
        },
        ...
  ]
}
```

Two things about this shape are worth noticing before you write a parser.

First, the field names are the short forms, team1 and team2 rather than home and away, and the round is a human readable string such as Matchday 1 rather than a number. This is a consequence of the data being generated from Football.TXT, a plain text format where each line is a match, and the generator preserves the vocabulary of the source rather than normalising it.

Second, the score is nested under ft for full time, which implies the structure has room for other score components such as half time or penalties, even where a given match only carries the full time result. The example also shows a date and a score together in the same object, so a fixture that has not been played simply has no score key, or has a null one, and a consumer that assumes score.ft[0] always exists will break on the first future fixture.

The league file name encodes the league, for example en.1.json for the Premier League, with the numbering scheme following the Football.TXT convention where the first division of a country is 1.

## Fetching it is a curl, and the raw URL matters

The readme explains how to use the public JSON API service with no API key, and the instruction is to use the raw links served by GitHub, otherwise you get the complete formatted GitHub page.

That is a small detail that catches people the first time. A URL pointing at a github.com blob path returns an HTML page; the JSON is at the raw.githubusercontent.com path.

```bash
$ curl https://raw.githubusercontent.com/openfootball/football.json/master/2015-16/en.1.json
```

There is no host to run, no token to manage, no rate limit to read about and no schema endpoint. The repository is the API. For a project that wants a dependency free way to read fixtures, that is a genuine advantage over a hosted sports data provider, where the free tier comes with keys, quotas and a terms of service that says how you may use the data.

The cost of that choice is equally clear. There is no availability guarantee beyond GitHub, no versioning scheme, and the content is whatever the upstream sources happen to say. The caching behaviour you get is GitHub's, and if you fetch on every page render you are making a network call to a file host on the hot path of your site, which is a decision you should make deliberately rather than by copying the curl line.

The readme also points at the source side of the project, the Football.TXT pages per country, which are the human editable form of the same data and are published through the openfootball.github.io site.

## Editing the JSON here is a mistake, and the readme says so twice

The contribution rule is the single most important operational fact about this repository, and it is stated in bold in the readme.

The football.json files are auto-generated using the datasets in the Football.TXT format, so the instruction is to not edit the auto-generated JSON files here but the Football.TXT sources upstream in the country repositories. Those are /england for the Premier League, the Championship, League One and League Two, /deutschland for the Bundesliga family, /espana for La Liga and Segunda, /italy for Serie A and Serie B, and /europe for French Ligue 1 and Ligue 2, with each having its own page index on the openfootball.github.io site.

And then the consequence is spelled out: if you only edit or patch the auto-generated JSON files here without updating the sources upstream, your changes will get lost or overwritten with the next update.

That is a two-step workflow, and it is the one thing to internalise before contributing. A fix in this repository has to be made in a different repository, in a plain text file, and it only shows up here after the daily generation job runs. A pull request that patches the JSON directly will look like a helpful contribution and will silently disappear, which is why the readme repeats the point rather than leaving it in a footnote.

There is also a starter kit for people who want to add a league that is missing. The League Quick Starter Kit is the documented path for starting a country or tournament repository from scratch, and contributions of new leagues are explicitly welcome.

## The generation step is a command line tool, not a service

If you want to regenerate the datasets yourself, the readme points at the build scripts in the yorobot/football.json repository, or tells you to use your own, and then offers a quicker alternative in the fbtxt2json command line tool from the sportdb/footty project.

Converting one Football.TXT file looks like this:

```bash
$ fbtxt2json england/2026-27/1-premierleague.txt -o en.1.json
```

And converting a whole country repository at once runs the tool over the directory and writes the output into a site directory:

```bash
$ fbtxt2json . -o ./_site   # run inside /england; output json datasets to _site directory
```

So the pipeline is text to JSON with one command, and there is nothing in between. That is a genuinely useful property, because it means the format is reproducible and the transformation is inspectable, unlike a hosted provider's opaque endpoint.

The readme also collects third party scripts that use the data, which is a good way to see the shape used in anger. Enrique Lopez Magallon wrote a Python robot that reads the .txt files and generates an emulated version of the JSONs. Nurgazy Nazhimidinov built a tool that compares the last season and this season head to head results of a Premier League team. And Rodolfo Melogli uses the Football.TXT fixture data for Serie A and the Premier League to power a set of free fantasy football tools, with fixture difficulty ratings and next five run-in rankings for Fantacalcio and Fantasy Premier League.

The third of those is the most instructive, because it is the use case the data shape was designed for: something that needs a difficulty rating per fixture, which means reading the season's results and computing from them.

## The upstream refresh is manual, and that is the weak point

The FAQ at the top of the readme answers the update question, and the answer has two halves.

The first half is the good one. The football.json datasets of the latest season get auto-updated once a day at 5 o'clock UTC from the upstream Football.TXT datasets, via a GitHub action.

The second half is the caveat. For the upstream Football.TXT datasets themselves, there is no automatic daily update. That is the honest limit of the project: the generation step is automated, the collection step is not, and the collection step is the one that decides whether a match result is ever correct.

In practice that means somebody has to notice a match result changed, or was postponed, or that a new fixture was published, and edit the right.txt file. The readme frames that as an invitation, with a section titled Updates / Contributions Welcome, and points at the country repositories and at the DIY generation instructions for anyone who wants to help.

So the reliability profile of a given competition's data depends on how actively its community maintains the source file. A league with a committed maintainer will be current within a day. A league nobody watches will drift, and the drift will not be announced.

There is a second, smaller gap in the same area. The football.json repository carries season directories going back to 2010-11, which means the historical seasons are static snapshots. A correction for a result that was originally misreported still has to come through the Football.TXT sources upstream, the same as for the current season.

## Public domain, and a reminder about what the data is not

The licensing is the strongest feature here and it is stated without hedging. The football.json schema, data and scripts are dedicated to the public domain, to be used as you please with no restrictions whatsoever, and the licence in the repository metadata is given as CC0-1.0 and the package field as Public Domain.

For a commercial project that is a cleaner position than most data sources offer. There is no attribution requirement, no client redistribution restriction, no question about whether a derived dataset inherits terms, and no clause about using the data to build a competing service. For a sports app, a betting model, a fan site or a research dataset, that removes a legal review step that usually takes longer than the integration.

The repository also carries a help and support area at the openfootball help repository, and the readme invites questions and comments.

What the data is not is worth stating plainly. It covers fixtures and results, and it covers the leagues listed plus whatever else the community has added. It has no live scores, no odds, no player statistics, no venue or weather data, and no event stream. Anything that needs the state of a match as it is being played is looking at a different project entirely.

And the fact that the files are generated and the upstream is hand maintained means the data is a community effort with a community's error rate, not a vendor feed with a quality guarantee. For a hobby project, a visualisation, or a test fixture, that is entirely sufficient. For anything where a wrong result has consequences, you should know that the correction path runs through a text file in another repository and a daily GitHub action.

## Conclusion

football.json is worth adopting for a fixture display, a fantasy football tool, a sports blog or a demo, because the licence puts it in the public domain with no restrictions and the shape is small enough to parse in an afternoon. It is the wrong choice if you need a data provider with a service level agreement, because the upstream refresh depends on human contributions and the daily job only regenerates what the sources already contain. Before you depend on it, fetch a season file and check the coverage and the date range for the leagues you need, and note that the repository was pushed to on 2026-09-22 with no tagged releases, so the commit history is the version history.

## FAQ

### How often are the football.json datasets updated?

The datasets of the latest season, 2026 and 2026/27, get auto-updated once a day at 5 o'clock UTC from the upstream Football.TXT datasets through a GitHub action, and the action log is linked in the readme. For the upstream Football.TXT datasets themselves there is no automatic daily update, which is where human contributions come in.

### How do I fetch a football.json file without an API key?

Use the raw links served by GitHub, for example curl https://raw.githubusercontent.com/openfootball/football.json/master/2015-16/en.1.json. The readme warns that using the normal GitHub URL gives you the formatted page rather than the JSON.

### Why should I not edit the JSON files in the football.json repository?

They are auto-generated from the Football.TXT sources, so a direct patch will be lost or overwritten with the next update. The readme asks you to edit the .txt sources upstream in the country repositories such as /england, /deutschland, /espana, /italy and /europe instead.

### Which leagues does football.json cover?

The English Premier League with the Championship, League One and League Two, the Deutsche Bundesliga with the 2. Bundesliga and 3. Liga, the Spanish Primera División and Segunda División, the Italian Serie A and Serie B, the French Ligue 1 and Ligue 2, and more, with the repository holding season directories from 2010-11 to 2026-27.

### Can I generate the JSON myself from the Football.TXT sources?

Yes. The readme points at the build scripts in the yorobot/football.json repository, and the fbtxt2json command line tool converts a Football.TXT file with fbtxt2json england/2026-27/1-premierleague.txt -o en.1.json, or a whole country repository with fbtxt2json . -o ./_site run inside /england.

## Sources

- [Issues](https://github.com/openfootball/football.json/issues)
- [License: CC0-1.0](https://github.com/openfootball/football.json/blob/master/LICENSE)
- [openfootball/football.json on GitHub](https://github.com/openfootball/football.json)
- [README](https://github.com/openfootball/football.json/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openfootball-football-json