Skip to main content
Version: 2.0.0

Schedule & Event API Documentation

Description

This endpoint returns all the sports team & event information for previous and upcoming games & matches: lineups, venue, location, TV channel, weather & more.

REQUIREMENT

You'll need a license key to use OpticOdds' API. You can get one by contacting us at www.opticodds.com.

API Endpoint

https://api.opticodds.com/api/v2/schedules/list

Parameters

key (required)

Your OpticOdds API license key.

sport

NOTE

You can pass in multiple of this parameter.

The sport you want to receive schedule data for. We support the following:

  • football
  • basketball
  • baseball
  • mma
  • boxing
  • hockey
  • soccer
  • tennis
  • golf
  • motorsports
  • esports
  • wrestling
  • aussie-rules
  • rugby
  • lacrosse
  • cricket
  • volleyball
  • politics

league

NOTE

You can pass in multiple of this parameter.

The league you want to receive schedule data for (e.g. NBA)

division

NOTE

You can pass in multiple of this parameter.

Filter by division.

conference

NOTE

You can pass in multiple of this parameter.

Filter by conference.

team_id

Filter by the team_id you are interested in. Note that you can only provide a single team_id per request.

start_date_before

Specify this value if you want to receive all games before a specific date. Please pass in an ISO 8601 date for the best results.

start_date_after

Specify this value if you want to receive all games after a specific date. Please pass in an ISO 8601 date for the best results.

game_date

Specify this value if you want to receive all games on a specific date. Needs to be in the following format: YYYY-MM-DD.

include_starting_lineups

Set to true to include home_starting_lineups and away_starting_lineups.

include_records

Set to true to include home_record and away_record.

season_week

Filter by the season week.

season_year

Filter by the season year.

season_type

Filter by the season type.

include_team_ids

Setting this parameter to true will return home_team_id and away_team_id as part of the response. Note that this is off by default for backwards compatibility reasons.

page

The page number of the request.

include_statsperform_ids

Specify this parameter if you want the StatsPerform IDs to be included as part of the response.

Example Response

{
"data": [
{
"id": "8E19EE5495CD",
"sport": "Basketball",
"league": "NBA",
"start_date": "2022-03-08T03:30:00Z",
"season_type": "Regular",
"season_year": "2021-2022",
"season_week": null,
"away_team_abb": "NY",
"away_team_city": "New York",
"away_team_name": "Knicks",
"away_team": "New York Knicks",
"home_team_abb": "SAC",
"home_team_city": "Sacramento",
"home_team_name": "Kings",
"home_team": "Sacramento Kings",
"description": "New York Knicks vs Sacramento Kings",
"venue_name": "Golden 1 Center",
"venue_location": "Sacramento, CA",
"away_starter": null,
"home_starter": null,
"is_live": false,
"status": "Unplayed",
"checked_date": "2022-03-08T02:37:29Z",
"game_id": "40294-31342-2022-03-07",
"broadcast": "ESPN+",
"weather": null,
"weather_temp": null,
"last_play": "End of 1st period",
"clock": "0:00",
"period": "1"
},
{
"id": "28F01DE09A56",
"sport": "Basketball",
"league": "NBA",
"start_date": "2022-03-09T00:00:00Z",
"season_type": "Regular",
"season_year": "2021-2022",
"season_week": null,
"away_team_abb": "BKN",
"away_team_city": "Brooklyn",
"away_team_name": "Nets",
"away_team": "Brooklyn Nets",
"home_team_abb": "CHA",
"home_team_city": "Charlotte",
"home_team_name": "Hornets",
"home_team": "Charlotte Hornets",
"description": "Brooklyn Nets vs Charlotte Hornets",
"venue_name": "Spectrum Center",
"venue_location": "Charlotte, NC",
"away_starter": null,
"home_starter": null,
"is_live": false,
"status": "Unplayed",
"checked_date": "2022-03-08T02:37:29Z",
"game_id": "33152-35142-2022-03-08",
"broadcast": "ESPN+",
"weather": null,
"weather_temp": null,
"last_play": "End of 1st period",
"clock": "0:00",
"period": "1"
},
{
"id": "0D1CD879B1A8",
"sport": "Basketball",
"league": "NBA",
"start_date": "2022-03-09T00:00:00Z",
"season_type": "Regular",
"season_year": "2021-2022",
"season_week": null,
"away_team_abb": "CLE",
"away_team_city": "Cleveland",
"away_team_name": "Cavaliers",
"away_team": "Cleveland Cavaliers",
"home_team_abb": "IND",
"home_team_city": "Indiana",
"home_team_name": "Pacers",
"home_team": "Indiana Pacers",
"description": "Cleveland Cavaliers vs Indiana Pacers",
"venue_name": "Gainbridge Fieldhouse",
"venue_location": "Indianapolis, IN",
"away_starter": null,
"home_starter": null,
"is_live": false,
"status": "Unplayed",
"checked_date": "2022-03-08T02:37:29Z",
"game_id": "11464-32825-2022-03-08",
"broadcast": "ESPN+",
"weather": null,
"weather_temp": null,
"last_play": "End of 1st period",
"clock": "0:00",
"period": "1"
},
...
],
"page": 1,
"total_pages": 4
}

