Games Endpoint

Retrieve game schedules and core metadata for supported leagues.

GET

/api/v1/nba/odds/games

Description

Returns games for a specific date or date range, including team matchups, start times, and status. Use this as the foundation for building game lists, slates, and schedules.

Parameters

Name	Type	Required	Description
`date`	string (YYYY-MM-DD)	Optional	Get games for a single day.
`start_date`	string (YYYY-MM-DD)	Optional	Inclusive start date for a range query.
`end_date`	string (YYYY-MM-DD)	Optional	Inclusive end date for a range query.
`league_id`	integer	Optional	Filter games by league.

Example Request

curl -X GET "https://odds-marketplace.onrender.com/api/v1/nba/odds/games?date=2024-01-15&league_id=1" \
  -H "Authorization: Bearer sk_your_api_key_here"

Response

Returns a paginated list of normalized game objects. Each game bundles core matchup info, teams, optional boxscore, and normalized betting markets.

Top-level fields

success — boolean indicating whether the request was successful.
data — array of game objects.
count — number of games in data.
pagination — pagination metadata:
- limit — max records per page (matches your request).
- offset — zero-based index of the first record in this page.
- total — total games matching your filters.
- has_more — whether more pages are available.

Game object

Each entry in data has the following shape (fields may be null if unavailable):

Identifiers: game_id, league_id, core_id.
Status: status, real_status, status_display, start_time (ISO string).
Teams: away_team_id, home_team_id, winning_team_id, away_team, home_team, teams (full team objects with IDs, names, abbreviations, colors, conference/division, optional standings).
Game details: league_name, type, season, week, attendance, coverage, is_free, trending, rotation numbers, num_bets.
boxscore — live/game result info (clock, period, per-period scoring, total points, split first/second half totals) when available.
broadcast — network/internet info if defined.
markets — normalized betting markets:
- spread, moneyline, total — each with outcomes (normalized odds, team/side, period, availability), best_odds, consensus, count, and available_count.
- core_bet_types — normalized core team-score markets where available.
meta — additional metadata from the source feed.
updated_at — ISO timestamp when the normalized snapshot was generated.

Example Response

{
  "success": true,
  "data": [
    {
      "game_id": 401123456,
      "league_id": 1,
      "core_id": "nba-2024-01-15-lal-den",
      "status": "scheduled",
      "real_status": "scheduled",
      "status_display": "Scheduled",
      "start_time": "2024-01-15T03:00:00.000Z",
      "away_team_id": 14,
      "home_team_id": 21,
      "winning_team_id": null,
      "away_team": {
        "id": 14,
        "full_name": "Los Angeles Lakers",
        "short_name": "Lakers",
        "abbr": "LAL",
        "logo": "https://cdn.example.com/logos/lal.png"
      },
      "home_team": {
        "id": 21,
        "full_name": "Denver Nuggets",
        "short_name": "Nuggets",
        "abbr": "DEN",
        "logo": "https://cdn.example.com/logos/den.png"
      },
      "teams": [
        {
          "id": 14,
          "full_name": "Los Angeles Lakers",
          "abbr": "LAL"
        },
        {
          "id": 21,
          "full_name": "Denver Nuggets",
          "abbr": "DEN"
        }
      ],
      "league_name": "NBA",
      "type": "regular",
      "season": "2023-24",
      "week": null,
      "attendance": null,
      "coverage": null,
      "is_free": false,
      "trending": false,
      "away_rotation_number": 501,
      "home_rotation_number": 502,
      "num_bets": 1234,
      "boxscore": null,
      "broadcast": {
        "network": "ESPN",
        "internet": "ESPN+",
        "network_short": "ESPN"
      },
      "markets": {
        "moneyline": {
          "market_type": "moneyline",
          "count": 10,
          "available_count": 8,
          "best_odds": {
            "decimal": 2.15,
            "american": "+115",
            "book_id": 69,
            "book_name": "FanDuel"
          },
          "outcomes": [
            {
              "outcome_id": 123456789,
              "book_id": 69,
              "market_type": "moneyline",
              "side": "home",
              "team_id": 21,
              "team": {
                "id": 21,
                "name": "Denver Nuggets",
                "abbr": "DEN"
              },
              "odds": {
                "decimal": 1.75,
                "american": "-133",
                "fractional": "3/4",
                "original": 1.75
              },
              "is_live": false,
              "is_available": true,
              "value": null,
              "line_status": "available",
              "period": "full_game"
            }
          ],
          "consensus": {
            "average_odds": {
              "decimal": 1.82
            },
            "book_count": 5,
            "available_count": 8
          }
        },
        "spread": {
          "market_type": "spread",
          "count": 10,
          "available_count": 8,
          "best_odds": {
            "decimal": 1.91,
            "american": "-110",
            "book_id": 68,
            "book_name": "DraftKings"
          }
        },
        "total": {
          "market_type": "total",
          "count": 10,
          "available_count": 8
        },
        "core_bet_types": null
      },
      "meta": {},
      "updated_at": "2024-01-15T02:55:12.345Z"
    }
  ],
  "count": 1,
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 3,
    "has_more": true
  }
}

