### Install API Football v3 Ruby Gem

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

Instructions for adding the API Football v3 gem to your application's Gemfile for installation via Bundler, or for standalone installation using the gem command.

```ruby
gem 'api_football_v3'
```

--------------------------------

### Venues API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Gets stadium and venue information.

```APIDOC
## Venues API

### Description
Gets stadium and venue information.

### Method
GET

### Endpoint
`/venues`

### Parameters
#### Query Parameters
- **id** (integer) - Optional - Venue ID.
- **country** (string) - Optional - Country name.
- **search** (string) - Optional - Search by venue name.

### Request Example
```ruby
# Get venue by ID
response = @client.venues(id: 316)

# Get venues by country
response = @client.venues(country: "Chile")

# Search venue by name
response = @client.venues(search: "Nacional")
```
```

--------------------------------

### Predictions API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Gets match predictions and betting tips for upcoming fixtures.

```APIDOC
## Predictions API

### Description
Gets match predictions and betting tips for upcoming fixtures.

### Method
GET

### Endpoint
`/predictions`

### Parameters
#### Query Parameters
- **fixture** (integer) - Required - Fixture ID.

### Request Example
```ruby
# Get predictions for a fixture
response = @client.predictions(fixture: 123456)
```

### Response Example
```json
{
  "get": "predictions",
  "response": [
    {
      "predictions": {
        "winner": { "name": "Team A" },
        "percent": { "home": "60%", "draw": "25%", "away": "15%" }
      }
    }
  ]
}
```
```

--------------------------------

### General Endpoint Access

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

Demonstrates the general method for accessing any API endpoint using the `get` function with an endpoint path and options.

```APIDOC
## General Endpoint Access

### Description
All available endpoints can be accessed using a general `get(endpoint, options)` method. This method allows you to specify the desired endpoint path and any associated options (parameters) as a hash.

### Method
GET

### Endpoint
Any valid API endpoint path (e.g., `/coachs`, `/fixtures`, `/players/topscorers`)

### Parameters
#### Path Parameters
None for the general `get` method itself, but the `endpoint` string will contain path parameters if applicable.

#### Query Parameters
- **endpoint** (string) - Required - The specific API endpoint path to access (e.g., "/countries", "/leagues?season=2020").
- **options** (hash) - Optional - A hash containing key-value pairs for query parameters supported by the specific endpoint.

### Request Example
```ruby
# Example: Fetching countries with a search parameter
@client.get("/countries", { search: "Chile" })

# Example: Fetching fixtures for a specific league and season
@client.get("/fixtures", { league: 265, season: 2020 })
```

### Response
#### Success Response (200)
The response structure depends on the specific endpoint being called. Refer to the documentation for individual endpoints for details on their response format.

#### Response Example
(See examples for specific endpoints like `/countries` or `/leagues`)
```

--------------------------------

### Generic GET Method

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Provides direct access to any API endpoint, useful for endpoints not covered by convenience methods or when fine-grained control is needed.

```APIDOC
## Generic GET Method

### Description
Provides direct access to any API endpoint, useful for endpoints not covered by convenience methods or when fine-grained control is needed.

### Method
GET

### Endpoint
Any valid API endpoint path.

### Parameters
#### Path Parameters
- **endpoint** (string) - Required - The API endpoint path (e.g., `/teams`).

#### Query Parameters
- **params** (hash) - Optional - A hash of query parameters for the request.

### Request Example
```ruby
# Direct endpoint access
response = @client.get('/teams', { id: 2323 })

# Access any endpoint with custom parameters
response = @client.get('/fixtures', { league: 265, season: 2020, from: "2020-09-01", to: "2020-09-30" })
```
```

--------------------------------

### Get Coach by ID

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches information about a specific coach using their ID. Requires a coach ID.

```ruby
response = @client.coaches(id: 123)
```

--------------------------------

### Generic Endpoint Access - Ruby

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

Demonstrates the generic 'get' method for accessing API endpoints, allowing flexibility by specifying the endpoint path and options as parameters. This method returns a JSON object.

```ruby
get(endpoint, options)
```

--------------------------------

### Get Teams by ID using API Football v3 Client

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

This snippet shows how to use a client to make a GET request to the /teams endpoint, filtering by a specific team ID. It requires an initialized client object and returns team data in JSON format.

```javascript
@client.get('/teams', { id: 2323 })
```

--------------------------------

### Get Standings for a League and Season

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches the league standings and table for a specific league and season. Requires a league ID and season year.

```ruby
response = @client.standings(league: 265, season: 2020)
```

--------------------------------

### Get Odds Mapping

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves mapping information related to odds data. This method can be paginated.

```ruby
mapping = @client.mapping(page: 1)
```

--------------------------------