Example Response with include_starting_lineups

{
{
"id": "372AB4F5B4B6",
"start_date": "2023-08-11T18:40:00-04:00",
"season_type": "Regular",
"season_year": "2023",
"season_week": null,
"away_team_abb": "CLE",
"away_team_city": "Cleveland",
"away_team_name": "Guardians",
"away_team": "Cleveland Guardians",
"home_team_abb": "TB",
"home_team_city": "Tampa Bay",
"home_team_name": "Rays",
"home_team": "Tampa Bay Rays",
"description": "Cleveland Guardians vs Tampa Bay Rays",
"venue_name": "Tropicana Field",
"venue_location": "St. Petersburg, Florida",
"away_starter": "Xzavion Curry",
"home_starter": "Aaron Civale",
"is_live": false,
"status": "Unplayed",
"checked_date": "2023-08-11T15:46:36-04:00",
"game_id": "81005-32800-2023-08-11-15",
"sport": "baseball",
"league": "MLB",
"home_starting_lineups": [
{
"player_id": "BFE430B567C5",
"player_name": "Aaron Civale",
"player_team": "Tampa Bay Rays",
"player_position": "P",
"player_batting_throwing": "R"
},
{
"player_id": "3C49F4B7013A",
"player_name": "Yandy Diaz",
"player_team": "Tampa Bay Rays",
"player_position": "1B",
"player_batting_throwing": "R"
},
{
"player_id": "8B8E6BD55EBA",
"player_name": "Wander Franco",
"player_team": "Tampa Bay Rays",
"player_position": "SS",
"player_batting_throwing": "S"
},
{
"player_id": "4DD6693C6C83",
"player_name": "Brandon Lowe",
"player_team": "Tampa Bay Rays",
"player_position": "2B",
"player_batting_throwing": "L"
},
{
"player_id": "328C68E577E6",
"player_name": "Randy Arozarena",
"player_team": "Tampa Bay Rays",
"player_position": "LF",
"player_batting_throwing": "R"
},
{
"player_id": "CABCC3C42356",
"player_name": "Isaac Paredes",
"player_team": "Tampa Bay Rays",
"player_position": "3B",
"player_batting_throwing": "R"
},
{
"player_id": "CDD29844A85A",
"player_name": "Luke Raley",
"player_team": "Tampa Bay Rays",
"player_position": "DH",
"player_batting_throwing": "L"
},
{
"player_id": "67C877519A5D",
"player_name": "Jose Siri",
"player_team": "Tampa Bay Rays",
"player_position": "CF",
"player_batting_throwing": "R"
},
{
"player_id": "ED7BAEC99955",
"player_name": "Josh Lowe",
"player_team": "Tampa Bay Rays",
"player_position": "RF",
"player_batting_throwing": "L"
},
{
"player_id": "89F837F2C660",
"player_name": "Christian Bethancourt",
"player_team": "Tampa Bay Rays",
"player_position": "C",
"player_batting_throwing": "R"
}
],
"away_starting_lineups": [
{
"player_id": "04B05129C485",
"player_name": "Xzavion Curry",
"player_team": "Cleveland Guardians",
"player_position": "P",
"player_batting_throwing": "R"
},
{
"player_id": "14FF0F8E6FBA",
"player_name": "Steven Kwan",
"player_team": "Cleveland Guardians",
"player_position": "LF",
"player_batting_throwing": "L"
},
{
"player_id": "34EBEED3E1B7",
"player_name": "Andres Gimenez",
"player_team": "Cleveland Guardians",
"player_position": "2B",
"player_batting_throwing": "L"
},
{
"player_id": "930A0E824F31",
"player_name": "Jose Ramirez",
"player_team": "Cleveland Guardians",
"player_position": "3B",
"player_batting_throwing": "S"
},
{
"player_id": "B70CC6180FF6",
"player_name": "Oscar Gonzalez",
"player_team": "Cleveland Guardians",
"player_position": "DH",
"player_batting_throwing": "R"
},
{
"player_id": "01C5BF4B8F6C",
"player_name": "Will Brennan",
"player_team": "Cleveland Guardians",
"player_position": "RF",
"player_batting_throwing": "L"
},
{
"player_id": "A8BE20BAE957",
"player_name": "Gabriel Arias",
"player_team": "Cleveland Guardians",
"player_position": "1B",
"player_batting_throwing": "R"
},
{
"player_id": "D7342B867C90",
"player_name": "Brayan Rocchio",
"player_team": "Cleveland Guardians",
"player_position": "SS",
"player_batting_throwing": "S"
},
{
"player_id": "113841DC8EC3",
"player_name": "Bo Naylor",
"player_team": "Cleveland Guardians",
"player_position": "C",
"player_batting_throwing": "L"
},
{
"player_id": "58D217C9F333",
"player_name": "Myles Straw",
"player_team": "Cleveland Guardians",
"player_position": "CF",
"player_batting_throwing": "R"
}
],
"broadcast": "ESPN+",
"weather": "Mostly sunny",
"weather_temp": "92",
"last_play": null,
"clock": null,
"period": null
},
},
...
}

API Endpoint (deprecated)

DEPRECATED

Deprecated endpoint

https://api.opticodds.com/api/v2/schedules