# API-AFL

> Follow Australian rules football with API-AFL: AFL Premiership games and live scores, quarter by quarter, goals and behinds by player, team and player statistics for a game and a season, the ladder and bookmakers' pre-match odds. Needs an API-SPORTS key; the free plan allows 100 requests a day.

App · Sports · 17 actions. Web page: https://docs.lodol.com/docs/integrations/api-afl

## Actions

### Find players

Find players by name or ID, or list a team's players in a season, each with the ID the statistics actions take.

**Inputs**

- Player ID (`player_id`, text): Optional. Only this player, by ID, such as 682.
- Search (`search`, text): Optional. Only names containing this, at least 3 characters.
- Team (`team_id`, text): Optional. Only this team's players, with a season. Pick one from the list.
- Season (`season`, number): Optional. Only this season, as its year, such as 2024. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.

**Outputs**

- `count` (number): How many came back.
- `players` (list): The players.

**Example output**

```json
{
  "count": 1,
  "players": [
    {
      "id": 682,
      "name": "Lachie Neale"
    }
  ]
}
```

### Find teams

Find the AFL's teams, each with its ID and logo: all of them, or by name, by ID, or those in a season.

**Inputs**

- Team ID (`team_id`, text): Optional. Only this team, by ID, such as 2.
- Search (`search`, text): Optional. Only names containing this, at least 3 characters.
- League (`league_id`, text): Optional. The competition: 1 for the AFL Premiership, API-AFL's only one, which is used when a season is set and this is left empty.
- Season (`season`, number): Optional. Only this season, as its year, such as 2024. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.

**Outputs**

- `count` (number): How many came back.
- `teams` (list): The teams.

**Example output**

```json
{
  "count": 1,
  "teams": [
    {
      "id": 2,
      "logo": "https://media.api-sports.io/afl/teams/2.png",
      "name": "Brisbane Lions"
    }
  ]
}
```

### Get a game

Get one game by ID: its round, venue, status and both sides' goals, behinds and score, live while it is being played.

**Inputs**

- Game ID (`game_id`, text, required): The game's ID, such as 3058. List games returns them.
- Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Australia/Melbourne. UTC when left empty.

**Outputs**

- `attendance` (number): The crowd, when the API has it.
- `date` (text): When it starts, with the time zone's offset (ISO 8601).
- `id` (number): The game's ID.
- `league` (object): The competition and season.
- `round` (text): Regular Season, or Postseason or Post Season for the finals.
- `scores` (object): Both sides' scores.
- `status` (object): Where the game stands.
- `teams` (object): Both sides.
- `time` (text): Its start time, HH:MM, in that time zone.
- `timestamp` (number): When it starts, as a Unix timestamp.
- `timezone` (text): The time zone date and time are given in.
- `venue` (text): Where it is played.
- `week` (number): The round's number, such as 5.

**Example output**

```json
{
  "attendance": null,
  "date": "2024-09-28T04:30:00+00:00",
  "id": 3058,
  "league": {
    "id": 1,
    "season": 2024
  },
  "round": "Postseason",
  "scores": {
    "away": {
      "behinds": 12,
      "goals": 18,
      "psbehinds": 0,
      "psgoals": 0,
      "score": 120
    },
    "home": {
      "behinds": 6,
      "goals": 9,
      "psbehinds": 0,
      "psgoals": 0,
      "score": 60
    }
  },
  "status": {
    "long": "Finished",
    "short": "FT"
  },
  "teams": {
    "away": {
      "id": 2,
      "logo": "https://media.api-sports.io/afl/teams/2.png",
      "name": "Brisbane Lions"
    },
    "home": {
      "id": 14,
      "logo": "https://media.api-sports.io/afl/teams/14.png",
      "name": "Sydney Swans"
    }
  },
  "time": "04:30",
  "timestamp": 1727497800,
  "timezone": "UTC",
  "venue": "Melbourne Cricket Ground",
  "week": 28
}
```

### Get account status

See the connected key's API-AFL plan, when it renews, and how many of today's requests are used and left. It is free: it never counts against the day.

**Inputs**: None.

**Outputs**

- `active` (true/false): True while the subscription is active.
- `daily_limit` (number): Requests allowed a day.
- `plan` (text): The plan, such as Free.
- `requests_remaining` (number): Requests left today; the day starts at midnight UTC.
- `requests_today` (number): Requests used today.
- `subscription_end` (text): When the plan renews or ends.

