README

With this package, you're allowed to use all Sportmonks APIs in a single project.

Sportmonks::football()
Sportmonks::core()
Sportmonks::my()
Sportmonks::odds()
Sportmonks::cricket()
Sportmonks::f1()

Installation

Require the package via composer

composer require fpicosm/sportmonks

Update your .env file adding the variables:

SPORTMONKS_TOKEN=# YOUR_API_TOKEN (required)
SPORTMONKS_TIMEZONE=# Optional. A valid timezone from /v3/core/timezones endpoint (UTC by default)
SPORTMONKS_PER_PAGE=# Optional. Default page size in paginated responses (50 by default)

Publish the config file

php artisan vendor:publish --provider="Sportmonks\SportmonksServiceProvider"

APIs 3.0

Basic usage

The `setInclude` option

This option allows to enrich your responses by including related resources in the request, passing them as an array of strings, or a semicolon-separated string:

Sportmonks::football()
    ->leagues()
    ->setInclude('country', 'sport')
    ->find(8);

Sportmonks::football()
    ->leagues()
    ->setInclude('country;sport')
    ->find(8);

or an array too

Sportmonks::football()
    ->leagues()
    ->setInclude(['country', 'sport'])
    ->find(8);

Produces the response:

{
    "data": {
        "id": 8,
        "sport_id": 1,
        "country_id": 462,
        "name": "Premier League",
        "active": true,
        "short_code": "UK PL",
        "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/8/8.png",
        "type": "league",
        "sub_type": "domestic",
        "last_played_at": "2025-03-10 20:00:00",
        "category": 1,
        "has_jerseys": false,
        "country": {
            "id": 462,
            "continent_id": 1,
            "name": "England",
            "official_name": "England",
            "fifa_name": "ENG",
            "iso2": "EN",
            "iso3": "ENG",
            "latitude": "54.56088638305664",
            "longitude": "-2.2125117778778076",
            "borders": [
                "IRL"
            ],
            "image_path": "https://cdn.sportmonks.com/images/countries/png/short/en.png"
        },
        "sport": {
            "id": 1,
            "name": "Football",
            "code": "football"
        }
    }
}

You can also get nested relations by using dot notation:

Sportmonks::football()
    ->leagues()
    ->setInclude('country.continent', 'sport')
    ->find(8);

{
    "data": {
        "id": 8,
        "sport_id": 1,
        "country_id": 462,
        "name": "Premier League",
        "active": true,
        "short_code": "UK PL",
        "image_path": "https://cdn.sportmonks.com/images/soccer/leagues/8/8.png",
        "type": "league",
        "sub_type": "domestic",
        "last_played_at": "2025-03-10 20:00:00",
        "category": 1,
        "has_jerseys": false,
        "country": {
            "id": 462,
            "continent_id": 1,
            "name": "England",
            "official_name": "England",
            "fifa_name": "ENG",
            "iso2": "EN",
            "iso3": "ENG",
            "latitude": "54.56088638305664",
            "longitude": "-2.2125117778778076",
            "borders": [
                "IRL"
            ],
            "image_path": "https://cdn.sportmonks.com/images/countries/png/short/en.png",
            "continent": {
                "id": 1,
                "name": "Europe",
                "code": "EU"
            }
        },
        "sport": {
            "id": 1,
            "name": "Football",
            "code": "football"
        }
    }
}

The `setSelect` option

This option allows you to reduce the speed and response size, getting only the specified fields on the given entities, passing an array of strings or a comma separated string (fields that have relations are always included).

Sportmonks::football()
    ->leagues()
    ->setSelect('name', 'short_code')
    ->find(8);

Produces the response:

{
    "data": {
        "name": "Premier League",
        "short_code": "UK PL",
        "id": 8,
        "sport_id": 1,
        "country_id": 462
    }
}

You can combine both setSelect and setInclude options. If you want to select specified fields within relations, you should use the relation:field,another_field,... notation:

Sportmonks::football()
    ->leagues()
    ->setInclude('country:name,iso2', 'country.continent:name', 'sport:code')
    ->select('name')
    ->find(8);

{
    "data": {
        "name": "Premier League",
        "id": 8,
        "sport_id": 1,
        "country_id": 462,
        "country": {
            "id": 462,
            "continent_id": 1,
            "name": "England",
            "iso2": "EN",
            "continent": {
                "id": 1,
                "name": "Europe"
            }
        },
        "sport": {
            "id": 1,
            "code": "football"
        }
    }
}

If you need extra info, you can check the documentation

The `setFilters` option

This option allows you to filters the results. If you don't know how to use filters in Sportmonks, please see the tutorial.

You can use both static/dynamic filters:

Sportmonks::football()
    ->fixtures()
    ->setFilters([
        'fixtureLeagues' => [564, 8],
        'todayDate',
        'participantSearch' => 'barcelona'
    ])
    ->all();

The `sortBy` option

By default, all endpoints return the results ordered by id, in ascending direction. With this option, you can sort the results by the given field, and the given order:

Sportmonks::football()
    ->leagues()
    ->sortBy('name') # ascending by default
    ->all();

Sportmonks::football()
    ->leagues()
    ->sortBy('name', 'desc')
    ->all();

The `getPage` option

Some endpoints return paginated responses. With this option, you can set the page number and the number of items you want to get:

Sportmonks::core()
    ->countries()
    ->getPage(2) # by default, the value in env('SPORTMONKS_PER_PAGE'), or 50 if not given
    ->all()

Sportmonks::core()
    ->countries()
    ->getPage(2, 20) # get only 20 items per page
    ->all()

There's also an optional third argument orderBy to say if you want the results ordered by id asc (by default) or desc.

Sportmonks::core()
    ->countries()
    ->getPage(2, 20, 'desc') # get the second page, 20 items per page, starting from the end
    ->all();

You can combine both sortBy and getPage options. In this case, the third argument in the getPage does not have any effect, as you are sorting the results by the given field:

Sportmonks::core()
    ->countries()
    ->getPage(2, 10, 'desc') // this `desc` has no effect
    ->sortBy('name', 'asc') 
    ->all();

Endpoints

Core API

Cities

// get all cities
Sportmonks::core()->cities()->all();

// get city by id
Sportmonks::core()->cities()->find($cityId);

// get cities by search
Sportmonks::core()->cities()->search($name);

Continents

// get all continents
Sportmonks::core()->continents()->all();

// get continent by id
Sportmonks::core()->continents()->find($countryId);

Countries

// get all countries
Sportmonks::core()->countries()->all();

// get country by id
Sportmonks::core()->countries()->find($countryId);

// get countries by search
Sportmonks::core()->countries()->search($name);

Regions

// get all regions
Sportmonks::core()->regions()->all();

// get region by id
Sportmonks::core()->regions()->find($regionId);

// get regions by search
Sportmonks::core()->regions()->search($name);

Timezones

// get all supported timezones
Sportmonks::core()->timezones()->all();

Types

// get all types
Sportmonks::core()->types()->all();

// get type by id
Sportmonks::core()->types()->find($typeId);

// get types by entity
Sportmonks::core()->types()->byEntities();

Football API

Coaches

// get all coaches
Sportmonks::football()->coaches()->all();

// get coach by id
Sportmonks::football()->coaches()->find($coachId);

// get coaches by country id
Sportmonks::football()->coaches()->byCountry($countryId);

// get coaches by search by name
Sportmonks::football()->coaches()->search($name);

// get last updated coaches
Sportmonks::football()->coaches()->lastUpdated();

Commentaries

// get all commentaries
Sportmonks::football()->commentaries()->all();

// get commentaries by fixture id
Sportmonks::football()->commentaries()->byFixture($fixtureId);

Expected (xG)

// get expected by team
Sportmonks::football()->expected()->byTeam();

// get expected by player 
Sportmonks::football()->expected()->byPlayer();

Fixtures

// get all fixtures
Sportmonks::football()->fixtures()->all();