### Get Transfers by Player

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches the transfer history for a specific player. Requires a player ID.

```ruby
response = @client.transfers(player: 276)
```

--------------------------------

### Get Venue by ID

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches information about a specific venue using its ID. Requires a venue ID.

```ruby
response = @client.venues(id: 316)
```

--------------------------------

### Get Trophies by Coach

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves the trophy/title information for a specific coach. Requires a coach ID.

```ruby
response = @client.trophies(coach: 123)
```

--------------------------------

### Get Available Bookmakers

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches a list of all available bookmakers supported by the API. This method does not require any parameters.

```ruby
bookmakers = @client.bookmakers
```

--------------------------------

### Get Available Bet Types

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves a list of all available bet types for which odds data can be fetched. This method does not require any parameters.

```ruby
bets = @client.bets
```

--------------------------------

### Get Trophies by Player

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches the trophy/title information for a specific player. Requires a player ID.

```ruby
response = @client.trophies(player: 276)
```

--------------------------------

### Get Predictions for a Fixture

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves match predictions and betting tips for a given fixture ID. Requires a fixture ID.

```ruby
response = @client.predictions(fixture: 123456)
```

--------------------------------

### Get Available Timezones

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Returns a list of all available timezones supported by the API for date and time conversions. This method does not require any parameters.

```ruby
response = @client.timezones
```

--------------------------------

### Get Available Player Seasons

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves a list of all available seasons for which player data can be fetched. This method does not require any parameters.

```ruby
seasons = @client.players_seasons
```

--------------------------------

### GET /teams

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

Retrieves a list of teams based on the provided parameters. This endpoint allows filtering by team ID.

```APIDOC
## GET /teams

### Description
Retrieves a list of teams. This example shows how to fetch a specific team by its ID.

### Method
GET

### Endpoint
/teams

### Parameters
#### Query Parameters
- **id** (integer) - Optional - The ID of the team to retrieve.

### Request Example
```json
{
  "id": 2323
}
```

### Response
#### Success Response (200)
- **get** (string) - The type of data requested ('teams').
- **parameters** (object) - The parameters used for the request.
  - **id** (string) - The ID of the team requested.
- **errors** (array) - An array of errors, if any.
- **results** (integer) - The number of results returned.
- **paging** (object) - Pagination information.
  - **current** (integer) - The current page number.
  - **total** (integer) - The total number of pages.
- **response** (array) - An array of team objects.
  - **team** (object) - Details about the team.
    - **id** (integer) - The unique identifier for the team.
    - **name** (string) - The name of the team.
    - **country** (string) - The country the team belongs to.
    - **founded** (integer) - The year the team was founded.
    - **national** (boolean) - Indicates if the team is a national team.
    - **logo** (string) - URL of the team's logo.
  - **venue** (object) - Details about the team's home venue.
    - **id** (integer) - The unique identifier for the venue.
    - **name** (string) - The name of the venue.
    - **address** (string) - The address of the venue.
    - **city** (string) - The city where the venue is located.
    - **capacity** (integer) - The capacity of the venue.
    - **surface** (string) - The type of playing surface.
    - **image** (string) - URL of the venue's image.

#### Response Example
```json
{
    "get":"teams",
    "parameters":{
        "id":"2323"
    },
    "errors":[],
    "results":1,
    "paging":{
        "current":1,
        "total":1
    },
    "response":[
        {
            "team":{
                "id":2323,
                "name":"Universidad de Chile",
                "country":"Chile",
                "founded":1927,
                "national":false,
                "logo":"https://media.api-sports.io/football/teams/2323.png"
            },
            "venue":{
                "id":316,
                "name":"Estadio Nacional Julio Martinez Pradanos",
                "address":"Avenida Grecia 2001, Nuñoa",
                "city":"Santiago de Chile",
                "capacity":48665,
                "surface":"grass",
                "image":"https://media.api-sports.io/football/venues/316.png"
            }
        }
    ]
}
```
```

--------------------------------

### Get Coaches by Team

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves a list of coaches associated with a specific team. Requires a team ID.

```ruby
response = @client.coaches(team: 2323)
```

--------------------------------

### Get Venues by Country

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves a list of venues located in a specific country. Requires a country name.

```ruby
response = @client.venues(country: "Chile")
```

--------------------------------

### Get Sidelined Information by Coach

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches injury and suspension data for a specific coach. Requires a coach ID.

```ruby
response = @client.sidelined(coach: 123)
```

--------------------------------

### Get Player by ID and Season

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches player data for a specific player ID and season. Requires a valid player ID and season year.

```ruby
response = @client.players(id: 276, season: 2020)
```

--------------------------------

### Get Transfers by Team

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves the transfer history for players associated with a specific team. Requires a team ID.

```ruby
response = @client.transfers(team: 2323)
```