**Example output**

```json
{
  "active": true,
  "daily_limit": 100,
  "plan": "Free",
  "requests_remaining": 88,
  "requests_today": 12,
  "subscription_end": "2027-10-01T00:00:00+00:00"
}
```

### Get game events

Get every goal and behind of a game, or of every game on a day, with the team, the player, the quarter and the minute.

**Inputs**

- Game ID (`game_id`, text): Optional. The game, by ID, such as 3058. Set this or a date, not both. List games gives game IDs.
- Date (`on_date`, date): Optional. Every game on this day, in the time zone chosen below, instead of one game. The free plan takes only yesterday, today or tomorrow.
- Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Australia/Melbourne. UTC when left empty.

**Outputs**

- `count` (number): How many came back.
- `games` (list): Each game's events.

**Example output**

```json
{
  "count": 1,
  "games": [
    {
      "events": [
        {
          "minute": 2,
          "period": 1,
          "player": {
            "id": 868
          },
          "team": {
            "id": 2
          },
          "type": "behind"
        },
        {
          "minute": 6,
          "period": 1,
          "player": {
            "id": 867
          },
          "team": {
            "id": 2
          },
          "type": "behind"
        }
      ],
      "game_id": 3058
    }
  ]
}
```

### Get game player statistics

Get every player's statistics for a game, or for every game on a day: goals, goal assists, behinds, disposals, kicks, handballs, marks, tackles, hitouts, clearances and free kicks for and against.

**Inputs**

- Game ID (`game_id`, text): Optional. The game, by ID, such as 3058. Set this or a date, not both. List games gives game IDs.
- Date (`on_date`, date): Optional. Every game on this day, in the time zone chosen below, instead of one game. The free plan takes only yesterday, today or tomorrow.
- Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Australia/Melbourne. UTC when left empty.

**Outputs**

- `count` (number): How many came back.
- `games` (list): Each game's player statistics.

**Example output**

```json
{
  "count": 1,
  "games": [
    {
      "game_id": 3058,
      "teams": [
        {
          "players": [
            {
              "behinds": 0,
              "clearances": 0,
              "disposals": 15,
              "free_kicks": {
                "against": 1,
                "for": 0
              },
              "goals": {
                "assists": 0,
                "total": 0
              },
              "handballs": 2,
              "hitouts": 0,
              "kicks": 13,
              "marks": 11,
              "player": {
                "id": 144,
                "number": 35
              },
              "tackles": 4
            }
          ],
          "team": {
            "id": 2
          }
        },
        {
          "players": [
            {
              "behinds": 0,
              "clearances": 2,
              "disposals": 14,
              "free_kicks": {
                "against": 1,
                "for": 0
              },
              "goals": {
                "assists": 0,
                "total": 3
              },
              "handballs": 4,
              "hitouts": 0,
              "kicks": 10,
              "marks": 2,
              "player": {
                "id": 505,
                "number": 26
              },
              "tackles": 6
            }
          ],
          "team": {
            "id": 14
          }
        }
      ]
    }
  ]
}
```

### Get game team statistics

Get each side's statistics for a game, or for every game on a day: disposals, kicks, handballs, free kicks, hitouts, clearances, marks, goals, goal assists, behinds and tackles.

**Inputs**

- Game ID (`game_id`, text): Optional. The game, by ID, such as 3058. Set this or a date, not both. List games gives game IDs.
- Date (`on_date`, date): Optional. Every game on this day, in the time zone chosen below, instead of one game. The free plan takes only yesterday, today or tomorrow.
- Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Australia/Melbourne. UTC when left empty.

**Outputs**

- `count` (number): How many came back.
- `games` (list): Each game's statistics.

**Example output**

```json
{
  "count": 1,
  "games": [
    {
      "game_id": 3058,
      "teams": [
        {
          "statistics": {
            "defence": {
              "tackles": 64
            },
            "disposals": {
              "disposals": 385,
              "free_kicks": 16,
              "handballs": 115,
              "kicks": 270
            },
            "marks": 158,
            "scoring": {
              "assists": 15,
              "behinds": 9,
              "goals": 18
            },
            "stoppages": {
              "clearances": 33,
              "hitouts": 20
            }
          },
          "team": {
            "id": 2
          }
        },
        {
          "statistics": {
            "defence": {
              "tackles": 45
            },
            "disposals": {
              "disposals": 305,
              "free_kicks": 13,
              "handballs": 110,
              "kicks": 195
            },
            "marks": 88,
            "scoring": {
              "assists": 7,
              "behinds": 5,
              "goals": 9
            },
            "stoppages": {
              "clearances": 34,
              "hitouts": 42
            }
          },
          "team": {
            "id": 14
          }
        }
      ]
    }
  ]
}
```

