# US Sports Odds & Results - NFL, NBA, MLB, NHL Lines & ATS (`poetsc/us-sports-odds`) Actor

Final scores with opening and closing point spreads, moneylines and totals for NFL, NBA, MLB, NHL, WNBA and college sports, plus ATS and over/under results, consensus lines, no-vig win probability, upcoming games and injury reports. ESPN public data.

- **URL**: https://apify.com/poetsc/us-sports-odds.md
- **Developed by:** [Poetsc Data](https://apify.com/poetsc) (community)
- **Categories:** Sports, Automation, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 game with lines

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does US Sports Odds & Results do?

US Sports Odds & Results turns ESPN's public data into a **clean betting dataset** for **NFL, NBA, MLB, NHL, WNBA, college football (FBS) and college basketball (D-I)**. Every game comes with the final score **and the betting lines next to it**:

- **Opening and closing point spread, moneyline and total** from a major US sportsbook (DraftKings, ESPN BET, Caesars, MGM…)
- **Consensus spread and total** (median across sportsbooks), so one odd number never skews your model
- **ATS winner** (who covered), **over / under result**, **did the favorite win**, and **no-vig home win probability**, already calculated
- Final score, quarter / period / inning line scores, overtime, venue, neutral site, attendance, team records and AP rankings

Three modes:

- **Results**: finished games with closing lines and outcomes, for one day or a whole season.
- **Schedule**: upcoming games with current lines, optionally with **each team's injury list**.
- **Injuries**: the current league injury report, one row per player (status, injury, expected return, news blurb).

No API key, no browser, no proxy. A full NBA month (about 230 games) takes under a minute.

### What data do you get?

| Field | Example |
|---|---|
| date, league, season, seasonType, week | 2023-11-05, NFL, 2023, regular, 9 |
| awayTeam / homeTeam (+ abbr, id, record, rank) | Miami Dolphins @ Kansas City Chiefs |
| awayScore, homeScore, linescores | 14, 21 |
| winner, margin, totalPoints, overtime | KC, 7, 35, false |
| oddsProvider | ESPN BET |
| homeSpreadOpen → homeSpread | -2.5 → -1.5 |
| homeMoneylineOpen → homeMoneyline, awayMoneyline | -140, +120 |
| totalOpen → total, overOdds, underOdds | 50.5 → 51, -110, -110 |
| consensusHomeSpread, consensusTotal, bookmakerCount | -1.5, 51, 8 |
| homeWinProbNoVig | 0.5652 |
| favorite, atsWinner, totalResult, favoriteWon | KC, KC, under, true |
| venue, venueCity, neutralSite, attendance | Deutsche Bank Park, Frankfurt, true |

Spreads are from the **home team's** point of view (negative = home favored). For MLB and NHL the spread is the run line / puck line (usually ±1.5). Moneylines and prices are American odds.

Optional extras:

- **Include every sportsbook**: `bookmakers[]` with each book's spread, moneyline and total (opening and closing where available).
- **Include injury lists** (Schedule mode): `homeInjuries[]` and `awayInjuries[]` with player, position, status (Out, Questionable, Day-To-Day…), injury and expected return date.

### Use cases

- **Backtesting betting models**: seasons of closing lines with ATS and over/under outcomes already labelled
- **Closing line value (CLV)**: compare opening and closing numbers game by game
- **Daily pipelines**: schedule tomorrow's games with lines and injuries every evening, results every morning
- **Power ratings and ELO**: scores, margins, home/away and neutral-site flags in one flat table
- **Fantasy and DFS**: league-wide injury report as a clean table, refreshed on a schedule

### How to use it

1. Choose **What to get**: Results, Schedule or Injuries.
2. Pick **Leagues**.
3. Set **Start date** and optional **End date** (US Eastern). Empty = yesterday (Results) or today (Schedule).
4. Optionally list **Teams** (e.g. `KC`, `LAL`, `NYY`).
5. Run, then export JSON, CSV or Excel, or call it from your code via the Apify API. Add an Apify Schedule to run it daily.

### Input examples

Last NFL season with closing lines:

```json
{ "mode": "results", "leagues": ["nfl"], "startDate": "2025-09-04", "endDate": "2026-02-08" }
```

Tonight's NBA and NHL games with lines and injuries:

```json
{ "mode": "schedule", "leagues": ["nba", "nhl"], "includeInjuries": true }
```

Current NFL injury report:

```json
{ "mode": "injuries", "leagues": ["nfl"] }
```

### Output example

```json
{
  "date": "2025-11-08",
  "league": "NCAAF",
  "season": 2025,
  "seasonType": "regular",
  "awayTeam": "Ohio State Buckeyes",
  "awayAbbr": "OSU",
  "awayScore": 34,
  "homeTeam": "Purdue Boilermakers",
  "homeAbbr": "PUR",
  "homeScore": 10,
  "winner": "OSU",
  "margin": -24,
  "totalPoints": 44,
  "oddsProvider": "ESPN BET",
  "homeSpreadOpen": 26.5,
  "homeSpread": 30.5,
  "totalOpen": 47.5,
  "total": 49.5,
  "favorite": "OSU",
  "atsWinner": "PUR",
  "totalResult": "under",
  "favoriteWon": true
}
```

### How much does it cost?

Pay per result (see the Pricing tab): one charge per game and a smaller one per injury row. A full NFL regular season (about 270 games) costs well under a dollar.

### Notes and limits

- Lines are the numbers ESPN publishes from its sportsbook partners. Reliable opening and closing lines are available from about the **2023** season on; older games may have closing lines only, or none.
- Older seasons sometimes show conflicting numbers between books. Use `consensusHomeSpread` / `consensusTotal`, or `bookmakers[]`, if you want to filter outliers yourself.
- ESPN keeps only the **current** injury report, so injury lists are added to upcoming games only.
- Not affiliated with ESPN or any sportsbook. Data is for research and analysis.

### Feedback

Missing a league or a field? Open an issue on the Issues tab.

# Actor input Schema

## `mode` (type: `string`):

Results = finished games with final score, opening & closing lines and ATS / over-under outcome. Schedule = upcoming games with current lines (and optional injury lists). Injuries = current league injury report, one row per player.

## `leagues` (type: `array`):

Which leagues to fetch.

## `startDate` (type: `string`):

First day (YYYY-MM-DD, US Eastern). Defaults to yesterday in Results mode and today in Schedule mode. Not used for Injuries.

## `endDate` (type: `string`):

Last day. Leave empty for a single day. A whole season works; long ranges just take longer.

## `teams` (type: `array`):

Optional. Only keep games of these teams, by ESPN abbreviation (e.g. KC, LAL, NYY) or team ID. For Injuries, use the full team name.

## `includeOdds` (type: `boolean`):

Opening and closing spread, moneyline and total from a major US sportsbook, a multi-book consensus, no-vig win probability and ATS / over-under results.

## `includeAllBookmakers` (type: `boolean`):

Adds a bookmakers\[] array with each sportsbook's spread, moneyline and total (opening and closing where available).

## `includeInjuries` (type: `boolean`):

Adds homeInjuries\[] and awayInjuries\[] (player, position, status, injury) to upcoming games. ESPN only keeps the current report, so this is ignored for finished games.

## `maxItems` (type: `integer`):

Stop after this many games or injury rows.

## `maxConcurrency` (type: `integer`):

How many odds requests to run at once.

## Actor input object example

```json
{
  "mode": "results",
  "leagues": [
    "nba",
    "nfl"
  ],
  "includeOdds": true,
  "includeAllBookmakers": false,
  "includeInjuries": false,
  "maxItems": 10000,
  "maxConcurrency": 4
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "leagues": [
        "nba",
        "nfl"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("poetsc/us-sports-odds").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "leagues": [
        "nba",
        "nfl",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("poetsc/us-sports-odds").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "leagues": [
    "nba",
    "nfl"
  ]
}' |
apify call poetsc/us-sports-odds --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,poetsc/us-sports-odds"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/DDvqbh0vA5aAxHCtB/builds/a2BwhAfdu37UhArUs/openapi.json