// get fixture by id
Sportmonks::football()->fixtures()->find($fixtureId);

// get fixtures by multiple ids
Sportmonks::football()->fixtures()->multiple($fixtureIds);

// get fixtures by date
Sportmonks::football()->fixtures()->byDate($date);

// get fixtures by date range
Sportmonks::football()->fixtures()->byDateRange($from, $to);

// get fixtures by date range for team
Sportmonks::football()->fixtures()->byDateRangeForTeam($from, $to, $teamId);

// get fixtures by head to head
Sportmonks::football()->fixtures()->h2h($teamId, $rivalId);

// get fixtures by search by name
Sportmonks::football()->fixtures()->search($name);

// get upcoming fixtures by market id
Sportmonks::football()->fixtures()->upcomingByMarket($marketId);

// get upcoming fixtures by tv station id
Sportmonks::football()->fixtures()->upcomingByTvStation($tvStationId);

// get past fixtures by tv station id
Sportmonks::football()->fixtures()->pastByTvStation($tvStationId);

// get latest updated fixtures
Sportmonks::football()->fixtures()->lastUpdated();

Leagues

// get all leagues
Sportmonks::football()->leagues()->all();

// get league by id
Sportmonks::football()->leagues()->find($leagueId);

// get leagues by live
Sportmonks::football()->leagues()->live();

// get leagues by fixture date
Sportmonks::football()->leagues()->byFixtureDate($date);

// get leagues by country id
Sportmonks::football()->leagues()->byCountry($countryId);

// get leagues search by name
Sportmonks::football()->leagues()->search($name);

// get all leagues by team id
Sportmonks::football()->leagues()->allByTeam($teamId);

// get current leagues by team id
Sportmonks::football()->leagues()->currentByTeam($teamId);

Livescores

// get inplay livescores
Sportmonks::football()->livescores()->inplay();

// get all livescores
Sportmonks::football()->livescores()->all();

// get latest updated livescores
Sportmonks::football()->livescores()->lastUpdated();

News

// get pre-match news
Sportmonks::football()->news()->preMatch()->all();

// get pre-match news by season id
Sportmonks::football()->news()->preMatch()->bySeason($seasonId);

// get pre-match news for upcoming fixtures
Sportmonks::football()->news()->preMatch()->upcoming();

// get post-match news
Sportmonks::football()->news()->postMatch();

// get post-match news by season id
Sportmonks::football()->news()->postMatch()->bySeason($seasonId);

Players

// get all players
Sportmonks::football()->players()->all();

// get player by id
Sportmonks::football()->players()->find($playerId);

// get players by country id
Sportmonks::football()->players()->byCountry($countryId);

// get players by search by name
Sportmonks::football()->players()->search($name);

// get last updated players
Sportmonks::football()->players()->lastUpdated();

Predictions

// get probabilities
Sportmonks::football()->predictions()->all();

// get predictability by league id
Sportmonks::football()->predictions()->byLeague($leagueId);

// get probabilities by fixture id
Sportmonks::football()->predictions()->byFixture($fixtureId);

// get value bets
Sportmonks::football()->predictions()->valueBets()->all();

// get value bets by fixture id
Sportmonks::football()->predictions()->valueBets()->byFixture($fixtureId);

Referees

// get all referees
Sportmonks::football()->referees()->all();

// get referee by id
Sportmonks::football()->referees()->find($refereeId);

// get referees by country id
Sportmonks::football()->referees()->byCountry($countryId);

// get referees by season id
Sportmonks::football()->referees()->bySeason($seasonId);

// get referees by search by name
Sportmonks::football()->referees()->search($name);

Rivals

// get all rivals
Sportmonks::football()->rivals()->all();

// get rivals by team id
Sportmonks::football()->rivals()->byTeam($teamId);

Rounds

// get all rounds
Sportmonks::football()->rounds()->all();

// get round by id
Sportmonks::football()->rounds()->find($roundId);

// get rounds by season id
Sportmonks::football()->rounds()->bySeason($seasonId);

