# US Sports Probability Engine: NFL, NBA, MLB & NHL (`jenko_systems/us-sports-probability-engine`) Actor

Statistical win probabilities, expected scores, totals (over/under) and spreads for every NFL, NBA, MLB and NHL game. Poisson / Negative Binomial and Gaussian models with home advantage, back-to-back fatigue and time decay, plus market edge and a public walk-forward calibration backtest.

- **URL**: https://apify.com/jenko_systems/us-sports-probability-engine.md
- **Developed by:** [Jenko Systems](https://apify.com/jenko_systems) (community)
- **Features:** Limited permissions
- **Stats:** 3 total users, 3 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

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

## 🏈🏀⚾🏒 US Sports Probability Engine: NFL, NBA, MLB & NHL

**Statistical win probabilities for every game in the four major US leagues.** For each game you get win probability, expected score, over/under and spread prices, the most likely scores and fair odds. When a betting line is published, you also get the model's **edge versus the market**.

Pick the league with one filter: **NFL, NBA, MLB, NHL or all**. Between them, the four leagues cover the whole year:

| League | Season |
|---|---|
| 🏒 NHL | October → June |
| 🏀 NBA | October → June |
| 🏈 NFL | September → February |
| ⚾ MLB | March → October |

***

### Why this one

- **A real model, not tips.** Goals and runs use a Poisson or Negative Binomial model. Points use a Gaussian model. Each team gets an attack and a defense rating, adjusted for home advantage, back-to-back fatigue (NBA/NHL) and time decay. Ratings are shrunk toward the league average, so a hot two-week streak doesn't produce silly numbers.
- **Overtime handled properly.** In the NHL the model prices regulation (home / tie / away) separately, then resolves overtime and shootouts. In MLB it resolves extra innings the same way.
- **Proven calibration.** The `calibration` mode runs a walk-forward backtest. Each week the model is refit using only past games, then it predicts the next week. You get accuracy, Brier score, log loss and calibration bins. In a well-calibrated model, games priced at 60% are won about 60% of the time, and you can check it yourself.
- **Market comparison.** When a line is published, the output shows the no-vig market probability, the bookmaker margin and the model's edge.
- **Cheap and fast.** Game history is cached between runs, so a typical run only downloads the latest results.

***

### Modes

| Mode | What you get |
|---|---|
| `predictions` *(default)* | Every game today, tomorrow or both (US Eastern, the leagues' own calendar): win %, expected score, totals ladder, spread, team totals, most likely scores, fair odds, market edge |
| `matchup` | Any two teams, home/away or neutral site, with your own total and spread lines |
| `power_rankings` | All teams ranked by net rating, with offense/defense per game and P(beat an average team) |
| `team` | One team: rating and rank, last 10 results, next 5 games with win probabilities |
| `calibration` | Walk-forward backtest: accuracy, Brier score, log loss, calibration bins and model vs market |

Every field is optional. Empty fields get sensible examples (today's games, top-ranked teams), and the run tells you what it assumed in `defaults_used`.

***

### Example inputs

Tonight's NHL games:

```json
{ "mode": "predictions", "league": "nhl" }
```

Tomorrow's NBA games:

```json
{ "mode": "predictions", "league": "nba", "day": "tomorrow" }
```

A hypothetical NBA Finals game on neutral ground, priced at a 224.5 total:

```json
{ "mode": "matchup", "league": "nba", "home_team": "BOS", "away_team": "Lakers", "neutral_site": true, "total_line": 224.5 }
```

How good is the model? Backtest the last 90 days of MLB:

```json
{ "mode": "calibration", "league": "mlb", "backtest_days": 90 }
```

***

### Sample output (`predictions`, NHL)

```json
{
  "league": "NHL",
  "date": "2026-11-03",
  "matchup": "TOR @ BOS",
  "prob_home_win": 0.5712,
  "prob_away_win": 0.4288,
  "prob_regulation": { "home": 0.4471, "tie": 0.2236, "away": 0.3293 },
  "expected_score": { "home": 3.21, "away": 2.84 },
  "expected_total": 6.05,
  "most_likely_scores": [ { "score": "3-2", "prob": 0.0812 } ],
  "totals": [ { "line": 6.5, "over": 0.4213, "under": 0.5787 } ],
  "spread": { "home_line": -1.5, "home_covers": 0.3102, "away_covers": 0.6898 },
  "team_totals": { "home": { "3+": 0.6011 }, "away": { "3+": 0.5402 } },
  "fair_odds": { "home_american": -133, "away_american": 133 },
  "market": { "market_prob_home_no_vig": 0.5904, "edge_home": -0.0192 }
}
```

*(Illustrative values.)*

***

### 🤖 Use with AI agents (MCP)

This actor is available through the **Apify MCP server** (`mcp.apify.com`), so Claude, ChatGPT and other agents can call it directly:

- *"What are the win probabilities for tonight's NBA games?"*
- *"Price Yankees vs Red Sox, over 8.5 runs."*
- *"Which NHL team has the best defense right now?"*

Set `"summary_only": true` for a compact answer that fits an agent's context.

***

### Backtest (out of sample)

The model was refit every week using only past games, then it predicted the following week. Parameters were chosen in one season and tested on the next, so the test numbers below are out of sample. **Brier skill** is the improvement over always predicting the league's home win rate (0% = no skill).

| League | Test period | Games | Accuracy | Brier | Brier skill |
|---|---|---|---|---|---|
| 🏀 NBA | 2025-26 season | 1,322 | **67.8%** | 0.207 | **+16%** |
| 🏈 NFL | 2024 season to Oct 2026 | 676 | **65.1%** | 0.225 | **+10%** |
| ⚾ MLB | 2025 season | 2,422 | 56.1% | 0.243 | +2% |
| 🏒 NHL | 2025-26 season | 1,394 | 53.9% | 0.247 | +1% |

Across two NBA seasons, games where the model gave **70% or more** were won **82%** of the time. Totals are well calibrated in the NBA.

What this means in practice:

- **NBA and NFL: strong, well-calibrated signal.**
- **MLB and NHL: small edge only.** Single games are close to coin flips in both sports, and the biggest single factor (the starting pitcher or goalie) is not in the model. Treat these numbers as a calibrated baseline and add your own pitcher or goalie view.
- **Against the betting market (NFL closing lines), the market is more accurate** (Brier 0.213 vs 0.226). Betting every "edge" the model found lost money over the period. Use the market comparison to spot disagreements worth investigating, not as automatic picks.

Run `"mode": "calibration"` to check the live model yourself at any time.

### Methodology and limits

- **Inputs:** final scores, schedule, home/neutral site and rest days. Player-level statistics are **not** used, so injuries and lineup news only show up once they affect results. Factor them in yourself when they matter (a star out, a backup goalie or pitcher).
- **Time decay:** half-life of 50 days (NBA), 120 days (NHL), 150 days (MLB) or 200 days (NFL), so early-season numbers lean on last season and adapt fast. These values were picked in one season and validated on the next.
- **NFL:** with only 17 games per team, NFL ratings are the noisiest. Key numbers (3, 7) are not modeled explicitly.
- This is a statistical model for analysis and research. It is **not** betting advice, and no model wins every game.

***

### Pricing

You pay per result (one game, team or report). Runs that return nothing, such as an off-season date or a team not found, cost nothing beyond the platform start fee. The reason appears at the top of the run.

***

Made by **[Jenko Systems](https://jenkosystems.com)**: refined public data, modeled.

# Actor input Schema

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

predictions = probabilities for upcoming games (default). matchup = any two teams. power_rankings = model ratings for every team. team = one team's rating, last 10 results and next games. calibration = walk-forward backtest of the model (accuracy, Brier score, calibration bins).

## `league` (type: `string`):

Which championship to analyze. 'all' runs every league that has games in the period (leagues in off-season are skipped).

## `day` (type: `string`):

Which slate to analyze, by the leagues' own calendar (US Eastern time): today (default), tomorrow, or both. Games already started or finished today are included too (pre-game probabilities + final score). NFL: when there are no games today/tomorrow, the next game day within 7 days is returned.

## `team` (type: `string`):

Abbreviation or name (e.g. BOS, Lakers, New York Yankees). In 'predictions' it filters that team's game; in 'team' mode it picks the team (empty = top-rated team).

## `home_team` (type: `string`):

Matchup mode only. Empty = the #1 team in the power rankings.

## `away_team` (type: `string`):

Matchup mode only. Empty = the #2 team in the power rankings.

## `neutral_site` (type: `boolean`):

Matchup mode only: removes home advantage.

## `total_line` (type: `number`):

Matchup mode only: over/under line to price (e.g. 6.5 goals, 224.5 points). Empty = lines around the expected total.

## `home_spread` (type: `number`):

Matchup mode only: home handicap (e.g. -1.5, -6.5). Empty = automatic.

## `top_n` (type: `integer`):

Power rankings only: how many teams to return. Empty = all.

## `backtest_days` (type: `integer`):

Calibration only: how many past days to evaluate with weekly refits. Default 60.

## `include_market` (type: `boolean`):

When a betting line is published for the game, add the no-vig market probability and the model's edge.

## `summary_only` (type: `boolean`):

Drops the detailed blocks (totals ladder, team totals, most likely scores, model info) and keeps the headline probabilities.

## Actor input object example

```json
{
  "mode": "predictions",
  "league": "all",
  "day": "today",
  "neutral_site": false,
  "include_market": true,
  "summary_only": false
}
```

# Actor output Schema

## `predictions` (type: `string`):

One row per game (or team/report, depending on the mode).

## `rankings` (type: `string`):

Power rankings view (mode: power_rankings).

## `allFields` (type: `string`):

Full results with every field.

## `summary` (type: `string`):

Mode, leagues, item count and defaults used in this run.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("jenko_systems/us-sports-probability-engine").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("jenko_systems/us-sports-probability-engine").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 '{}' |
apify call jenko_systems/us-sports-probability-engine --silent --output-dataset

```

## MCP server setup

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

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/f7jabHOlwayb0HMzM/builds/RYo9ZUKY1fh9MWyJX/openapi.json