--------------------------------

### Get Odds for a Fixture

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches betting odds data for a specific fixture, including bookmakers and bet types. Requires a fixture ID.

```ruby
response = @client.odds(fixture: 123456)
```

--------------------------------

### Get Sidelined Information by Player

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves injury and suspension data for a specific player. Requires a player ID.

```ruby
response = @client.sidelined(player: 276)
```

--------------------------------

### Get Players by Team and Season

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves a list of players belonging to a specific team for a given season. Requires a team ID and season year.

```ruby
response = @client.players(team: 2323, season: 2020)
```

--------------------------------

### Get Top Scorers for a League

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches the top scorers for a specified league and season. Returns a list of players with their goal statistics. Requires a league ID and season year.

```ruby
top_scorers = @client.top_scorers(league: 265, season: 2020)
```

--------------------------------

### Initialize API Football V3 Client in Ruby

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Demonstrates how to initialize the ApiFootballV3::Client. Configuration can be done using a block with individual settings or by passing a hash of options. Ensure you replace 'YOUR_API_KEY' with your actual API key and select the correct base_url for your subscription type.

```ruby
require 'api_football_v3'

# Initialize with block configuration
@client = ApiFootballV3::Client.new do |config|
  config.api_key = "YOUR_API_KEY"
  config.base_url = "https://api-football-beta.p.rapidapi.com/"
  # Or for API-Sports subscribers:
  # config.base_url = "https://v3.football.api-sports.io/"
end

# Alternative: Initialize with hash options
@client = ApiFootballV3::Client.new(
  api_key: "YOUR_API_KEY",
  base_url: "https://v3.football.api-sports.io/"
)
```

--------------------------------

### Client Initialization

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Initialize the ApiFootballV3 client with your API key and the appropriate base URL.

```APIDOC
## Client Initialization

The `ApiFootballV3::Client` class is the main entry point for interacting with the API. It must be configured with your API key and the appropriate base URL depending on your subscription type (RapidAPI or API-Sports).

### Request Example
```ruby
require 'api_football_v3'

# Initialize with block configuration
@client = ApiFootballV3::Client.new do |config|
  config.api_key = "YOUR_API_KEY"
  config.base_url = "https://api-football-beta.p.rapidapi.com/"
  # Or for API-Sports subscribers:
  # config.base_url = "https://v3.football.api-sports.io/"
end

# Alternative: Initialize with hash options
@client = ApiFootballV3::Client.new(
  api_key: "YOUR_API_KEY",
  base_url: "https://v3.football.api-sports.io/"
)
```
```

--------------------------------

### Configure API Football v3 Client in Ruby

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

Demonstrates how to initialize and configure the ApiFootballV3 client with an API key and the appropriate base URL. This is essential for authenticating requests to the API Football v3 service.

```ruby
@client = ApiFootballV3::Client.new do |config|
  config.api_key = "YOUR_API_KEY"
  config.base_url = "https://api-football-beta.p.rapidapi.com/" #  or https://v3.football.api-sports.io/
end
```

--------------------------------

### Access Fixtures Data with API Football V3 Ruby Gem

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Shows how to access match fixtures using the API Football V3 Ruby gem. This includes fetching fixtures by date, league and season, retrieving live matches, and accessing specific details like rounds, head-to-head data, statistics, events, lineups, and player statistics for a given fixture.

```ruby
# Get fixtures by date
response = @client.fixtures(date: "2020-09-15")

# Get fixtures by league and season
response = @client.fixtures(league: 265, season: 2020)

# Get all live matches
live_matches = @client.live
# => { "get" => "fixtures", "parameters" => { "live" => "all" }, "response" => [...] }

# Get rounds for a league season
rounds = @client.rounds(league: 265, season: 2020)

# Head-to-head between two teams
h2h = @client.head_to_head(h2h: "2323-2324")

# Get fixture statistics
stats = @client.fixture_statistics(fixture: 123456)

# Get fixture events (goals, cards, substitutions)
events = @client.fixture_events(fixture: 123456)

# Get fixture lineups
lineups = @client.fixture_lineups(fixture: 123456)

# Get player statistics for a fixture
player_stats = @client.fixture_player_statistics(fixture: 123456)
```

--------------------------------

### Transfers API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches player transfer history and data.

```APIDOC
## Transfers API

### Description
Fetches player transfer history and data.

### Method
GET

### Endpoint
`/transfers`

### Parameters
#### Query Parameters
- **player** (integer) - Optional - Player ID.
- **team** (integer) - Optional - Team ID.

### Request Example
```ruby
# Get transfers by player
response = @client.transfers(player: 276)

# Get transfers by team
response = @client.transfers(team: 2323)
```
```

--------------------------------