// get rounds by search by name
Sportmonks::football()->rounds()->search($name);

Schedules

// get schedules by season id
Sportmonks::football()->schedules()->bySeason($seasonId);

// get schedules by team id
Sportmonks::football()->schedules()->byTeam($teamId);

// get schedules by season id and team id
Sportmonks::football()->schedules()->bySeasonAndTeam($seasonId, $teamId);

Seasons

// get all seasons
Sportmonks::football()->seasons()->all();

// get season by id
Sportmonks::football()->seasons()->find($seasonId);

// get seasons by team id
Sportmonks::football()->seasons()->byTeam($teamId);

// get seasons by search by name
Sportmonks::football()->seasons()->search($name);

Squads

// get squad by team id
Sportmonks::football()->squads()->currentByTeam($teamId);

// get extended squad by team id
Sportmonks::football()->squads()->extendedByTeam($teamId);

// get squad by team and season id
Sportmonks::football()->squads()->bySeasonAndTeam($seasonId, $teamId);

Stages

// get all stages
Sportmonks::football()->stages()->all();

// get stage by id
Sportmonks::football()->stages()->find($stageId);

// get stages by season id
Sportmonks::football()->stages()->bySeason($seasonId);

// get stages by search by name
Sportmonks::football()->stages()->search($name);

Standings

// get all standings
Sportmonks::football()->standings()->all();

// get standings by season id
Sportmonks::football()->standings()->bySeason($seasonId);

// get standing correction by season id
Sportmonks::football()->standings()->correctionBySeason($seasonId);

// get standings by round id
Sportmonks::football()->standings()->byRound($roundId);

// get live standings by league id
Sportmonks::football()->standings()->liveByLeague($leagueId);

States

// get all states
Sportmonks::football()->states()->all();

// get state by id
Sportmonks::football()->states()->find($stateId);

Statistics

// get season statistics by participant
Sportmonks::football()->statistics()->byPlayer($playerId);
Sportmonks::football()->statistics()->byTeam($teamId);
Sportmonks::football()->statistics()->byCoach($coachId);
Sportmonks::football()->statistics()->byReferee($refereeId);

// get stage statistics by id
Sportmonks::football()->statistics()->byStage($stageId);

// get round statistics by id
Sportmonks::football()->statistics()->byRound($roundId);

Teams

// get all teams
Sportmonks::football()->teams()->all();

// get team by id
Sportmonks::football()->teams()->find($teamId);

// get teams by country id
Sportmonks::football()->teams()->byCountry($countryId);

// get teams by season id
Sportmonks::football()->teams()->bySeason($seasonId);

// get teams by search by name
Sportmonks::football()->teams()->search($name);

Top Scorers

// get top scorers by season id
Sportmonks::football()->topScorers()->bySeason($seasonId);

// get top scorers by stage id
Sportmonks::football()->topScorers()->byStage($stageId);

Transfers

// get all transfers
Sportmonks::football()->transfers()->all();

// get transfer by id
Sportmonks::football()->transfers()->find($transferId);

// get latest transfers
Sportmonks::football()->transfers()->latest();

// get transfers between date range
Sportmonks::football()->transfers()->byDateRange($from, $to);

// get transfers by team id
Sportmonks::football()->transfers()->byTeam($teamId);

// get transfers by player id
Sportmonks::football()->transfers()->byPlayer($playerId);

Tv Stations

// get all tv stations
Sportmonks::football()->tvStations()->all();

// get tv station by id
Sportmonks::football()->tvStations()->find($tvStationId);

// get tv stations by fixture id
Sportmonks::football()->tvStations()->byFixture($fixtureId);

Venues

// get all venues
Sportmonks::football()->venues()->all();

// get venue by id
Sportmonks::football()->venues()->find($venueId);

// get venues by season id
Sportmonks::football()->venues()->bySeason($seasonId);

// get venues by search by name 
Sportmonks::football()->venues()->search($name);

Odds API

Bookmakers

// get all bookmakers
Sportmonks::odds()->bookmakers()->all();

