# rugbypy


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

*8000*+ players, *250*+ teams, *6000*+ games over the 2022, 2023, 2024 &
2025 seasons - `rugbypy` is a Python package that aims to make rugby
data more available to aid in the development of rugby analytics.
Documentation can be found [here](seanyboi.github.io/rugbypy/)

![PyPI - Downloads](https://img.shields.io/pypi/dm/rugbypy.png) ![PyPI -
Python Version](https://img.shields.io/pypi/pyversions/rugbypy.png)

If you would like to help keep the lights on and support this repo feel
free to buy me a coffee!

[![](https://raw.githubusercontent.com/pachadotdev/buymeacoffee-badges/main/bmc-donate-yellow.svg)](https://buymeacoffee.com/oconnorjamz)

## Requirements

`python version 3.11`

## Install

``` sh
pip install rugbypy
```

## How to use

### Match Stats

You can fetch all matches that have ever occurred with:

``` python
from rugbypy.match import *
matches = fetch_all_matches()
matches
```

    Fetching all matches...

<div>

|      | match_id | home_team                       | away_team             | date     |
|------|----------|---------------------------------|-----------------------|----------|
| 1498 | cae3129b | Exeter Chiefs                   | Bristol Rugby         | 20220101 |
| 1499 | 494f4092 | Scarlets                        | Ospreys               | 20220101 |
| 1500 | 77e4e537 | Connacht                        | Munster               | 20220101 |
| 1501 | fbca6594 | Stade Francais Paris            | Perpignan             | 20220101 |
| 1502 | 7863a641 | Clermont Auvergne               | Stade Toulousain      | 20220101 |
| ...  | ...      | ...                             | ...                   | ...      |
| 1121 | 2ac5db4a | Shizuoka Bluerevs               | Urayasu D Rocks       | 20251228 |
| 1122 | a68f4527 | Toshiba Brave Lupus Tokyo       | Yokohama Canon Eagles | 20251228 |
| 1123 | 00adb234 | Mitsubishi Sagamihara Dynaboars | Saitama Wild Knights  | 20251228 |
| 1117 | e37207b8 | Leicester                       | Exeter Chiefs         | 20251228 |
| 4743 | 667ee422 | Beziers                         | Uso Nevers            | 20260403 |

<p>6171 rows × 4 columns</p>
</div>

You can fetch all the matches that occured on a particular date with:

``` python
from rugbypy.match import *
matches = fetch_matches_by_date(date="20251205")
matches
```

    Fetching matches on date: 20251205...

<div>

|  | match_id | competition_id | home_team_id | home_team | away_team_id | away_team |
|----|----|----|----|----|----|----|
| 0 | 35e0b16d | ee0c6883 | d7d74d92 | Sale Sharks | 6f08f859 | Glasgow Warriors |
| 1 | f29de850 | ee0c6883 | fe2eda63 | Bayonne | f54be954 | Stormers |
| 2 | 722ce3c7 | 83d92007 | 0aa2b3cc | Ulster | 2e49b214 | Racing 92 |
| 3 | 6afe8441 | 822142db | deee3415 | Beziers | af22c862 | Soyaux Angouleme |
| 4 | 719b1db1 | 822142db | 93d1e116 | Carcassonne | 34149c5c | Vannes |
| 5 | 3aa1bb81 | 822142db | 98fce2f7 | Biarritz | 791d6c23 | Valence Romans |
| 6 | 575235eb | 822142db | 870e9fb0 | Aurillac | d5468acc | Brive |
| 7 | 66a1c770 | 822142db | 6992ab09 | Dax | 8b15a375 | Uso Nevers |
| 8 | f196da5a | 822142db | 2bac4677 | Agen | 4f43e2ca | Provence Rugby |
| 9 | 416f317e | 822142db | 6de7a527 | Mont De Marsan | 53983719 | Oyonnax |

</div>

The old method below is deprecated as of v3:

``` python
matches = fetch_matches(date="20230101")
```

    Deprecated, please use the fetch_matches_by_date() function instead

Then using that match id you can feed it into the match details
function:

``` python
from rugbypy.match import *
match_details = fetch_match_details(match_id="35e0b16d")
match_details
```

    Fetching match details for match_id: 35e0b16d...

<div>

|  | match_id | date | season | competition_id | competition | venue_id | venue | city_played | home_team | away_team | ... | completed | is_tournament | played_on_grass | attendance | home_team_form | away_team_form | kickoff_time | home_score | away_score | referee |
|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
| 0 | 35e0b16d | 20251205 | 2025 | ee0c6883 | European Rugby Champions Cup | 059580a0 | CorpAcq Stadium | Salford | Sale Sharks | Glasgow Warriors | ... | True | True | True | None | WLWLL | WWWWL | 14:30 | 21 | 26 | None |

<p>1 rows × 22 columns</p>
</div>

### Team Stats

You can fetch all the teams within the rugbypy database from our
registry with:

``` python
fetch_all_teams()
```

    Fetching all teams available...

<div>

|     | team_id  | team_name            |
|-----|----------|----------------------|
| 0   | 5fa975a5 | Ospreys              |
| 1   | 79c81be4 | Cardiff Blues        |
| 2   | 0e10c257 | Scarlets             |
| 3   | 973ef5cc | Gwent Dragons        |
| 4   | 93542906 | Newcastle            |
| ... | ...      | ...                  |
| 284 | 0c3eb5f5 | France Women 7s      |
| 285 | 91fc7224 | Brazil Women 7s      |
| 286 | 03817b3b | Fiji Women 7s        |
| 287 | 3baba750 | Canada Women 7s      |
| 288 | 04349324 | New Zealand Women 7s |

<p>289 rows × 2 columns</p>
</div>

You can fetch the team stats for a particular with:

``` python
from rugbypy.team import *
team_stats = fetch_team_stats(team_id="93542906")
team_stats
```

    Fetching all team stats for team_id: 93542906...

<div>

|  | team | game_date | team_id | team_vs | team_vs_id | match_id | players | 22m_entries | 22m_conversion | line_breaks | ... | scrums_won | tackles | territory | total_free_kicks_conceded | total_lineouts | tries | turnover_knock_on | turnovers_conceded | yellow_cards | metres_carried |
|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
| 0 | Newcastle | 20250103 | 93542906 | Harlequins | 566d5199 | 3e3e2af2 | \[4e129a8c, 39c63750, 04f27e6a, 8a10bc21, 0c2d9... | 9.0 | 4.22 | 6.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 1 | Newcastle | 20250111 | 93542906 | Ospreys | 5fa975a5 | f8d5672a | \[39c63750, f9e52f58, ece068ae, bfb19f72, d5a55... | 10.0 | 3.50 | 8.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 2 | Newcastle | 20250117 | 93542906 | Montpellier | b6f40da2 | 57acf63c | \[39c63750, 04f27e6a, f9e52f58, 0c2d9ef3, ece06... | 12.0 | 2.17 | 9.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 3 | Newcastle | 20250126 | 93542906 | Bristol | 47d5fe17 | 10cecec6 | \[4e129a8c, 39c63750, 04f27e6a, 8a10bc21, 0c2d9... | 7.0 | 5.00 | 2.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 4 | Newcastle | 20250321 | 93542906 | Sale | d7d74d92 | 1eed410b | \[4e129a8c, 04f27e6a, b7a90ca8, 8a10bc21, 0c2d9... | 8.0 | 1.88 | 3.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 87 | Newcastle | 20241129 | 93542906 | Saracens | 0026b492 | 355072a4 | \[1ec5b586, a850f667, 0c2d9ef3, 40ef3013, 20006... | 9.0 | 1.89 | 4.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 88 | Newcastle | 20241208 | 93542906 | Pau | 73e02b8e | 04558689 | \[1ec5b586, 548a8c29, a850f667, 0c2d9ef3, 20006... | 12.0 | 2.67 | 7.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 89 | Newcastle | 20241215 | 93542906 | Gwent Dragons | 973ef5cc | 9f498135 | \[1ec5b586, 548a8c29, a850f667, 0c2d9ef3, 20006... | 12.0 | 1.83 | 6.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 90 | Newcastle | 20241221 | 93542906 | Bath | aa4f64f5 | e251bdbf | \[1ec5b586, 548a8c29, a850f667, 0c2d9ef3, 40ef3... | 12.0 | 3.33 | 6.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 91 | Newcastle | 20241228 | 93542906 | Northampton | 895ae027 | c8490107 | \[1ec5b586, a850f667, 0c2d9ef3, 40ef3013, 20006... | 12.0 | 5.08 | 12.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |

<p>92 rows × 59 columns</p>
</div>

You can then fetch the team stats for a particular team on a particular
date with:

``` python
from rugbypy.team import *
team_stats = fetch_team_stats(team_id="93542906", date="20251213")
team_stats
```

    Fetching team stats for team_id: 93542906 on date: 20251213...

<div>

|  | team | game_date | team_id | team_vs | team_vs_id | match_id | players | 22m_entries | 22m_conversion | line_breaks | ... | scrums_won | tackles | territory | total_free_kicks_conceded | total_lineouts | tries | turnover_knock_on | turnovers_conceded | yellow_cards | metres_carried |
|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
| 18 | Newcastle | 20251213 | 93542906 | Lions | bb49fc47 | 87ab265a | \[dbd1161c, 4e129a8c, 8a10bc21, 3b0a4aa4, 0c2d9... | 9.0 | 1.11 | 4.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |

<p>1 rows × 59 columns</p>
</div>

### Player Stats

We have the ability to fetch player stats for all the games they have
been involved in. We firstly identify the `player_id` of a player by
searching our player registry.

``` python
from rugbypy.player import *
players = fetch_all_players()
players
```

<div>

|      | player_id | player_name       |
|------|-----------|-------------------|
| 0    | 9f0d99ce  | Morgan Morris     |
| 1    | e31a204b  | James Ratti       |
| 2    | b1d2895a  | Max Nagy          |
| 3    | 25bfea05  | Daniel Kasende    |
| 4    | 24717f78  | Jac Morgan        |
| ...  | ...       | ...               |
| 8439 | b4a9513f  | Paul Mullen       |
| 8440 | edf9d7e1  | Tom Baraer        |
| 8441 | da8da81b  | Nathan Van de Ven |
| 8442 | d5c9a047  | Nicolas Gali      |
| 8443 | 3834ffae  | Nicholas Muli     |

<p>8444 rows × 2 columns</p>
</div>

Or we can search for a certain player through our similarity tool:

``` python
from rugbypy.player import *
individual_player = fetch_player_id("jac morgan")
individual_player
```

<div>

|      | player_id | player_name     |
|------|-----------|-----------------|
| 4    | 24717f78  | Jac Morgan      |
| 3518 | 2c8b48a5  | Francesco Braga |
| 5860 | e387e07f  | Franco Lamanna  |

</div>

Once we have their `player_id` we can fetch their player stats using
[`fetch_player_stats`](https://seanyboi.github.io/rugbypy/player.html#fetch_player_stats).
In this example we fetch Jac Morgan player stats:

``` python
from rugbypy.player import *
player_stats = fetch_player_stats(player_id="24717f78")
player_stats
```

    Fetching all player stats for player_id: 24717f78...

<div>

|  | player_id | name | team | team_id | position | carries | line_breaks | tackles_completed | turnovers_lost | turnovers_won | ... | offload | penalty_goals | points | rucks_won | runs | tackles | total_free_kicks_conceded | total_lineouts | turnover_knock_on | turnovers_conceded |
|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
| 0 | 24717f78 | Jac Morgan | Ospreys | 5fa975a5 | blindside_flanker | 9.0 | 0.0 | 19.0 | 0.0 | 0.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 1 | 24717f78 | Jac Morgan | Ospreys | 5fa975a5 | blindside_flanker | 11.0 | 0.0 | 12.0 | 1.0 | 1.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 2 | 24717f78 | Jac Morgan | Ospreys | 5fa975a5 | openside_flanker | 10.0 | 0.0 | 30.0 | 0.0 | 2.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 3 | 24717f78 | Jac Morgan | Wales | b6319444 | flanker | 15.0 | 1.0 | NaN | NaN | NaN | ... | 1.0 | 0.0 | 0.0 | 12.0 | 15.0 | 21.0 | 0.0 | 0.0 | 2.0 | 3.0 |
| 4 | 24717f78 | Jac Morgan | Wales | b6319444 | flanker | 8.0 | 0.0 | NaN | NaN | NaN | ... | 0.0 | 0.0 | 0.0 | 7.0 | 8.0 | 13.0 | 0.0 | 0.0 | 1.0 | 1.0 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 67 | 24717f78 | Jac Morgan | Wales | b6319444 | openside_flanker | 14.0 | 0.0 | 27.0 | 0.0 | 1.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 68 | 24717f78 | Jac Morgan | Wales | b6319444 | openside_flanker | 11.0 | 0.0 | 28.0 | 0.0 | 1.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 69 | 24717f78 | Jac Morgan | Ospreys | 5fa975a5 | number_eight | 13.0 | 1.0 | 12.0 | 0.0 | 3.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 70 | 24717f78 | Jac Morgan | Ospreys | 5fa975a5 | openside_flanker | 9.0 | 0.0 | 11.0 | 0.0 | 2.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 71 | 24717f78 | Jac Morgan | Ospreys | 5fa975a5 | blindside_flanker | 14.0 | 0.0 | 12.0 | 0.0 | 4.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |

<p>72 rows × 54 columns</p>
</div>

We can also fetch the player stats on a particular date using
[`fetch_player_stats`](https://seanyboi.github.io/rugbypy/player.html#fetch_player_stats).
In this example we fetch Jac Morgans player stats on 2025-01-01:

``` python
from rugbypy.player import *
player_stats = fetch_player_stats(player_id="24717f78", date="20250101")
player_stats
```

    Fetching player stats for player_id: 24717f78 on date: 20250101...

<div>

|  | player_id | name | team | team_id | position | carries | line_breaks | tackles_completed | turnovers_lost | turnovers_won | ... | offload | penalty_goals | points | rucks_won | runs | tackles | total_free_kicks_conceded | total_lineouts | turnover_knock_on | turnovers_conceded |
|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----|
| 0 | 24717f78 | Jac Morgan | Ospreys | 5fa975a5 | blindside_flanker | 9.0 | 0.0 | 19.0 | 0.0 | 0.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |

<p>1 rows × 54 columns</p>
</div>

### Competition data

You can fetch all competition ids to from our competition registry with:

``` python
from rugbypy.competition import *
competitions = fetch_all_competitions()
competitions
```

    Fetching all competition...

<div>

|     | competition_id | competition_name             |
|-----|----------------|------------------------------|
| 0   | 50e6935b       | World Rugby U20 Championship |
| 1   | 0fad1a69       | Premiership Womens Rugby     |
| 2   | 2f0de05a       | French Top 14                |
| 3   | d7c59c8c       | Japan Rugby League One       |
| 4   | 822142db       | Pro D2                       |
| 5   | 83d92007       | European Rugby Challenge Cup |
| 6   | 467a422f       | Womens Six Nations           |
| 7   | 0bc7d681       | British and Irish Lions Tour |
| 8   | c2f89f12       | Currie Cup                   |
| 9   | 679f8455       | Bunnings Npc                 |
| 10  | b5e3c6bd       | Women's Rugby World Cup      |
| 11  | bc5d9ec5       | Pacific Nations Cup          |
| 12  | ee0c6883       | European Rugby Champions Cup |
| 13  | 2c3df351       | Gallagher Prem               |
| 14  | 23df32a1       | International Test Match     |
| 15  | 0ab9177f       | Major League Rugby           |
| 16  | 622e1591       | URBA Top 12                  |
| 17  | 814f16bc       | Mitre 10 Cup                 |
| 18  | 877aa127       | Super Rugby                  |
| 19  | 30e7e1ca       | Womens Internationals        |
| 20  | df0639c9       | U20 Six Nations              |
| 21  | a97ec065       | Olympic Men's 7s             |
| 22  | 0f8b619e       | Olympic Women's Rugby Sevens |

</div>

### Venue data

You can fetch all venue ids to from our venue registry with:

``` python
from rugbypy.venue import *
competitions = fetch_all_venues()
competitions
```

    Fetching all venues...

<div>

|     | venue_id | venue_name                                 |
|-----|----------|--------------------------------------------|
| 0   | fb155133 | Cardiff Arms Park                          |
| 1   | 1f19e651 | Parc y Scarlets                            |
| 2   | 74f2b7f9 | Kingston Park                              |
| 3   | 477771ab | Kingsholm                                  |
| 4   | 3933483f | Mattioli Woods Welford Road Stadium        |
| ... | ...      | ...                                        |
| 345 | 8c0b3ee4 | Estadio Jorge Luis Hirschi                 |
| 346 | 8a535068 | Estadio Brigadier General Estanislao López |
| 347 | b9f8a9dd | Massey university                          |
| 348 | cc60410c | Bluenergy Stadium                          |
| 349 | 8c764117 | Chambéry Savoie Stadium                    |

<p>350 rows × 2 columns</p>
</div>
