Stats FC Dugout

The complete documentation of our JSON API

Rate Limits

Rate limits are determined globally for the entire API. Each API key is limited to 250 or 1,500 requests per day, depending on the active subscription.

If you hit the rate limit, you will receive an HTTP 429 error.

Authentication

You authenticate to the Stats FC API via API key.

Include the API key from your account page as a X-StatsFC-Key header. For example:

curl -H "X-StatsFC-Key: {api_key}" https://dugout.statsfc.com/api/v1/…

To try the API before you sign up use the API key apitest. More in the FAQs.

Competitions

GET /competitions
Response
Status: 200 OK
{
    "data": [
        {
            "id": 2,
            "name": "Premier League",
            "key": "EPL",
            "region": "England",
            "rounds": [
                {
                    "id": 435,
                    "name": "Premier League",
                    "start": "2015-08-07",
                    "end": "2016-05-14"
                }
            ]
        }
    ]
}
Optional Parameters
Name Type Description
region string The region of the competition

Seasons

GET /seasons
Response
Status: 200 OK
{
    "data": [
        {
            "id": 10,
            "name": "2015\/2016",
            "start": "2015-06-30",
            "end": "2016-06-30"
        }
    ]
}

States

GET /states
Response
Status: 200 OK
{
    "data": [
        {
            "id": 2,
            "key": "FX",
            "name": "Fixture"
        }
    ]
}

Fixtures

GET /fixtures
Response
Status: 200 OK
{
    "data": [
        {
            "id": 21159,
            "timestamp": "2015-08-08T14:00:00+0000",
            "competition": {
                "id": 2,
                "name": "Premier League",
                "key": "EPL",
                "region": "England"
            },
            "round": {
                "id": 435,
                "name": "Premier League",
                "start": "2015-08-07",
                "end": "2016-05-14"
            },
            "teams": {
                "home": {
                    "id": 8,
                    "name": "Stoke City",
                    "shortName": "Stoke"
                },
                "away": {
                    "id": 1,
                    "name": "Liverpool",
                    "shortName": "Liverpool"
                }
            },
            "players": {
                "home": [],
                "away": []
            },
            "score": null,
            "currentState": {
                "id": 4,
                "key": "HT",
                "name": "Half-Time"
            },
            "venue": {
                "id": 665,
                "name": "Britannia Stadium",
                "capacity": 27740
            },
            "events": [
                "cards": [],
                "goals": [],
                "states": [],
                "substitutions": []
            ]
        }
    ]
}
Optional Parameters
Name Type Description
season string The season the fixtures are in
season_id integer The ID of the season the fixtures are in
competition string The name of the competition the fixtures are in
competition_id integer The ID of the competition the fixtures are in
competition_key string The key of the competition the fixtures are in
team string The name of the home or away team the fixtures are in
team_id integer The ID of the home or away team the fixtures are in
from string The earliest date to return fixtures from. This is a date in ISO 8601 format: YYYY-MM-DD
to string The latest date to return fixtures to. This is a date in ISO 8601 format: YYYY-MM-DD

Results

