README

PHP Library for Sportmonks Soccer API v3. Developed by Carsten Tetzlaff. This Library is heavily inspired by https://github.com/joesaunderson/sportmonks-soccer.

Prerequisites

PHP >= 7.3

Installation

composer require tetzilla/sportmonks-football-api

Setup

The API Client relies on Environment variables for configuration (setting API token & timezone).

Prerequisites

PHP >= 7.3

Install:

composer require symfony/dotenv

Usage:

use Symfony\Component\Dotenv\Dotenv;
$dotenv = new Dotenv();
$dotenv->load(__DIR__.'/.env');

An example .env file:

# API TOKEN (Required)
# https://docs.sportmonks.com/football/welcome/authentication
SPORTMONKS_API_TOKEN=_YOUR_API_TOKEN_HERE

# TIMEZONE (Optional)
# https://docs.sportmonks.com/football/tutorials-and-guides/tutorials/introduction/set-your-time-zone
SPORTMONKS_TIMEZONE=Europe/London

Usage

use Sportmonks\Football\FootballApi;

...

// Basic API call for all Bookmakers
$response = FootballApi::bookmakers()->getAll();

Pagination, Filtering, Sorting & Data Enrichment

The Sportmonks API allows for advanced filtering and sorting, as well as adding data via relationships. This client supports the following:

Pagination

// API call for Fixtures with page specified
$response = FootballApi::fixtures()
    ->setPage(3)
    ->getByDate('2023-03-19');

Note: The pagination ($response['pagination']) can be used to loop through pages and build a result set.

Includes

// API call for Fixtures with includes
$response = FootballApi::fixtures()
    ->setInclude(['scores', 'lineups', 'events'])
    ->getByDate('2023-03-19');

Filtering

Entity filter

// API call for Fixtures with filters
$response = FootballApi::fixtures()
    ->setInclude(['events','statistics.type'])
    ->setFilters(['eventTypes' => [18,14]])
    ->getByDate('2023-03-19');

Deleted filter

// API call for Fixtures with deleted filter
$response = FootballApi::fixtures()
    ->setFilters(['deleted'])
    ->all();

Populate filter

// API call for Fixtures with populate (1000 per page)
$response = FootballApi::fixtures()
    ->setFilters(['populate'])
    ->all();

Note: This client will not validate the usage for the correct endpoints and will not throw an error. Refer to the Sportmonks docs to see which endpoints support the above parameters.

Full Endpoint Examples

Livescores

Get all - View Sportmonks Docs

$response = FootballApi::livescores()->all();

Get all inplay - View Sportmonks Docs

$response = FootballApi::livescores()->inplay();

Get latest - View Sportmonks Docs

$response = FootballApi::livescores()->latest();

Fixtures

Get all - View Sportmonks Docs

$response = FootballApi::fixtures()->all();

Get by Id - View Sportmonks Docs

$response = FootballApi::fixtures()->getById($fixtureId);

Get by multiple ids - View Sportmonks Docs

$response = FootballApi::fixtures()->getByMultipleIds([$fixtureId1,$fixtureIds2,...]);

Get by date - View Sportmonks Docs

$response = FootballApi::fixtures()->getByDate($date);

Get by date range - View Sportmonks Docs

$response = FootballApi::fixtures()->getByDateRange($dateFrom, $dateTo);

Get by date range for team - View Sportmonks Docs

$response = FootballApi::fixtures()->getByDateRangeForTeam($dateFrom, $dateTo, $teamId);

Get by head to head - View Sportmonks Docs

$response = FootballApi::fixtures()->getHeadToHead($teamId1, $teamId2);

Get upcoming by market id - View Sportmonks Docs

$response = FootballApi::fixtures()->getUpcommingByMarketId($marketId);

Get by search by name - View Sportmonks Docs

$response = FootballApi::fixtures()->search($searchQuery);

Get last updated - View Sportmonks Docs

$response = FootballApi::fixtures()->getLastUpdated();

States

Get all states - View Sportmonks Docs

$response = FootballApi::states()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::states()->getById();

Leagues

Get all - View Sportmonks Docs

$response = FootballApi::leagues()->all();

Get by Id - View Sportmonks Docs

$response = FootballApi::leagues()->getById($leagueId);

Get by live - View Sportmonks Docs

$response = FootballApi::leagues()->live();

Get by fixture date - View Sportmonks Docs

$response = FootballApi::leagues()->getByFixtureDate($date);

Get by country id- View Sportmonks Docs

$response = FootballApi::leagues()->getByCountryId($countryId);

Get by search by name - View Sportmonks Docs

$response = FootballApi::leagues()->search($searchQuery);

Get all by team id - View Sportmonks Docs

$response = FootballApi::leagues()->getAllByTeamId($teamId);

Get current by team id - View Sportmonks Docs

$response = FootballApi::leagues()->getCurrentByTeamId($teamId);

Seasons

Get all - View Sportmonks Docs

$response = FootballApi::season()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::season()->getById($seasonId);

