# NFL Games API: Scores, Schedule and Results (`conserving_celerytop/nfl-games-api`) Actor

NFL game schedules, scores and results since 1999 as one row per game: season, week, teams, score, winner, margin, stadium, roof, temperature and wind. Open nflverse data under CC BY 4.0, no login. $1.00 per 1,000 games.

- **URL**: https://apify.com/conserving_celerytop/nfl-games-api.md
- **Developed by:** [Don Mangu](https://apify.com/conserving_celerytop) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 games

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

Get NFL games by season, week and team as one row per game, for $1.00 per 1,000 games.

Add the seasons you need and filter by week, team, game type or final games only. Each row has the date, kickoff time, teams, score, winner, margin, stadium, roof, surface, temperature, wind and rest days. The data covers the seasons 1999 to now. It comes from the open nflverse games file and is read at run time, so you get the same results as the file shows that day. You need no login and no API key.

Game data: nflverse (github.com/nflverse/nflverse-data), CC BY 4.0. Fields filtered and reformatted. Not affiliated with or endorsed by the NFL.

### Sample output

One row per game. These are real rows from the 2026 season, newest first, read on 6 October 2026:

| Date | Week | Away | Score | Home | Winner | Margin |
|---|---|---|---|---|---|---|
| 2026-10-05 | 4 | ATL | 45-24 | NO | ATL | 21 |
| 2026-10-04 | 4 | DET | 26-32 | CAR | CAR | 6 |
| 2026-10-04 | 4 | LAC | 23-30 | SEA | SEA | 7 |
| 2026-10-04 | 4 | KC | 30-27 | LV | KC | 3 |
| 2026-10-04 | 4 | DEN | 14-24 | SF | SF | 10 |

The first row in full:

```json
{
  "game_id": "2026_04_ATL_NO",
  "season": 2026,
  "game_type": "REG",
  "week": 4,
  "gameday": "2026-10-05",
  "gametime": "20:15",
  "weekday": "Monday",
  "away_team": "ATL",
  "home_team": "NO",
  "away_score": 45,
  "home_score": 24,
  "result": -21,
  "total": 69,
  "overtime": false,
  "stadium": "Caesars Superdome",
  "roof": "dome",
  "surface": null,
  "temp": null,
  "wind": null,
  "away_rest": 11,
  "home_rest": 8,
  "div_game": true,
  "winner": "ATL",
  "margin": 21,
  "is_final": true
}
```

The key-value store of the run also holds an `ATTRIBUTION` record with the data credit, the licence link and a note on what was changed, and a `STATS` record with the run counts.

### How to use the NFL games API

1. Open the Actor and go to the **Input** tab.
2. In **Seasons**, add one or more years such as `2025`. Leave it empty to get the current season.
3. Optionally set **Weeks**, **Teams**, **Game types**, **Only final games**, **Sort order** and **Max games**.
4. Click **Start**, then open the **Overview** view of the dataset. Download it as JSON, CSV or Excel.

You can also call the Actor from your own code with the Apify API, run it on a schedule, or connect it to Make, Zapier or n8n.

### What you get

- One row per NFL game, regular season and playoffs, from 1999 to the current season.
- Season, week, game type, date, weekday and kickoff time.
- Away and home team codes, away and home score, the result (home score minus away score), the total points and an overtime flag.
- Stadium, roof (outdoors, open, closed or dome), surface, temperature and wind where the source has them.
- Days of rest for both teams and a flag for division games.
- Three derived fields: `winner` (a team code, or `TIE`), `margin` (points, never negative) and `is_final`.
- Filters by season, week, team and game type, and a sort order of oldest or newest first.

Games that are not played yet are in the file with a date and no score. They have `is_final` set to false. Turn on **Only final games** to leave them out.

### Pricing

You pay per game row saved. The price is $1.00 per 1,000 games, which is $0.001 per game. Apify also charges a start event of $0.00005 per GB of run memory, which is $0.0000125 at the default 256 MB. Apify platform usage is included. Status rows (a season without games, or filters that match nothing) are free.

| Example | Games | Cost |
|---|---|---|
| Week 1 of one season (16 games) | 16 | $0.016 |
| One regular season (272 games) | 272 | $0.272 |
| One season with playoffs (2025, 285 games) | 285 | $0.285 |
| Every game in the file, 1999 to 2026 | 7,548 | $7.548 |

Paid plans get lower prices per game as your Apify plan tier goes up. You can set a maximum cost per run in the run options. The Actor stops when it reaches that limit and says so in the status message.

### Input

```json
{
  "seasons": ["2026"],
  "teams": ["KC"],
  "gameTypes": ["REG"],
  "onlyFinal": true,
  "sortOrder": "desc",
  "maxGames": 10
}
```

All fields are optional. `seasons` takes four digit years. A season is named after the year it starts, so the games of January 2026 belong to season 2025. `weeks` takes numbers from 1 to 22. `teams` takes team codes such as `KC` or team names such as `Kansas City Chiefs`. `gameTypes` takes `REG` for the regular season or `POST` for the playoffs. `WC`, `DIV`, `CON` and `SB` select one playoff round. `maxGames` defaults to 1,000 and you pay for each row returned. A wrong value, for example the week 99 or the team `Nobody`, stops the run at once with a message that says what to change. No game is charged.

### Output fields

| Field | Meaning |
|---|---|
| `game_id` | The id of the game: season, week, away team and home team |
| `season`, `week`, `game_type` | Season year, week number, and `REG`, `WC`, `DIV`, `CON` or `SB` |
| `gameday`, `weekday`, `gametime` | Date, weekday and kickoff time. `gametime` is 24-hour time in the Eastern time zone, whatever the place of the game |
| `away_team`, `home_team` | Team codes as the source writes them for that season |
| `away_score`, `home_score` | Points. Null until the game is final |
| `result`, `total` | Home score minus away score, and the sum of both scores |
| `overtime` | True when the game went to overtime |
| `stadium`, `roof`, `surface` | Venue details as listed in the source. Null when the source has no value |
| `temp`, `wind` | Temperature and wind speed in miles per hour, for outdoor and open roof games only. The source does not state the unit of the temperature |
| `away_rest`, `home_rest` | Days of rest before the game |
| `div_game` | True when both teams play in the same division |
| `winner`, `margin`, `is_final` | Derived by this Actor: the winning team code or `TIE`, the point margin, and whether the game has a final score |

### Seasons and team codes

The file holds the seasons 1999 to 2026 today, 7,548 games. A season with no games, for example one that the NFL has not published yet, returns one free status row. The source uses the team code of the season. For example, the Raiders are `OAK` before 2020 and `LV` from 2020, the Chargers are `SD` before 2017 and `LAC` from 2017, and the Rams are `STL` before 2016 and `LA` from 2016. If you type a nickname such as `Raiders`, the Actor looks for all codes of that team.

### FAQ

#### Is it legal to use this data?

The Actor reads the nflverse games file. The nflverse-data repository on GitHub is licensed under Creative Commons Attribution 4.0 (CC BY 4.0). That licence allows reuse, including commercial use, if you give credit, link the licence and say what was changed. The credit line is at the top of this page and in the `ATTRIBUTION` record of every run. Fields were filtered and reformatted. The same games table also sits in the nflverse nfldata repository, which has no licence file, so I cannot show a written licence for that copy. I built this Actor from the CC BY 4.0 release. This is not legal advice. Check that your own use follows the laws and terms that apply to you. "NFL" and team names are trademarks of their owners. They appear here only as plain facts, and this Actor is not affiliated with or endorsed by the NFL or any team.

#### Which data is not included?

There are no player names, no coach or referee names, no play by play, no live scores and no betting lines or odds. The source columns for those are dropped on purpose. You get team level game data only.

#### How fresh is the data?

The Actor downloads the file at the start of each run. A result appears when the nflverse file has it. The file is updated often in season, and I did not measure the delay. The Actor does not check the score against a second source.

#### Why did I get a status row and no games?

A `not_found` row means the file has no games for that season. A `no_matching_games` row means the file was read but no game fits your filters, for example a team code that the team did not use in that season. A `source_error` row means the data host did not answer. The Actor tries a second address for the same table first. No status row is charged.

#### Why did my run stop early?

The maximum cost per run was reached. This limit comes from the run options. On a Free plan it can also come from the credit that is left on your account. Raise the limit, add credit, or lower **Max games**. The status message of the run says how many games were saved.

#### Which memory setting should I use?

Keep the default of 256 MB or higher. The file is about 2 MB and a run takes a few seconds.

### Related Actors

- Football Fixtures API: Scores, Results and League Table (same author) returns football (soccer) fixtures, results and a computed league table.

### About this Actor

I built this Actor as an independent developer. Game data: nflverse (github.com/nflverse/nflverse-data), CC BY 4.0. Fields filtered and reformatted. Not affiliated with or endorsed by the NFL. If this saved you time, a rating helps others find it.

# Actor input Schema

## `seasons` (type: `array`):

Add seasons as four digit years, for example 2025. A season is named after the year it starts, so the games of January 2026 belong to season 2025. Leave empty to use the current season. Data starts in 1999.

## `weeks` (type: `array`):

Add week numbers from 1 to 22 to keep only those weeks, for example 1. Leave empty for all weeks. Playoff games are weeks 18 to 22, depending on the season.

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

Add team codes such as KC or BUF, or team names such as Kansas City Chiefs, to keep only games of those teams. Leave empty for all teams. The source uses the code of the season, for example OAK for the Raiders before 2020.

## `gameTypes` (type: `array`):

Add REG for regular season games or POST for playoff games. WC, DIV, CON and SB select one playoff round: wild card, divisional, conference and Super Bowl. Leave empty for all game types.

## `onlyFinal` (type: `boolean`):

Keep only games that have a final score. Games not yet played have no score and are returned when this is off.

## `sortOrder` (type: `string`):

Order the games by date and kickoff time.

## `maxGames` (type: `integer`):

Return at most this many game rows in total. You pay for each game row returned.

## Actor input object example

```json
{
  "seasons": [
    "2025"
  ],
  "weeks": [
    "1"
  ],
  "gameTypes": [
    "REG"
  ],
  "onlyFinal": false,
  "sortOrder": "asc",
  "maxGames": 20
}
```

# Actor output Schema

## `games` (type: `string`):

No description

## `attribution` (type: `string`):

No description

## `stats` (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 = {
    "seasons": [
        "2025"
    ],
    "weeks": [
        "1"
    ],
    "gameTypes": [
        "REG"
    ],
    "maxGames": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("conserving_celerytop/nfl-games-api").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 = {
    "seasons": ["2025"],
    "weeks": ["1"],
    "gameTypes": ["REG"],
    "maxGames": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("conserving_celerytop/nfl-games-api").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 '{
  "seasons": [
    "2025"
  ],
  "weeks": [
    "1"
  ],
  "gameTypes": [
    "REG"
  ],
  "maxGames": 20
}' |
apify call conserving_celerytop/nfl-games-api --silent --output-dataset

```

## MCP server setup

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

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/k1X5ir47xjIS2tcNd/builds/o7g1I8VtaHMPtU818/openapi.json