GET /results
Response
Status: 200 OK
{
    "data": [
        {
            "id": 69540,
            "timestamp": "2016-08-14T15:00:00+0000",
            "competition": {
                "id": 2,
                "name": "Premier League",
                "key": "EPL",
                "region": "England"
            },
            "round": {
                "id": 1044,
                "name": "Premier League",
                "start": null,
                "end": null
            },
            "teams": {
                "home": {
                    "id": 18,
                    "name": "Arsenal",
                    "shortName": "Arsenal"
                },
                "away": {
                    "id": 1,
                    "name": "Liverpool",
                    "shortName": "Liverpool"
                }
            },
            "players": {
                "home": [
                    {
                        "id": 16976,
                        "number": 33,
                        "position": "GK",
                        "role": "starting",
                        "name": "Petr \u010cech",
                        "shortName": "\u010cech"
                    }
                ],
                "away": [
                    {
                        "id": 17018,
                        "number": 22,
                        "position": "GK",
                        "role": "starting",
                        "name": "Simon Mignolet",
                        "shortName": "Mignolet"
                    }
                ]
            },
            "score": [
                3,
                4
            ],
            "currentState": {
                "id": 9,
                "key": "FT",
                "name": "Full-Time"
            },
            "venue": {
                "id": 47,
                "name": "Emirates Stadium",
                "capacity": 60338
            },
            "events": {
                "cards": [
                    {
                        "id": 41059,
                        "timestamp": "2016-08-14T15:26:15+0000",
                        "matchTime": "25'",
                        "type": "card",
                        "subType": "first-yellow",
                        "team": {
                            "id": 1,
                            "name": "Liverpool",
                            "shortName": "Liverpool"
                        },
                        "player": {
                            "id": "17235",
                            "name": "Adam Lallana",
                            "shortName": "Lallana",
                            "position": "MF"
                        }
                    }
                ],
                "goals": [
                    {
                        "id": 160439,
                        "timestamp": "2016-08-14T15:30:26+0000",
                        "matchTime": "29'",
                        "type": "goal",
                        "subType": null,
                        "team": {
                            "id": 18,
                            "name": "Arsenal",
                            "shortName": "Arsenal"
                        },
                        "player": {
                            "id": "17476",
                            "name": "Theo Walcott",
                            "shortName": "Walcott",
                            "position": "FW"
                        },
                        "assist": {
                            "id": "34666",
                            "name": "Alex Iwobi",
                            "shortName": "Iwobi",
                            "position": "FW"
                        }
                    }
                ],
                "states": [
                    {
                        "id": 213309,
                        "timestamp": "2016-08-14T15:01:41+0000",
                        "matchTime": "1'",
                        "type": "state",
                        "state": {
                            "id": 1,
                            "key": "1H",
                            "name": "1st Half"
                        }
                    }
                ],
                "substitutions": [
                    {
                        "id": 57247,
                        "timestamp": "2016-08-14T16:17:18+0000",
                        "matchTime": "60'",
                        "type": "substitution",
                        "subType": null,
                        "team": {
                            "id": 18,
                            "name": "Arsenal",
                            "shortName": "Arsenal"
                        },
                        "playerOff": {
                            "id": "17478",
                            "name": "Aaron Ramsey",
                            "shortName": "Ramsey",
                            "position": "MF"
                        },
                        "playerOn": {
                            "id": "17480",
                            "name": "Santi Cazorla",
                            "shortName": "Cazorla",
                            "position": "MF"
                        }
                    }
                ]
            }
        }
    ]
}
Optional Parameters
Name Type Description
season string The season the results are in
season_id integer The ID of the season the results are in
competition string The name of the competition the results are in
competition_id integer The ID of the competition the results are in
competition_key string The key of the competition the results are in
team string The name of the home or away team the results are in
team_id integer The ID of the home or away team the results are in
from string The earliest date to return results from. This is a date in ISO 8601 format: YYYY-MM-DD
to string The latest date to return results to. This is a date in ISO 8601 format: YYYY-MM-DD
Possible Values
Name Type Values Description
players home position
players away position
events player position
string
  • GK
  • DF
  • MF
  • FW
The player's general position
players home role
players away role
string
  • starting
  • sub
The player's role at the start of the match
events type string
  • goal
  • card
  • substitution
  • state
  • penalties (indicating the start of a penalty shootout)
  • penalty (indicating an individual penalty in a shootout)
The primary type of the event
events subType string
  • penalty (relating to goal type)
  • own-goal (relating to goal type)
  • first-yellow (relating to card type)
  • second-yellow (relating to card type)
  • red (relating to card type)
The secondary type of the event

Standings

GET /standings
Response
Status: 200 OK
{
    "data": [
        {
            "competition": {
                "id": 2,
                "name": "Premier League",
                "key": "EPL",
                "region": "England"
            },
            "round": {
                "id": 107,
                "name": "Premier League",
                "start": "2014-08-15",
                "end": null
            },
            "team": {
                "id": 7,
                "name": "Chelsea",
                "shortName": "Chelsea"
            },
            "position": 1,
            "played": 38,
            "wins": 26,
            "draws": 9,
            "losses": 3,
            "for": 73,
            "against": 32,
            "difference": 41,
            "points": 87,
            "info": "top1",
            "notes": null
        }
    ]
}
Optional Parameters
Name Type Description
season string The season for the standings
competition string The name of the competition for the standings
competition_id integer The ID of the competition for the standings
competition_key string The key of the competition for the standings
Possible Values
Name Type Values Description
info string
  • top1
  • top2
  • top3
  • top4
  • bottom1
Meta data about the tier of the league position

Top Scorers