GET

/api/v1/nba/odds/games/:game_id

Get Game by ID

Retrieve a single normalized game by its ID. This is the most direct way to look up full odds, boxscore, and metadata for a specific game.

Parameters

Name	Type	Required	Description
`game_id`	integer (path)	Required	Unique game identifier from the odds feed.
`date`	string (YYYY-MM-DD)	Optional	Specify the date to resolve the game if it appears on multiple dates.
`include_markets`	string	Optional	When set to `"false"`, omits the `markets` object to reduce payload size.
`include_boxscore`	string	Optional	When set to `"false"`, omits the `boxscore` object.

Response

On success, returns a single normalized game object with the exact same shape as the items in the /api/v1/nba/odds/games list response. On failure, returns a 404 with an error message.

200 OK — { success: true, data: Game }
404 Not Found — { success: false, error: "Game not found" }

Example Request (by ID)

curl -X GET "https://odds-marketplace.onrender.com/api/v1/nba/odds/games/401123456?include_markets=true&include_boxscore=true" \
  -H "Authorization: Bearer sk_your_api_key_here"

Example Response (success)

{
  "success": true,
  "data": {
    "game_id": 401123456,
    "league_id": 1,
    "status": "scheduled",
    "start_time": "2024-01-15T03:00:00.000Z",
    "away_team_id": 14,
    "home_team_id": 21,
    "away_team": {
      "id": 14,
      "full_name": "Los Angeles Lakers",
      "abbr": "LAL"
    },
    "home_team": {
      "id": 21,
      "full_name": "Denver Nuggets",
      "abbr": "DEN"
    },
    "markets": {
      "moneyline": {
        "market_type": "moneyline",
        "count": 10,
        "available_count": 8
      }
    },
    "boxscore": null,
    "meta": {},
    "updated_at": "2024-01-15T02:55:12.345Z"
  }
}

Example Response (not found)

{
  "success": false,
  "error": "Game not found"
}

GET

/api/v1/nba/odds/games/:game_id/boxscore

Get Game Boxscore

Retrieve the live or final boxscore for a specific game.

Parameters

Name	Type	Required	Description
`game_id`	integer (path)	Required	Unique game identifier.
`date`	string (YYYY-MM-DD)	Optional	Specify the date to resolve the game.

Response

Returns the boxscore data for the game including period scores and status.

Example Request

curl -X GET "https://odds-marketplace.onrender.com/api/v1/nba/odds/games/401123456/boxscore" \
  -H "Authorization: Bearer sk_your_api_key_here"

Example Response

{
  "success": true,
  "data": {
    "game_id": 401123456,
    "status": "in_progress",
    "boxscore": {
      "clock": "4:20",
      "period": 4,
      "home_score": 102,
      "away_score": 98,
      "period_scores": [
        { "period": 1, "home": 25, "away": 24 },
        { "period": 2, "home": 28, "away": 30 },
        { "period": 3, "home": 24, "away": 22 },
        { "period": 4, "home": 25, "away": 22 }
      ]
    }
  }
}