Get by team id - View Sportmonks Docs

$response = FootballApi::season()->getByTeamId($teamId);

Get by search by name - View Sportmonks Docs

$response = FootballApi::season()->search($searchQuery);

Schedules

Get by season id - View Sportmonks Docs

$response = FootballApi::schedules()->bySeasonId($seasonId);

Get by season id - View Sportmonks Docs

$response = FootballApi::schedules()->byTeamId($teamId);

Get by season id and team id - View Sportmonks Docs

$response = FootballApi::schedules()->bySeasonAndTeamId($seasonId, $teamId);

Stages

Get all - View Sportmonks Docs

$response = FootballApi::stages()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::stages()->getById($stageId);

Get by season id - View Sportmonks Docs

$response = FootballApi::stages()->getBySeasonId($seasonId);

Get by search by name - View Sportmonks Docs

$response = FootballApi::stages()->search($searchQuery);

Rounds

Get all - View Sportmonks Docs

$response = FootballApi::rounds()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::rounds()->getById($roundId);

Get by season id - View Sportmonks Docs

$response = FootballApi::rounds()->getBySeasonId($seasonId);

Get by search by name - View Sportmonks Docs

$response = FootballApi::rounds()->search($searchQuery);

Standings

Get all - View Sportmonks Docs

$response = FootballApi::standings()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::standings()->getBySeasonId($seasonId);

Get by round id - View Sportmonks Docs

$response = FootballApi::standings()->getByRoundId($roundId);

Get corrections by season id - View Sportmonks Docs

$response = FootballApi::standings()->getCorrectionsBySeasonId($seasonId);

Get live standings by league id - View Sportmonks Docs

$response = FootballApi::standings()->getLiveByLeagueId($leagueId);

Topscorers

Get all by season id - View Sportmonks Docs

$response = FootballApi::topscorers()->getBySeasonId($seasonId);

Get all by stage id - View Sportmonks Docs

$response = FootballApi::topscorers()->getByStageId($stageId);

Teams

Get all - View Sportmonks Docs

$response = FootballApi::teams()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::teams()->getById($teamId);

Get by country id - View Sportmonks Docs

$response = FootballApi::teams()->getByCountryId($countryId);

Get by season id - View Sportmonks Docs

$response = FootballApi::teams()->getBySeasonId($seasonId);

Get by search by name - View Sportmonks Docs

$response = FootballApi::teams()->search($searchQuery);

Team Squads

Get by team id - View Sportmonks Docs

$response = FootballApi::teamSquads()->getByTeamId($teamId);

Get by team id and season id - View Sportmonks Docs

$response = FootballApi::teamSquads()->getByTeamAndSeasonId($teamId,$seasonId);

Players

Get all - View Sportmonks Docs

$response = FootballApi::players()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::players()->getById($playerId);

Get by country id - View Sportmonks Docs

$response = FootballApi::players()->getByCountryId($countryId);

Get by search by name - View Sportmonks Docs

$response = FootballApi::players()->search($searchQuery);

Get last updated - View Sportmonks Docs

$response = FootballApi::players()->getLastUpdated();

Coaches

Get all - View Sportmonks Docs

$response = FootballApi::coaches()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::coaches()->getById($coachId);

Get by country id - View Sportmonks Docs

$response = FootballApi::coaches()->getByCountryId($countryId);

Get by search by name - View Sportmonks Docs

$response = FootballApi::coaches()->search($searchQuery);

Get last updated - View Sportmonks Docs

$response = FootballApi::coaches()->getLastUpdated();

Referees

Get all - View Sportmonks Docs

$response = FootballApi::referees()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::referees()->getById($refereeId);

Get by country id - View Sportmonks Docs

$response = FootballApi::referees()->getByCountryId($countryId);

Get by season id - View Sportmonks Docs

$response = FootballApi::referees()->getBySeasonId($countryId);

Get by search by name - View Sportmonks Docs

$response = FootballApi::referees()->search($searchQuery);

Transfers

Get all - View Sportmonks Docs

$response = FootballApi::transfers()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::transfers()->getById($transferId);

Get latest - View Sportmonks Docs

$response = FootballApi::transfers()->latest();

Get between date range - View Sportmonks Docs

$response = FootballApi::transfers()->getByDateRange($dateFrom,$dateTo);

Get by team id - View Sportmonks Docs

$response = FootballApi::transfers()->getByTeamId($teamId);

Get by player id - View Sportmonks Docs

$response = FootballApi::transfers()->getByPlayerId($playerId);

Venues

Get all - View Sportmonks Docs

$response = FootballApi::venues()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::venues()->getById($venueId);

Get by season id - View Sportmonks Docs

$response = FootballApi::venues()->getBySeasonId($seasonId);

Get by search by name - View Sportmonks Docs

$response = FootballApi::venues()->search($searchQuery);

TV Stations

Get all - View Sportmonks Docs

$response = FootballApi::tvStations()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::tvStations()->getById($stationId);

Get by fixture id - View Sportmonks Docs