GET /top-scorers
Response
Status: 200 OK
{
    "data": [
        {
            "id": 17183,
            "player": {
                "name": "Sergio Ag\u00c3\u00bcero",
                "shortName": "Ag\u00c3\u00bcero"
            },
            "team": {
                "name": "Manchester City",
                "shortName": "Man City"
            },
            "goals": 26
        }
    ]
}
Optional Parameters
Name Type Description
season string The season the top scorers are from
competition string The name of the competition the top scorers are from
competition_id integer The ID of the competition the top scorers are from
competition_key string The key of the competition the top scorers are from
team string The name of the home or away team the top scorers are from
team_id integer The ID of the home or away team the top scorers are from

At least one of the competition or team parameters is required.

Squads

GET /squads
Response
Status: 200 OK
{
    "data": [
        {
            "team": {
                "id": 18,
                "name": "Arsenal",
                "shortName": "Arsenal"
            },
            "players": [
                {
                    "id": "17478",
                    "name": "Aaron Ramsey",
                    "shortName": "Ramsey",
                    "position": "MF"
                }
            ]
        }
    ]
}
Optional Parameters
Name Type Description
season string The season the results are in
competition string The name of the competition the results are in
competition_id integer The ID of the competition the results are in
competition_key string The key of the competition the results are in
team string The name of the home or away team the results are in
team_id integer The ID of the home or away team the results are in
Possible Values
Name Type Values Description
players position string
  • GK
  • DF
  • MF
  • FW
The player's general position

Errors

Responses
Status: 401 Unauthorized
{
    "error": {
        "message": "API key not provided",
        "statusCode": 401
    }
}
Status: 401 Unauthorized
{
    "error": {
        "message": "API key not found",
        "statusCode": 401
    }
}
Status: 401 Unauthorized
{
    "error": {
        "message": "IP address does not match",
        "statusCode": 401
    }
}
Status: 401 Unauthorized
{
    "error": {
        "message": "The chosen competition is not in your API subscription",
        "statusCode": 401
    }
}
Status: 401 Unauthorized
{
    "error": {
        "message": "You must filter by competition or team",
        "statusCode": 401
    }
}
Status: 429 Too Many Requests
{
    "error": {
        "message": "Rate limit exceeded",
        "statusCode": 429
    }
}
Status: 503 Service Unavailable
{
    "error": {
        "message": "Down for maintenance. We'll be right back",
        "statusCode": 503
    }
}

FAQs

We support the following competitions, grouped by region:

  • World
    • FIFA Club World Cup
  • Europe
    • Champions League
    • Champions League Qualification
    • Europa League
    • UEFA Super Cup
  • England
    • Premier League
    • Championship
    • League One
    • League Two
    • FA Cup
    • League Cup
    • Football League Trophy
    • Community Shield
  • Spain
    • La Liga
    • Copa del Rey
    • Supercopa de España
  • Germany
    • Bundesliga
    • 2. Bundesliga
    • DFB Pokal
    • DFL Supercup
  • Italy
    • Serie A
    • Coppa Italia
    • Supercoppa Italiana
  • France
    • Ligue 1
    • Coupe de France
    • Coupe de la Ligue
    • Trophée des Champions
  • Scotland
    • Scottish Premiership
    • Scottish Cup
    • Scottish League Cup

Of course! Use our API test key: apitest.

This will give you access to test all the endpoints, but is restricted to the FA Community Shield competition. (We won't just give all of our data away for free!)

Competition Coverage

Region Competition Tables Goals Assists Cards Subs Lineups Entry
World FIFA Club World Cup N/A December
Europe Champions League September
Champions League Qual. N/A July
Europa League September
UEFA Super Cup N/A August
England Premier League August
Championship August
League One August
League Two August
FA Cup N/A 4th Round Qual.
League Cup N/A 1st Round
Football League Trophy 1st Round
Community Shield N/A Final
Spain La Liga August
Copa del Rey N/A 4th Round
Supercopa de España N/A Final
Germany Bundesliga August
2. Bundesliga August
DFB Pokal N/A 3rd Round
DFL Supercup N/A Final
Italy Serie A August
Coppa Italia N/A 4th Round
Supercoppa Italiana N/A Final
France Ligue 1 August
Coupe de France N/A 3rd Round
Coupe de la Ligue N/A 3rd Round
Trophée des Champions N/A Final
Scotland Scottish Premiership August
Scottish Cup N/A 3rd Round
Scottish League Cup 1st Round