### Search Coach by Name

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Searches for coaches by their name. Requires a search query string.

```ruby
response = @client.coaches(search: "Guardiola")
```

--------------------------------

### Accessing Various API Endpoints - Ruby

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

Provides a comprehensive list of available endpoints in the API Football v3 client library, showing direct method calls for each. These methods simplify accessing specific data categories like coaches, fixtures, leagues, etc.

```ruby
@client.coaches                     # /coachs

@client.countries                   # /countries

@client.fixtures                    # /fixtures
@client.live                        # /fixtures?live=all
@client.rounds                      # /fixtures/rounds
@client.head_to_head                # /fixtures/headtohead
@client.fixture_statistics          # /fixtures/statistics
@client.fixture_events              # /fixtures/events
@client.fixture_lineups             # /fixtures/lineups
@client.fixture_player_statistics   # /fixtures/players

@client.leagues                     # /leagues
@client.leagues_seasons             # /leagues/seasons

@client.odds                        # /odds
@client.mapping                     # /odds/mapping
@client.bookmakers                  # /odds/bookmakers
@client.bets                        # /odds/bets

@client.players                     # /players
@client.top_scorers                 # /players/topscorers
@client.players_seasons             # /players/seasons

@client.predictions                 # /predictions

@client.sidelined                   # /sidelined

@client.standings                   # /standings

@client.teams                       # /teams
@client.team_statistics             # /teams/statistics

@client.timezones                   # /timezone

@client.transfers                   # /transfers

@client.trophies                    # /trophies

@client.venues                      # /venues
```

--------------------------------

### Search Venue by Name

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Searches for venues by their name. Requires a search query string.

```ruby
response = @client.venues(search: "Nacional")
```

--------------------------------

### Error Handling with API Football V3 Gem

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Demonstrates how to handle specific API errors raised by the gem using begin-rescue blocks. The gem defines custom error classes for various HTTP status codes.

```ruby
begin
  response = @client.teams(id: 999999)
rescue ApiFootballV3::Error::NotFound => e
  puts "Team not found: #{e.message}"
rescue ApiFootballV3::Error::TooManyRequests => e
  puts "Rate limit exceeded, please wait before retrying"
rescue ApiFootballV3::Error::Unauthorized => e
  puts "Invalid API key"
rescue ApiFootballV3::Error::BadRequest => e
  puts "Invalid request parameters: #{e.message}"
rescue ApiFootballV3::Error::ServerError => e
  puts "API server error, try again later"
rescue ApiFootballV3::Error => e
  puts "API error: #{e.message}
end

# Available error classes:
# Client errors (4xx): BadRequest, Unauthorized, Forbidden, NotFound,
#                      NotAcceptable, RequestEntityTooLarge, UnprocessableEntity, TooManyRequests
# Server errors (5xx): InternalServerError, BadGateway, ServiceUnavailable, GatewayTimeout
```

--------------------------------

### Fetch Player Data with API Football V3 Ruby Gem

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

This section covers retrieving player information and statistics using the API Football V3 Ruby gem. It allows access to player details, performance statistics, top scorer lists, and available seasons for player data.

```ruby
# Placeholder for player API examples
# Example: Get player by ID (specific method not shown in original text, assuming a pattern)
# player_info = @client.players(id: 12345)

# Example: Get top scorers for a league and season
# top_scorers = @client.top_scorers(league: 265, season: 2020)

# Example: Get available seasons for player data
# player_seasons = @client.player_seasons
```

--------------------------------

### Fetch Team Data with API Football V3 Ruby Gem

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Illustrates how to retrieve team information and statistics using the API Football V3 Ruby gem. You can query for a specific team by ID or search for teams based on league, season, or country. The gem provides detailed team and venue information.

```ruby
# Get team by ID
response = @client.teams(id: 2323)
# => {
#      "get" => "teams",
#      "response" => [
#        {
#          "team" => {
#            "id" => 2323,
#            "name" => "Universidad de Chile",
#            "country" => "Chile",
#            "founded" => 1927,
#            "logo" => "https://media.api-sports.io/football/teams/2323.png"
#          },
#          "venue" => {
#            "id" => 316,
#            "name" => "Estadio Nacional Julio Martinez Pradanos",
#            "capacity" => 48665
#          }
#        }
#      ]
#    }

# Get team statistics for a specific league and season
stats = @client.team_statistics(team: 2323, league: 265, season: 2020)
```

--------------------------------

### Standings API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches league standings and tables for a specific season.

