# NFL Stats (`payai/nfl-stats`) Actor

Scrapes live NFL statistics and calculates Expected Value percentages for pick'em leagues. Analyzes Against The Spread records, home/road performance, and momentum trends from ESPN, TeamRankings, and Pro Football Reference. Provides top team recommendations with confidence ratings for smart bettors.

- **URL**: https://apify.com/payai/nfl-stats.md
- **Developed by:** [PayAI](https://apify.com/payai) (community)
- **Categories:** AI, Agents, Other
- **Stats:** 26 total users, 1 monthly users, 98.4% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$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

## NFL Stats EV Scraper

### Overview

Advanced NFL statistics scraper that calculates Expected Value (EV) percentages for pick'em leagues and sports betting analysis. This actor aggregates data from multiple authoritative sources to provide comprehensive team performance metrics and betting recommendations.

### Features

- **Multi-Source Data Collection**: Scrapes from ESPN, TeamRankings, NFL.com, and Pro Football Reference
- **EV Calculation Engine**: Proprietary 4-factor weighted algorithm for accurate predictions
- **ATS Performance Tracking**: Against The Spread records with home/road splits
- **Real-Time Updates**: Current season statistics with automatic weekly updates
- **Supabase Integration**: Optional database storage for historical tracking
- **Excel Export Ready**: Formatted data for spreadsheet analysis

### Quick Start

```javascript
// Basic usage - get current week's picks
const input = {
  "week": "current",
  "season": "2024"
};
```

### Input Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `week` | string | "current" | NFL week number or "current" for latest |
| `season` | string | "2024" | NFL season year |
| `sources` | array | \["espn", "teamrankings", "nfl", "pro-football-reference"] | Data sources to scrape |
| `calculateEV` | boolean | true | Enable EV calculations |
| `updateSupabase` | boolean | false | Store in Supabase (requires config) |
| `includeInjuries` | boolean | true | Include injury reports |
| `pickemStrategy` | string | "ev" | Strategy: "ev", "contrarian", "chalk", "balanced" |

### Output Format

#### Team Data Structure

```json
{
  "team": "BAL",
  "teamName": "Baltimore Ravens",
  "atsRecord": "13-5-1",
  "atsPercentage": 72.2,
  "coverRate": 72.2,
  "homeATSPercentage": 75.0,
  "roadATSPercentage": 69.4,
  "units": 3.8,
  "profitability": "profitable",
  "evPercentage": 59,
  "evCategory": "SOLID PLAY",
  "last5ATS": "4-1",
  "favoriteCoverRate": 68.5,
  "underdogCoverRate": 76.0
}
```

#### Complete Output Example

```json
{
  "type": "FINAL_ANALYSIS",
  "week": "current",
  "season": "2024",
  "totalTeams": 32,
  "teams": [...],
  "recommendations": {
    "topPicks": [
      {
        "rank": 1,
        "team": "CAR",
        "teamName": "Carolina Panthers",
        "evPercentage": 61,
        "confidenceLevel": "SOLID PLAY",
        "atsRecord": "13-4-0",
        "units": 7.6
      }
    ],
    "confidencePool": [...],
    "avoidList": [
      {
        "team": "NYG",
        "teamName": "New York Giants",
        "evPercentage": 44,
        "confidenceLevel": "LEAN FADE",
        "atsRecord": "6-11-0"
      }
    ],
    "analysis": {
      "bestATS": [...],
      "bestHome": [...],
      "bestRoad": [...],
      "momentum": [...]
    }
  }
}
```

### EV Categories & Confidence Levels

| EV Score | Category | Action | Confidence Points |
|----------|----------|--------|-------------------|
| **65%+** | STRONG PLAY | Maximum bet | 15-16 points |
| **58-64%** | SOLID PLAY | Strong bet | 12-14 points |
| **52-57%** | LEAN PLAY | Medium bet | 8-11 points |
| **48-51%** | TOSS UP | Skip/minimal | 4-7 points |
| **42-47%** | LEAN FADE | Avoid | 1-3 points |
| **<42%** | STRONG FADE | Strong avoid | 0 points |

### EV Calculation Methodology

The Expected Value is calculated using a weighted 4-factor model:

#### Standard EV Strategy (Default)

- **ATS Performance (40%)**: Historical Against The Spread success rate
- **Situational Factors (30%)**: Home/road, division, prime time performance
- **Spread Analysis (20%)**: Performance as favorite vs underdog
- **Momentum (10%)**: Recent form and trending patterns

Formula: `EV = (0.40 × ATS) + (0.30 × Situational) + (0.20 × Spread) + (0.10 × Momentum)`

#### Alternative Strategies

##### Contrarian

- Fades public favorites, targets underdogs
- Weights: ATS 30%, Situational 20%, Spread 20%, Momentum 30%

##### Chalk

- Follows favorites and public consensus
- Weights: ATS 50%, Situational 20%, Spread 20%, Momentum 10%

##### Balanced

- Mix of value and safety
- Weights: ATS 35%, Situational 25%, Spread 25%, Momentum 15%

### Usage Examples

#### Via Apify Console

1. Navigate to the actor page
2. Enter your desired parameters
3. Click "Run"
4. View results in the dataset

#### Via API

```bash
curl -X POST https://api.apify.com/v2/acts/payai/nfl-stats/runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "week": "5",
    "season": "2024",
    "pickemStrategy": "ev"
  }'
```

#### Via JavaScript Client

```javascript
const { ApifyClient } = require('apify-client');

const client = new ApifyClient({
    token: 'YOUR_API_TOKEN',
});

// Run the actor
const run = await client.actor('payai/nfl-stats').call({
    week: 'current',
    season: '2024',
    calculateEV: true,
    pickemStrategy: 'ev'
});

// Get results
const { items } = await client.dataset(run.defaultDatasetId).listItems();

// Find top picks
const finalAnalysis = items.find(item => item.type === 'FINAL_ANALYSIS');
console.log('Top 5 Picks:', finalAnalysis.recommendations.topPicks);
```

#### Via Python

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_API_TOKEN')

## Run the actor
run = client.actor('payai/nfl-stats').call(run_input={
    'week': 'current',
    'season': '2024',
    'pickemStrategy': 'ev'
})

## Get results
items = client.dataset(run['defaultDatasetId']).list_items().items

## Process results
for item in items:
    if item.get('type') == 'FINAL_ANALYSIS':
        print('Top picks:', item['recommendations']['topPicks'])
```

### Data Sources

#### TeamRankings

- **Data**: ATS trends, home/road splits, O/U trends
- **Update Frequency**: Real-time during games
- **Reliability**: 95%+ uptime

#### ESPN

- **Data**: Standings, power rankings, injury reports
- **Update Frequency**: Daily
- **Reliability**: 90%+ uptime

#### Pro Football Reference

- **Data**: Historical stats, advanced metrics, game logs
- **Update Frequency**: Daily after games
- **Reliability**: 95%+ uptime

#### NFL.com

- **Data**: Official stats, current matchups, news
- **Update Frequency**: Real-time
- **Reliability**: 85%+ uptime

### Performance & Cost

#### Performance Metrics

- **Average Runtime**: 2-4 minutes
- **Data Points**: 500+ per run
- **Teams Analyzed**: All 32 NFL teams
- **Success Rate**: 95%+ data retrieval
- **Memory Usage**: 512MB-1GB

#### Cost Estimation

- **Compute Units**: ~0.01-0.02 per run
- **Cost per Run**: $0.004-0.008
- **Daily Usage** (1 run): ~$0.008
- **Weekly Usage** (7 runs): ~$0.056
- **Monthly Usage** (30 runs): ~$0.24
- **Season Usage** (150 runs): ~$1.20

### Best Practices

#### Optimal Timing

- **Tuesday-Thursday**: Most accurate weekly data
- **Friday Morning**: Final injury reports available
- **Sunday Morning**: Last-minute updates before games

#### Recommended Settings

```json
{
  "week": "current",
  "season": "2024",
  "sources": ["teamrankings", "espn"],
  "calculateEV": true,
  "pickemStrategy": "ev",
  "includeInjuries": true
}
```

#### Pick'em League Strategy

1. Run actor Tuesday evening for initial analysis
2. Update Friday for injury adjustments
3. Final run Sunday morning for late changes
4. Use top 5 picks for confidence pool
5. Avoid bottom 5 teams completely

### Troubleshooting

#### Common Issues

##### No Team Data Returned

- **Cause**: Website structure changed
- **Solution**: Report issue, actor will be updated

##### Timeout Errors

- **Cause**: Slow website response
- **Solution**: Reduce sources array, try again later

##### Missing Current Week

- **Cause**: Season transition period
- **Solution**: Specify week number explicitly

### Database Integration (Optional)

When `updateSupabase` is enabled, data is stored in:

- `nfl_team_stats`: Current team statistics
- `nfl_weekly_analysis`: Weekly recommendations
- `nfl_ev_calculations`: Detailed EV breakdowns

Required environment variables:

```bash
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_KEY=your_service_key
```

### Limitations

- Data availability depends on source website structure
- Preseason weeks have limited statistics
- Playoff weeks use different calculation weights
- Live odds not included (historical ATS only)
- Injury reports updated once daily (not real-time)

### Legal Disclaimer

This actor provides statistical analysis for informational purposes only. Users are responsible for compliance with local laws regarding sports betting. No gambling advice is provided or implied. Past performance does not guarantee future results.

### Support & Feedback

- **Issues**: Report via Apify platform
- **Feature Requests**: Contact through Apify console
- **Documentation**: This README
- **Updates**: Follow actor for notifications

### Version History

- **v0.1.10**: Enhanced selector robustness, 32 teams found
- **v0.1.9**: Improved TeamRankings accuracy
- **v0.1.8**: Added multiple fallback selectors
- **v0.1.0**: Initial release with 4-source integration

***

*Last Updated: September 2025*
*Actor ID: S654tc9Mr9Tka4FSw*

# Actor input Schema

## `week` (type: `string`):

NFL week number or 'current' for current week

## `season` (type: `string`):

NFL season year

## `calculateEV` (type: `boolean`):

Calculate EV% for each team

## `updateSupabase` (type: `boolean`):

Store results in Supabase database

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

Scrape and include injury reports

## `pickemStrategy` (type: `string`):

Strategy for pick'em recommendations

## Actor input object example

```json
{
  "week": "current",
  "season": "2024",
  "calculateEV": true,
  "updateSupabase": true,
  "includeInjuries": true,
  "pickemStrategy": "ev"
}
```

# 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("payai/nfl-stats").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("payai/nfl-stats").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 payai/nfl-stats --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,payai/nfl-stats"
        }
    }
}
```

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/S654tc9Mr9Tka4FSw/builds/aIjk1nIQEFLY0XSyB/openapi.json