### Get player statistics

Get a player's season: games played, and the total and average a game of goals, goal assists, behinds, disposals, kicks, handballs, marks, tackles, hitouts, clearances and free kicks for and against.

**Inputs**

- Player ID (`player_id`, text, required): The player's ID, such as 682 for Lachie Neale. Find players looks one up.
- Season (`season`, number, required): The season, as its year, such as 2024. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.

**Outputs**

- `player` (object): The player, by ID.
- `statistics` (object): The player's season.

**Example output**

```json
{
  "player": {
    "id": 682
  },
  "statistics": {
    "behinds": {
      "average": 0.3,
      "total": 7
    },
    "clearances": {
      "average": 7.8,
      "total": 202
    },
    "disposals": {
      "average": 29.3,
      "total": 762
    },
    "free_kicks": {
      "against": {
        "average": 1.2,
        "total": 30
      },
      "for": {
        "average": 1.3,
        "total": 35
      }
    },
    "games": {
      "played": 26
    },
    "goals": {
      "assists": {
        "average": 1.0,
        "total": 26
      },
      "total": {
        "average": 0.5,
        "total": 13
      }
    },
    "handballs": {
      "average": 15.7,
      "total": 409
    },
    "hitouts": {
      "average": 0,
      "total": 0
    },
    "kicks": {
      "average": 13.6,
      "total": 353
    },
    "marks": {
      "average": 4.6,
      "total": 120
    },
    "tackles": {
      "average": 3.3,
      "total": 85
    }
  }
}
```

### Get pre-match odds

Get bookmakers' pre-match odds for a game, optionally from one bookmaker or for one bet type. Odds appear 1 to 7 days before a game, are updated four times a day and are kept for 7 days after it.

**Inputs**

- Game ID (`game_id`, text, required): The game, by ID. List games gives game IDs.
- Bookmaker (`bookmaker_id`, text): Optional. Only this bookmaker's odds. Pick one from the list.
- Bet type (`bet_id`, text): Optional. Only this kind of bet, such as Home/Away. Pick one from the list.

**Outputs**

- `count` (number): How many came back.
- `odds` (list): The game's odds.

**Example output**

```json
{
  "count": 1,
  "odds": [
    {
      "bookmakers": [
        {
          "bets": [
            {
              "id": 1,
              "name": "Home/Away",
              "values": [
                {
                  "odd": 2.0,
                  "value": "Home"
                },
                {
                  "odd": 1.78,
                  "value": "Away"
                }
              ]
            }
          ],
          "id": 1,
          "name": "NordicBet"
        }
      ],
      "game_id": 2742,
      "league": {
        "id": 1,
        "season": 2023
      }
    }
  ]
}
```

### Get scores by quarter

Get the score at the end of each quarter of a game, or of every game on a day: each side's goals, behinds and points so far, so the last quarter's are the final score.

**Inputs**

- Game ID (`game_id`, text): Optional. The game, by ID, such as 3058. Set this or a date, not both. List games gives game IDs.
- Date (`on_date`, date): Optional. Every game on this day, in the time zone chosen below, instead of one game. The free plan takes only yesterday, today or tomorrow.
- Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Australia/Melbourne. UTC when left empty.

**Outputs**

- `count` (number): How many came back.
- `games` (list): Each game's quarters.

**Example output**