// get premium bookmakers
Sportmonks::odds()->bookmakers()->premium();

// get bookmaker by id
Sportmonks::odds()->bookmakers()->find($bookmakerId);

// get bookmakers by search
Sportmonks::odds()->bookmakers()->search($name);

// get bookmakers by fixture id
Sportmonks::odds()->bookmakers()->byFixture($fixtureId);

// get bookmaker event id's by fixture id
Sportmonks::odds()->bookmakers()->eventsByFixture($fixtureId);

Markets

// get all markets
Sportmonks::odds()->markets()->all();

// get premium markets
Sportmonks::odds()->markets()->premium();

// get market by id
Sportmonks::odds()->markets()->find($marketId);

// get markets by search
Sportmonks::odds()->markets()->search($name);

My Api

// get all entity filters
Sportmonks::my()->filters();

// get my enrichments
Sportmonks::my()->enrichments();

// get my resources
Sportmonks::my()->resources();

// get my leagues
Sportmonks::my()->leagues();

// get my usage
Sportmonks::my()->usage();

Cricket API

Basic usage

The `setInclude` option

Sportmonks::cricket()
    ->leagues()
    ->setInclude('seasons', 'country')
    ->all();

Sportmonks::cricket()
    ->leagues()
    ->setInclude(['seasons', 'country'])
    ->all();

Sportmonks::cricket()
    ->leagues()
    ->setInclude('seasons,country')
    ->all();

The `setFields` option

Sportmonks::cricket()
    ->leagues()
    ->setFields('name', 'code')
    ->all();

Sportmonks::cricket()
    ->leagues()
    ->setFields(['name', 'code'])
    ->all();

Sportmonks::cricket()
    ->leagues()
    ->setFields('name,code')
    ->all();

The `setFilters` option

Sportmonks::cricket()
    ->countries()
    ->setFilters(['continent_id' => 1])
    ->all();

Sportmonks::cricket()
    ->countries()
    ->setFilters(['continent_id' => 1, 'name' => 'Spain'])
    ->all();

The `sortBy` option

Sportmonks::cricket()
    ->countries()
    ->sortBy('name')
    ->all();

Sportmonks::cricket()
    ->countries()
    ->sortBy('continent_id', 'name')
    ->all();

Sportmonks::cricket()
    ->countries()
    ->sortBy(['continent_id', 'name'])
    ->all();

Sportmonks::cricket()
    ->countries()
    ->sortBy('continent_id,name')
    ->all();

Endpoints

Continents

// get all continents
Sportmonks::cricket()->continents()->all();

// get continent by id
Sportmonks::cricket()->continents()->all();

Countries

// get all 
Sportmonks::cricket()->countries()->all();

// get by id 
Sportmonks::cricket()->countries()->find($countryId);

Leagues

// get all 
Sportmonks::cricket()->leagues()->all();

// get by id 
Sportmonks::cricket()->leagues()->find($leagueId);

Seasons

// get all 
Sportmonks::cricket()->seasons()->all();

// get by id 
Sportmonks::cricket()->seasons()->find($seasonId);

Fixtures

// get all 
Sportmonks::cricket()->fixtures()->all();

// get by id 
Sportmonks::cricket()->fixtures()->find($fixtureId);

Livescores

// get all 
Sportmonks::cricket()->livescores()->all();

Teams

// get all 
Sportmonks::cricket()->teams()->all();

// get by id 
Sportmonks::cricket()->teams()->find($teamId);

// get squad by team and season id
Sportmonks::cricket()->teams()->squadBySeason($teamId, $seasonId);

Players

// get all 
Sportmonks::cricket()->players()->all();

// get by id 
Sportmonks::cricket()->players()->find($playerId);

Officials

// get all 
Sportmonks::cricket()->officials()->all();

// get by id 
Sportmonks::cricket()->officials()->find($officialId);

Venues

// get all 
Sportmonks::cricket()->venues()->all();

// get by id 
Sportmonks::cricket()->venues()->find($venueId);