```APIDOC
## Standings API

### Description
Fetches league standings and tables for a specific season.

### Method
GET

### Endpoint
`/standings`

### Parameters
#### Query Parameters
- **league** (integer) - Required - League ID.
- **season** (integer) - Required - The season year (e.g., 2020).

### Request Example
```ruby
# Get standings for a league and season
response = @client.standings(league: 265, season: 2020)
```

### Response Example
```json
{
  "get": "standings",
  "response": [
    {
      "league": {
        "standings": [[
          { "rank": 1, "team": { "name": "Team A" }, "points": 45 },
          { "rank": 2, "team": { "name": "Team B" }, "points": 42 }
        ]]
      }
    }
  ]
}
```
```

--------------------------------

### Fetch League Data with API Football V3 Ruby Gem

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Demonstrates fetching league information using the API Football V3 Ruby gem. You can retrieve leagues filtered by country and season, or fetch all available seasons. The gem returns detailed league data, including season information.

```ruby
# Get leagues by country and season
response = @client.leagues(country: "Chile", season: 2020)
# => {
#      "get" => "leagues",
#      "parameters" => { "country" => "Chile", "season" => "2020" },
#      "results" => 2,
#      "response" => [
#        {
#          "league" => { "id" => 265, "name" => "Primera Division", "type" => "League" },
#          "country" => { "name" => "Chile", "code" => "CL" },
#          "seasons" => [{ "year" => 2020, "current" => true, ... }]
#        }
#      ]
#    }

# Get all available seasons
seasons = @client.leagues_seasons
# => { "get" => "leagues/seasons", "response" => [2010, 2011, ..., 2024]}
```

--------------------------------

### Sample API Football v3 Teams Response

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

This is a sample JSON response from the API Football v3 /teams endpoint when requesting data for a specific team ID. It includes details about the team and its venue.

```json
{
    "get":"teams",
    "parameters":{
        "id":"2323"
    },
    "errors":[],
    "results":1,
    "paging":{
        "current":1,
        "total":1
    },
    "response":[
        {
            "team":{
                "id":2323,
                "name":"Universidad de Chile",
                "country":"Chile",
                "founded":1927,
                "national":false,
                "logo":"https://media.api-sports.io/football/teams/2323.png"
            },
            "venue":{
                "id":316,
                "name":"Estadio Nacional Julio Mart\u00EDnez Pr\u00E1danos",
                "address":"Avenida Grecia 2001, \u00D1u\u00F1oa",
                "city":"Santiago de Chile",
                "capacity":48665,
                "surface":"grass",
                "image":"https://media.api-sports.io/football/venues/316.png"
            }
        }
    ]
}
```

--------------------------------

### Fixtures API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Accesses match fixtures with various filtering options including live matches, rounds, head-to-head, statistics, events, lineups, and player statistics.

```APIDOC
## Fixtures API

Accesses match fixtures with various filtering options including live matches, rounds, head-to-head, statistics, events, lineups, and player statistics.

### Method
`GET`

### Endpoint
`/fixtures`

### Parameters
#### Query Parameters
- **date** (string) - Optional - Filter fixtures by a specific date (YYYY-MM-DD).
- **league** (integer) - Optional - Filter fixtures by league ID.
- **season** (integer) - Optional - Filter fixtures by season year.
- **live** (string) - Optional - Filter for live matches (e.g., "all").
- **h2h** (string) - Optional - Filter for head-to-head fixtures between two teams (e.g., "team1-team2").
- **fixture** (integer) - Optional - The ID of the fixture to get details for.

### Request Example
```ruby
# Get fixtures by date
response = @client.fixtures(date: "2020-09-15")

# Get fixtures by league and season
response = @client.fixtures(league: 265, season: 2020)

# Get all live matches
live_matches = @client.live

# Get rounds for a league season
rounds = @client.rounds(league: 265, season: 2020)

# Head-to-head between two teams
h2h = @client.head_to_head(h2h: "2323-2324")

# Get fixture statistics
stats = @client.fixture_statistics(fixture: 123456)

# Get fixture events (goals, cards, substitutions)
events = @client.fixture_events(fixture: 123456)

# Get fixture lineups
lineups = @client.fixture_lineups(fixture: 123456)

# Get player statistics for a fixture
player_stats = @client.fixture_player_statistics(fixture: 123456)
```

### Response
#### Success Response (200)
- **get** (string) - The endpoint name.
- **parameters** (object) - The parameters used for the request.
- **results** (integer) - The number of results returned.
- **response** (array) - An array of fixture objects, each containing detailed match information.

#### Response Example (Fixtures)
```json
{
  "get": "fixtures",
  "parameters": {"date": "2020-09-15"},
  "results": 10,
  "response": [
    {
      "fixture": {"id": 123456, ...},
      "league": {...},
      "teams": {...},
      "goals": {...},
      "score": {...}
    }
  ]
}
```
```

--------------------------------

### Fetch Countries with Search - Ruby

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

Demonstrates how to fetch country data using the 'countries' method with a search parameter. It returns a JSON object containing country information.