```json
{
  "count": 1,
  "games": [
    {
      "game_id": 3058,
      "quarters": [
        {
          "quarter": 1,
          "teams": {
            "away": {
              "behinds": 3,
              "goals": 4,
              "id": 2,
              "points": 27
            },
            "home": {
              "behinds": 1,
              "goals": 3,
              "id": 14,
              "points": 19
            }
          }
        },
        {
          "quarter": 2,
          "teams": {
            "away": {
              "behinds": 7,
              "goals": 11,
              "id": 2,
              "points": 73
            },
            "home": {
              "behinds": 3,
              "goals": 4,
              "id": 14,
              "points": 27
            }
          }
        },
        {
          "quarter": 3,
          "teams": {
            "away": {
              "behinds": 11,
              "goals": 16,
              "id": 2,
              "points": 107
            },
            "home": {
              "behinds": 4,
              "goals": 5,
              "id": 14,
              "points": 34
            }
          }
        },
        {
          "quarter": 4,
          "teams": {
            "away": {
              "behinds": 12,
              "goals": 18,
              "id": 2,
              "points": 120
            },
            "home": {
              "behinds": 6,
              "goals": 9,
              "id": 14,
              "points": 60
            }
          }
        }
      ]
    }
  ]
}
```

### Get team statistics

Get a team's season: games played, and the total and average a game of disposals, kicks, handballs, free kicks, hitouts, clearances, marks, goals, goal assists, behinds and tackles.

**Inputs**

- Team (`team_id`, text, required): The team, such as 2 for the Brisbane Lions. Pick one from the list, or pass a team ID from an earlier step.
- Season (`season`, number, required): The season, as its year, such as 2024. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.

**Outputs**

- `statistics` (object): The team's season.
- `team` (object): The team, by ID. Find teams gives its name.

**Example output**

```json
{
  "statistics": {
    "defence": {
      "tackles": {
        "average": 54.5,
        "total": 1472
      }
    },
    "disposals": {
      "disposals": {
        "average": 361.3,
        "total": 9755
      },
      "free_kicks": {
        "average": 18.2,
        "total": 491
      },
      "handballs": {
        "average": 128.7,
        "total": 3476
      },
      "kicks": {
        "average": 232.6,
        "total": 6279
      }
    },
    "games": {
      "played": 27
    },
    "marks": {
      "average": 110.4,
      "total": 2982
    },
    "scoring": {
      "assists": {
        "average": 9.1,
        "total": 247
      },
      "behinds": {
        "average": 10.3,
        "total": 277
      },
      "goals": {
        "average": 13.5,
        "total": 364
      }
    },
    "stoppages": {
      "clearances": {
        "average": 40.4,
        "total": 1091
      },
      "hitouts": {
        "average": 35.5,
        "total": 959
      }
    }
  },
  "team": {
    "id": 2
  }
}
```

### Get the ladder

Get a season's ladder: each team's place, premiership points, games won, drawn and lost, points for and against, and last five results. Narrow to one team's line.

**Inputs**

- Season (`season`, number, required): The season, as its year, such as 2024. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.
- League (`league_id`, text): Optional. The competition: 1 for the AFL Premiership, API-AFL's only one, which is used when a season is set and this is left empty.
- Team (`team_id`, text): Optional. Only this team's line. Pick one from the list.

**Outputs**

- `count` (number): How many came back.
- `standings` (list): The ladder, from first place down.

**Example output**

```json
{
  "count": 2,
  "standings": [
    {
      "games": {
        "drawn": 0,
        "lost": 6,
        "played": 23,
        "win": 17
      },
      "last_5": "WWWLL",
      "points": {
        "against": 1769,
        "for": 2242
      },
      "position": 1,
      "pts": 68,
      "team": {
        "id": 14,
        "logo": "https://media.api-sports.io/afl/teams/14.png",
        "name": "Sydney Swans"
      }
    },
    {
      "games": {
        "drawn": 0,
        "lost": 7,
        "played": 23,
        "win": 16
      },
      "last_5": "WWWWW",
      "points": {
        "against": 1752,
        "for": 2011
      },
      "position": 2,
      "pts": 64,
      "team": {
        "id": 11,
        "logo": "https://media.api-sports.io/afl/teams/11.png",
        "name": "Port Adelaide Power"
      }
    }
  ]
}
```

### List bet types

List the kinds of bet API-AFL has odds for, such as Home/Away or Over/Under, with the IDs the odds filter takes.

**Inputs**

- Search (`search`, text): Optional. Only names containing this, at least 3 characters.

**Outputs**

- `bets` (list): The bet types.
- `count` (number): How many came back.

**Example output**

```json
{
  "bets": [
    {
      "id": 1,
      "name": "Home/Away"
    },
    {
      "id": 2,
      "name": "2nd Half 3Way Result"
    }
  ],
  "count": 2
}
```