$response = FootballApi::tvStations()->getByFixtureId($fixtureId);

Predictions

Get predictability - View Sportmonks Docs

$response = FootballApi::predictions()->probabilities();

Get predictability by league id - View Sportmonks Docs

$response = FootballApi::predictions()->getPredictabilityByLeagueId($leagueId);

Get predictability by fixture id - View Sportmonks Docs

$response = FootballApi::tvStations()->getPredictabilityByFixtureId($fixtureId);

Get value bets - View Sportmonks Docs

$response = FootballApi::tvStations()->valueBets();

Pre-match Odds

Get all - View Sportmonks Docs

$response = FootballApi::preMatchOdds()->all();

Get by fixture id - View Sportmonks Docs

$response = FootballApi::preMatchOdds()->getByFixtureId($fixtureId);

Get by fixture id and bookmaker id - View Sportmonks Docs

$response = FootballApi::preMatchOdds()->getByFixtureAndBookmakerId($fixtureId,$bookmakerId);

Get by fixture id and market id - View Sportmonks Docs

$response = FootballApi::preMatchOdds()->getByFixtureAndMarketId($fixtureId,$marketId);

Get last updated - View Sportmonks Docs

$response = FootballApi::preMatchOdds()->getLastUpdated();

Inplay Odds

Get all - View Sportmonks Docs

$response = FootballApi::inplayOdds()->all();

Get by fixture id - View Sportmonks Docs

$response = FootballApi::inplayOdds()->getByFixtureId($fixtureId);

Get by fixture id and bookmaker id - View Sportmonks Docs

$response = FootballApi::inplayOdds()->getByFixtureAndBookmakerId($fixtureId,$bookmakerId);

Get by fixture id and market id - View Sportmonks Docs

$response = FootballApi::inplayOdds()->getByFixtureAndMarketId($fixtureId,$marketId);

Get last updated - View Sportmonks Docs

$response = FootballApi::inplayOdds()->getLastUpdated();

Markets

Get all - View Sportmonks Docs

$response = FootballApi::markets()->all();

Get by market id - View Sportmonks Docs

$response = FootballApi::markets()->getById($marketId);

Get by search - View Sportmonks Docs

$response = FootballApi::markets()->search($searchQuery);

Bookmakers

Get all - View Sportmonks Docs

$response = FootballApi::bookmakers()->all();

Get by bookmaker id - View Sportmonks Docs

$response = FootballApi::bookmakers()->getById($bookmakerId);

Get by search - View Sportmonks Docs

$response = FootballApi::bookmakers()->search($searchQuery);

Get by market id - View Sportmonks Docs

$response = FootballApi::bookmakers()->getByFixtureId($fixtureId);

News

Get pre-match news - View Sportmonks Docs

$response = FootballApi::preMatchNews()->all();

Get by season id - View Sportmonks Docs

$response = FootballApi::preMatchNews()->getBySeasonId($seasonId);

Get pre-match news for upcoming fixtures - View Sportmonks Docs

$response = FootballApi::preMatchNews()->upcomingFixtures();

Rivals

Get all rivales - View Sportmonks Docs

$response = FootballApi::rivals()->all();

Get by team id - View Sportmonks Docs

$response = FootballApi::rivals()->getByTeamId($teamId);

Commentaries

Get all commentaries - View Sportmonks Docs

$response = FootballApi::commentaries()->all();

Get by team id - View Sportmonks Docs

$response = FootballApi::commentaries()->getByFixtureId($fixtureId);

Core Endpoints

Core contains all endpoints that are used in all sports.

Continents 🗺️

Get all continents - View Sportmonks Docs

$response = FootballApi::continents()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::continents()->getById();

Countries

Get all countries - View Sportmonks Docs

$response = FootballApi::countries()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::countries()->getById();

Get by search - View Sportmonks Docs

$response = FootballApi::countries()->search($searchQuery);

Regions

Get all regions - View Sportmonks Docs

$response = FootballApi::regions()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::regions()->getById();

Get by search - View Sportmonks Docs

$response = FootballApi::regions()->search($searchQuery);

Cities 🏙️

Get all cities - View Sportmonks Docs

$response = FootballApi::cities()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::cities()->getById();

Get by search - View Sportmonks Docs

$response = FootballApi::cities()->search($searchQuery);

Types ⌨️

Get all types - View Sportmonks Docs

$response = FootballApi::types()->all();

Get by id - View Sportmonks Docs

$response = FootballApi::types()->getById();

Get by Entity - View Sportmonks Docs

$response = FootballApi::types()->getByEntity();

Filters ⚙️

Get all entity - View Sportmonks Docs

$response = FootballApi::filters()->entity();

My Sportmonks

Retrieve information about your subscription.

Get my enrichments - View Sportmonks Docs

$response = FootballApi::my()->enrichments();

Get my resources - View Sportmonks Docs

$response = FootballApi::my()->resources();

Get my leagues - View Sportmonks Docs

$response = FootballApi::my()->leagues();

License

MIT