```ruby
@client.countries(search: "Chile")
```

--------------------------------

### Leagues API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Fetches league information including seasons, coverage details, and associated countries. Filter by country, season, league ID, or type.

```APIDOC
## Leagues API

Fetches league information including seasons, coverage details, and associated countries. Filter by country, season, league ID, or type.

### Method
`GET`

### Endpoint
`/leagues`

### Parameters
#### Query Parameters
- **country** (string) - Optional - The name of the country to filter leagues by.
- **season** (integer) - Optional - The season year to filter leagues by.
- **league** (integer) - Optional - The ID of the league to retrieve.
- **type** (string) - Optional - The type of league (e.g., "League", "Cup").

### Request Example
```ruby
# Get leagues by country and season
response = @client.leagues(country: "Chile", season: 2020)

# Get all available seasons
seasons = @client.leagues_seasons
```

### Response
#### Success Response (200)
- **get** (string) - The endpoint name.
- **parameters** (object) - The parameters used for the request.
- **results** (integer) - The number of results returned.
- **response** (array) - An array of league objects, each containing:
  - **league** (object) - League details (id, name, type).
  - **country** (object) - Country details (name, code).
  - **seasons** (array) - An array of season objects.

#### Response Example (Leagues)
```json
{
  "get": "leagues",
  "parameters": {"country": "Chile", "season": "2020"},
  "results": 2,
  "response": [
    {
      "league": {"id": 265, "name": "Primera Division", "type": "League"},
      "country": {"name": "Chile", "code": "CL"},
      "seasons": [{"year": 2020, "current": true, ...}]
    }
  ]
}
```

#### Success Response (Seasons)
- **get** (string) - The endpoint name.
- **response** (array) - An array of available season years.

#### Response Example (Seasons)
```json
{
  "get": "leagues/seasons",
  "response": [2010, 2011, ..., 2024]
}
```
```

--------------------------------

### Leagues API

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

Retrieves a list of leagues. Supports filtering by country and season.

```APIDOC
## GET /leagues

### Description
Retrieves a list of football leagues. You can filter leagues by specifying the country and the season year.

### Method
GET

### Endpoint
/leagues

### Parameters
#### Query Parameters
- **country** (string) - Optional - The name or code of the country to filter leagues by.
- **season** (integer) - Optional - The season year to filter leagues by (e.g., 2020).

### Request Example
```ruby
@client.leagues(country: "Chile", season: 2020)
```

### Response
#### Success Response (200)
- **league** (object) - Contains league details like id, name, type, and logo.
- **country** (object) - Contains country details like name, code, and flag.
- **seasons** (array) - An array of season objects, each containing year, start/end dates, current status, and coverage details.

#### Response Example
```json
{
    "get": "leagues",
    "parameters": {
        "country": "Chile",
        "season": "2020"
    },
    "errors": [],
    "results": 2,
    "paging": {
        "current": 1,
        "total": 1
    },
    "response": [
        {
            "league": {
                "id": 265,
                "name": "Primera Division",
                "type": "League",
                "logo": "https://media.api-sports.io/football/leagues/265.png"
            },
            "country": {
                "name": "Chile",
                "code": "CL",
                "flag": "https://media.api-sports.io/flags/cl.svg"
            },
            "seasons": [
                {
                    "year": 2020,
                    "start": "2020-01-24",
                    "end": "2020-10-11",
                    "current": true,
                    "coverage": {
                        "fixtures": {
                            "events": true,
                            "lineups": true,
                            "statistics_fixtures": true,
                            "statistics_players": true
                        },
                        "standings": true,
                        "players": true,
                        "top_scorers": true,
                        "predictions": true,
                        "odds": true
                    }
                }
            ]
        }
    ]
}
```
```

--------------------------------

### Fetch Leagues by Country and Season - Ruby

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

Shows how to retrieve league data for a specific country and season. The method returns a JSON object with details about the leagues found.

```ruby
@client.leagues(country: "Chile", season: 2020)
```

--------------------------------

### Coaches API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves information about team coaches/managers.

```APIDOC
## Coaches API

### Description
Retrieves information about team coaches/managers.

### Method
GET

### Endpoint
`/coaches`

### Parameters
#### Query Parameters
- **id** (integer) - Optional - Coach ID.
- **team** (integer) - Optional - Team ID.
- **search** (string) - Optional - Search by coach name.

### Request Example
```ruby
# Get coach by ID
response = @client.coaches(id: 123)

# Get coaches by team
response = @client.coaches(team: 2323)

# Search coach by name
response = @client.coaches(search: "Guardiola")
```
```

--------------------------------

### Players API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves player information including statistics, top scorers, and available seasons.