Positions

// get all 
Sportmonks::cricket()->positions()->all();

// get by id 
Sportmonks::cricket()->positions()->find($positionId);

Stages

// get all 
Sportmonks::cricket()->stages()->all();

// get by id 
Sportmonks::cricket()->stages()->find($stageId);

Team Rankings

// get all
Sportmonks::cricket()->teamRankings()->global();

Standings

// get standings by season id
Sportmonks::cricket()->standings()->bySeason();

// get standings by stage id 
Sportmonks::cricket()->standings()->byStage();

Scores

// get all scores
Sportmonks::cricket()->scores()->all();

// get by id 
Sportmonks::cricket()->scores()->find($scoreId);

Formula One API

Basic usage

The `setInclude` option

Sportmonks::f1()
    ->tracks()
    ->setInclude('seasons', 'currentStage')
    ->all();

Sportmonks::f1()
    ->tracks()
    ->setInclude(['seasons', 'currentStage'])
    ->all();

Sportmonks::f1()
    ->tracks()
    ->setInclude('seasons,currentStage')
    ->all();

The `setFilters` option

Sportmonks::f1()
    ->seasons()
    ->setFilters(['name' => 2022])
    ->all();

The `sortBy` option

Sportmonks::f1()
    ->seasons()
    ->sortBy('name')
    ->all();

Endpoints

Livescores

// get livescores
Sportmonks::f1()->livescores()->all();

Seasons

// get all seasons
Sportmonks::f1()->seasons()->all();

// get season by id
Sportmonks::f1()->seasons()->find($seasonId);

Tracks

// get all tracks
Sportmonks::f1()->tracks()->all();

// get track by id
Sportmonks::f1()->tracks()->find($trackId);

// get tracks by season id
Sportmonks::f1()->tracks()->bySeason($seasonId);

// get track winners by season id
Sportmonks::f1()->tracks()->winnersBySeason($seasonId);

Stages

// get all stages
Sportmonks::f1()->stages()->all();

// get stage by id
Sportmonks::f1()->stages()->find($stageId);

// get stages by season id
Sportmonks::f1()->stages()->bySeason($seasonId);

Teams

// get team by id
Sportmonks::f1()->teams()->find($teamId);

// get teams by season id
Sportmonks::f1()->teams()->bySeason($seasonId);

// get team results by season id
Sportmonks::f1()->teams()->resultsBySeason($teamId, $seasonId);

Drivers

// get driver by id
Sportmonks::f1()->drivers()->find($driverId);

// get drivers by season id
Sportmonks::f1()->drivers()->bySeason($seasonId);

// get driver results by season id
Sportmonks::f1()->drivers()->resultsBySeason($driverId, $seasonId);

fpicosm / sportmonks

Maintainers

Details

README

Installation

APIs 3.0

Basic usage

The setInclude option

The setSelect option

The setFilters option

The sortBy option

The getPage option

Endpoints

Core API

Cities

Continents

Countries

Regions

Timezones

Types

Football API

Coaches

Commentaries

Expected (xG)

Fixtures

Leagues

Livescores

News

Players

Predictions

Referees

Rivals

Rounds

Schedules

Seasons

Squads

Stages

Standings

States

Statistics

Teams

Top Scorers

Transfers

Tv Stations

Venues

Odds API

Bookmakers

Markets

My Api

Cricket API

Basic usage

The setInclude option

The setFields option

The setFilters option

The sortBy option

Endpoints

Continents

Countries

Leagues

Seasons

Fixtures

Livescores

Teams

Players

Officials

Venues

Positions

Stages

Team Rankings

Standings

Scores

Formula One API

Basic usage

The setInclude option

The setFilters option

The sortBy option

Endpoints

Livescores

Seasons

Tracks

The `setInclude` option

The `setSelect` option

The `setFilters` option

The `sortBy` option

The `getPage` option

The `setInclude` option

The `setFields` option

The `setFilters` option

The `sortBy` option

The `setInclude` option

The `setFilters` option

The `sortBy` option