### List bookmakers

List the bookmakers API-AFL has odds from, with the IDs the odds filter takes. These IDs are API-AFL's own: the same bookmaker can have another ID in another API-SPORTS API.

**Inputs**

- Search (`search`, text): Optional. Only names containing this, at least 3 characters.

**Outputs**

- `bookmakers` (list): The bookmakers.
- `count` (number): How many came back.

**Example output**

```json
{
  "bookmakers": [
    {
      "id": 1,
      "name": "NordicBet"
    },
    {
      "id": 2,
      "name": "WilliamHill"
    }
  ],
  "count": 2
}
```

### List games

List games and results by day, by season, or a team's in a season, live ones included, each with its round, venue, status and both sides' goals, behinds and score. A fixture the AFL moved stays in the list as Cancelled beside its new date, unless left out.

**Inputs**

- Date (`on_date`, date): Optional. Only games on this day, in the time zone chosen below. The free plan takes only yesterday, today or tomorrow.
- League (`league_id`, text): Optional. The competition: 1 for the AFL Premiership, API-AFL's only one, which is used when a season is set and this is left empty.
- Season (`season`, number): Optional. Only this season, as its year, such as 2024. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.
- Team (`team_id`, text): Optional. Only this team's games, with a season. Pick one from the list.
- Leave out cancelled games (`leave_out_cancelled`, true/false): Optional. Leave out games marked Cancelled, most of which are fixtures that were moved to another date.
- Time zone (`timezone`, text): Optional. Give dates and times in this time zone, such as Australia/Melbourne. UTC when left empty.

**Outputs**

- `count` (number): How many came back.
- `games` (list): The games, in the order given.

**Example output**

```json
{
  "count": 1,
  "games": [
    {
      "attendance": null,
      "date": "2024-09-28T04:30:00+00:00",
      "id": 3058,
      "league": {
        "id": 1,
        "season": 2024
      },
      "round": "Postseason",
      "scores": {
        "away": {
          "behinds": 12,
          "goals": 18,
          "psbehinds": 0,
          "psgoals": 0,
          "score": 120
        },
        "home": {
          "behinds": 6,
          "goals": 9,
          "psbehinds": 0,
          "psgoals": 0,
          "score": 60
        }
      },
      "status": {
        "long": "Finished",
        "short": "FT"
      },
      "teams": {
        "away": {
          "id": 2,
          "logo": "https://media.api-sports.io/afl/teams/2.png",
          "name": "Brisbane Lions"
        },
        "home": {
          "id": 14,
          "logo": "https://media.api-sports.io/afl/teams/14.png",
          "name": "Sydney Swans"
        }
      },
      "time": "04:30",
      "timestamp": 1727497800,
      "timezone": "UTC",
      "venue": "Melbourne Cricket Ground",
      "week": 28
    }
  ]
}
```

### List leagues

List the competition once for each season on file, with the season's first and last day and whether it is under way. Narrow to one season, or to the season under way.

**Inputs**

- League (`league_id`, text): Optional. The competition: 1 for the AFL Premiership, API-AFL's only one, which is used when a season is set and this is left empty.
- Season (`season`, number): Optional. Only this season, as its year, such as 2024. The free plan reads the 2022 to 2024 seasons. From 1900 to 2100.
- Season under way only (`current_only`, true/false): Optional. Only the season under way; none between seasons.

**Outputs**

- `count` (number): How many came back.
- `leagues` (list): The competition, once for each season.

**Example output**

```json
{
  "count": 1,
  "leagues": [
    {
      "current": false,
      "end": "2024-09-28",
      "id": 1,
      "logo": "https://media.api-sports.io/afl/leagues/1.png",
      "name": "AFL Premiership",
      "season": 2024,
      "start": "2024-03-07"
    }
  ]
}
```

### List seasons

List the seasons API-AFL has data for, oldest first, as the years the Season fields take.

**Inputs**: None.

**Outputs**

- `count` (number): How many came back.
- `seasons` (list): The seasons, oldest first.

**Example output**

```json
{
  "count": 16,
  "seasons": [
    2011,
    2012,
    2013,
    2014,
    2015,
    2016,
    2017,
    2018,
    2019,
    2020,
    2021,
    2022,
    2023,
    2024,
    2025,
    2026
  ]
}
```