```APIDOC
## Players API

Retrieves player information including statistics, top scorers, and available seasons.

### Method
`GET`

### Endpoint
`/players`

### Parameters
#### Query Parameters
- **id** (integer) - Optional - The ID of the player.
- **name** (string) - Optional - The name of the player.
- **team** (integer) - Optional - The ID of the team the player belongs to.
- **league** (integer) - Optional - The ID of the league.
- **season** (integer) - Optional - The season year.

### Request Example
```ruby
# Get player by ID
player_info = @client.players(id: 12345)

# Get top scorers for a league and season
top_scorers = @client.top_scorers(league: 265, season: 2020)

# Get available seasons for players
player_seasons = @client.player_seasons
```

### Response
#### Success Response (200)
- **get** (string) - The endpoint name.
- **parameters** (object) - The parameters used for the request.
- **results** (integer) - The number of results returned.
- **response** (array) - An array of player objects, each containing player details and statistics.

#### Response Example (Player Info)
```json
{
  "get": "players",
  "parameters": {"id": 12345},
  "results": 1,
  "response": [
    {
      "player": {"id": 12345, "name": "Player Name", ...},
      "statistics": [...] 
    }
  ]
}
```
```

--------------------------------

### Fetch Countries Data with API Football V3 Ruby Gem

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Shows how to retrieve a list of countries using the API Football V3 Ruby gem. The `countries` method can fetch all available countries or be filtered by name using the `search` option. Responses are returned as parsed JSON objects.

```ruby
# Get all countries
response = @client.countries
# => { "get" => "countries", "results" => 161, "response" => [...] }

# Search for a specific country
response = @client.countries(search: "Chile")
# => {
#      "get" => "countries",
#      "parameters" => { "search" => "Chile" },
#      "errors" => [],
#      "results" => 1,
#      "response" => [
#        {
#          "name" => "Chile",
#          "code" => "CL",
#          "flag" => "https://media.api-sports.io/flags/cl.svg"
#        }
#      ]
#    }
```

--------------------------------

### Countries API

Source: https://github.com/agomezcampero/api_football_v3/blob/master/README.md

Retrieves a list of countries. Supports filtering by search term.

```APIDOC
## GET /countries

### Description
Retrieves a list of countries available in the API. You can filter the results by providing a search query.

### Method
GET

### Endpoint
/countries

### Parameters
#### Query Parameters
- **search** (string) - Optional - A search term to filter countries by name.

### Request Example
```ruby
@client.countries(search: "Chile")
```

### Response
#### Success Response (200)
- **name** (string) - The name of the country.
- **code** (string) - The ISO code of the country.
- **flag** (string) - The URL of the country's flag.

#### Response Example
```json
{
    "get": "countries",
    "parameters": {
        "search": "Chile"
    },
    "errors": [],
    "results": 1,
    "paging": {
        "current": 1,
        "total": 1
    },
    "response": [
        {
            "name": "Chile",
            "code": "CL",
            "flag": "https://media.api-sports.io/flags/cl.svg"
        }
    ]
}
```
```

--------------------------------

### Timezones API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Returns all available timezones supported by the API for date/time conversions.

```APIDOC
## Timezones API

### Description
Returns all available timezones supported by the API for date/time conversions.

### Method
GET

### Endpoint
`/timezones`

### Request Example
```ruby
response = @client.timezones
```

### Response Example
```json
{
  "get": "timezone",
  "response": ["Africa/Abidjan", "Africa/Accra", ...]
}
```
```

--------------------------------

### Error Handling

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

The gem raises specific error classes for different HTTP status codes, enabling precise error handling in your application.

```APIDOC
## Error Handling

### Description
The gem raises specific error classes for different HTTP status codes, enabling precise error handling in your application.

### Request Example
```ruby
begin
  response = @client.teams(id: 999999)
rescue ApiFootballV3::Error::NotFound => e
  puts "Team not found: #{e.message}"
rescue ApiFootballV3::Error::TooManyRequests => e
  puts "Rate limit exceeded, please wait before retrying"
rescue ApiFootballV3::Error::Unauthorized => e
  puts "Invalid API key"
rescue ApiFootballV3::Error::BadRequest => e
  puts "Invalid request parameters: #{e.message}"
rescue ApiFootballV3::Error::ServerError => e
  puts "API server error, try again later"
rescue ApiFootballV3::Error => e
  puts "API error: #{e.message}"
end

# Available error classes:
# Client errors (4xx): BadRequest, Unauthorized, Forbidden, NotFound,
#                      NotAcceptable, RequestEntityTooLarge, UnprocessableEntity, TooManyRequests
# Server errors (5xx): InternalServerError, BadGateway, ServiceUnavailable, GatewayTimeout
```
```

--------------------------------

### Teams API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves team information and statistics. Query by team ID, name, league, season, or country.

```APIDOC
## Teams API

Retrieves team information and statistics. Query by team ID, name, league, season, or country.

### Method
`GET`

### Endpoint
`/teams`

### Parameters
#### Query Parameters
- **id** (integer) - Optional - The ID of the team to retrieve.
- **name** (string) - Optional - The name of the team to search for.
- **league** (integer) - Optional - The ID of the league the team plays in.
- **season** (integer) - Optional - The season year.
- **country** (string) - Optional - The country the team is from.

### Request Example
```ruby
# Get team by ID
response = @client.teams(id: 2323)

# Get team statistics for a specific league and season
stats = @client.team_statistics(team: 2323, league: 265, season: 2020)
```

### Response
#### Success Response (200)
- **get** (string) - The endpoint name.
- **response** (array) - An array of team objects, each containing:
  - **team** (object) - Team details (id, name, country, founded, logo).
  - **venue** (object) - Venue details (id, name, capacity).

#### Response Example
```json
{
  "get": "teams",
  "response": [
    {
      "team": {
        "id": 2323,
        "name": "Universidad de Chile",
        "country": "Chile",
        "founded": 1927,
        "logo": "https://media.api-sports.io/football/teams/2323.png"
      },
      "venue": {
        "id": 316,
        "name": "Estadio Nacional Julio Martinez Pradanos",
        "capacity": 48665
      }
    }
  ]
}
```
```

--------------------------------

### Odds API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Accesses betting odds data including bookmakers and bet types.

```APIDOC
## Odds API

### Description
Accesses betting odds data including bookmakers and bet types.

### Method
GET

### Endpoint
`/odds` or `/odds/mapping` or `/odds/bookmakers` or `/odds/bets`

### Parameters
#### Query Parameters
- **fixture** (integer) - Optional - Fixture ID for odds.
- **page** (integer) - Optional - Page number for mapping.

### Request Example
```ruby
# Get odds for a fixture
response = @client.odds(fixture: 123456)

# Get odds mapping
mapping = @client.mapping(page: 1)

# Get available bookmakers
bookmakers = @client.bookmakers

# Get bet types
bets = @client.bets
```

### Response Example (Bookmakers)
```json
{
  "get": "odds/bookmakers",
  "response": [{ "id": 1, "name": "Bet365" }, ... ]
}
```
```

--------------------------------

### Sidelined API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves injury and suspension data for players.

```APIDOC
## Sidelined API

### Description
Retrieves injury and suspension data for players.

### Method
GET

### Endpoint
`/sidelined`

### Parameters
#### Query Parameters
- **player** (integer) - Optional - Player ID.
- **coach** (integer) - Optional - Coach ID.

### Request Example
```ruby
# Get sidelined information by player
response = @client.sidelined(player: 276)

# Get sidelined information by coach
response = @client.sidelined(coach: 123)
```
```

--------------------------------

### Players API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieve player information by ID and season, or by team and season. Also includes endpoints for top scorers and available seasons.

```APIDOC
## Players API

### Description
Retrieve player information by ID and season, or by team and season. Also includes endpoints for top scorers and available seasons.

### Method
GET

### Endpoint
`/players`

### Parameters
#### Query Parameters
- **id** (integer) - Optional - Player ID.
- **team** (integer) - Optional - Team ID.
- **season** (integer) - Required - The season year (e.g., 2020).

### Request Example
```ruby
# Get player by ID and season
response = @client.players(id: 276, season: 2020)

# Get players by team and season
response = @client.players(team: 2323, season: 2020)
```

### Top Scorers

### Method
GET

### Endpoint
`/players/topscorers`

### Parameters
#### Query Parameters
- **league** (integer) - Required - League ID.
- **season** (integer) - Required - The season year (e.g., 2020).

### Request Example
```ruby
top_scorers = @client.top_scorers(league: 265, season: 2020)
```

### Response Example
```json
{
  "get": "players/topscorers",
  "response": [
    {
      "player": { "id": 123, "name": "Player Name" },
      "statistics": [{ "goals": { "total": 25 }, ... }]
    }
  ]
}
```

### Available Player Seasons

### Method
GET

### Endpoint
`/players/seasons`

### Request Example
```ruby
seasons = @client.players_seasons
```
```

--------------------------------

### Trophies API

Source: https://context7.com/agomezcampero/api_football_v3/llms.txt

Retrieves trophy/title information for players or coaches.

```APIDOC
## Trophies API

### Description
Retrieves trophy/title information for players or coaches.

### Method
GET

### Endpoint
`/trophies`

### Parameters
#### Query Parameters
- **player** (integer) - Optional - Player ID.
- **coach** (integer) - Optional - Coach ID.

### Request Example
```ruby
# Get trophies by player
response = @client.trophies(player: 276)

# Get trophies by coach
response = @client.trophies(coach: 123)
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.