nytimes-games

An unofficial Python client for the New York Times Games APIs: Wordle, Connections, Strands, Spelling Bee, Letter Boxed and the Daily, Mini, Midi and Bonus crosswords, plus your own stats and game progress.

NYT doesn't publish documentation or an API spec for these endpoints. This package wraps them in one client with typed, validated Pydantic models, so you can build archives, stats dashboards, bots or your own games without reverse engineering NYT's APIs first. Optional extras add the nytg command line tool and a REST API.

Installation

pip install nytimes-games

The package installs as nytimes-games and is imported as nytgames. Python 3.10 or newer is required.

Quick start

from nytgames import NYTGamesClient

client = NYTGamesClient()

client.wordle("2025-06-12").solution
client.connections("2025-06-12").categories
client.crossword("mini")                  # today's Mini
client.crossword("daily", "1993-11-21")   # any Daily back to 1993

Your stats and game progress need your NYT session cookie:

client = NYTGamesClient(cookies="NYT-S=...")

stats = client.player_stats().stats
stats.wordle.calculatedStats.currentStreak
stats.connections.puzzles_won
stats.crossword_daily.dailyStats["monday"].avgTimeSeconds

What's available

Puzzles don't need cookies. Everything about you does.

Dates are YYYY-MM-DD strings. publish_type is daily, mini, midi or bonus, and date=None returns today's puzzle. NYT usually serves the next day's puzzle a day early.

archive() is the quickest way to get puzzle IDs for a date range, for example to check your progress on a month of puzzles:

midis = client.archive("crossword_midi", "2026-09-01", "2026-09-30")
client.crossword_game([p.id for p in midis], "midi")   # up to 30 IDs per call

Spelling Bee extras:

from nytgames import spelling_bee_hints

puzzle = client.spelling_bee_puzzle("2026-10-03")
spelling_bee_hints(puzzle)      # Spelling Bee Forum style hints: counts, pairs, points
client.spelling_bee_puzzles()   # every puzzle on the game page (about two weeks)

Cookies

To get your NYT-S cookie, log in at nytimes.com, open your browser's developer tools, and find the NYT-S cookie for .nytimes.com (Application tab in Chrome, Storage tab in Firefox). Treat it like a password: it gives access to your NYT account.

cookies can be:

• a Cookie header string: "NYT-S=...; nyt-a=..."
• a dict: {"NYT-S": "..."}
• a list of cookie objects with name and value keys, such as a JSON export from the Cookie-Editor browser extension

Errors

HTTP errors from NYT are raised as NYTGamesHTTPError, a subclass of requests.HTTPError:

from nytgames import NYTGamesNotFoundError

try:
    client.wordle("1900-01-01")
except NYTGamesNotFoundError:
    print("No puzzle that day")

Models

Every method returns Pydantic models from nytgames.models. Fields NYT adds later are kept rather than rejected, so new NYT fields don't break your code. Use .model_dump() to get plain dicts, and by_alias=True to keep NYT's original keys, such as "Queen Bee" in the Spelling Bee ranks.

Command line

The optional cli extra installs nytg:

pipx install "nytimes-games[cli]"     # or: pip install "nytimes-games[cli]"

nytg wordle                      # today's Wordle, without the answer
nytg wordle yesterday --answers
nytg connections friday -a       # the groups, in their colors
nytg strands 2025-06-12
nytg bee --hints                 # Spelling Bee Forum style hints
nytg letter-boxed
nytg crossword mini              # the grid and clues
nytg crossword daily 1993-11-21 --answers

Answers are hidden unless you pass --answers, in every output format. Dates can be YYYY-MM-DD, today, yesterday, tomorrow or a weekday, and first for the first puzzle in nytg archive.

Your stats and history

Log in once with your NYT-S cookie (see Cookies):

nytg auth login                  # paste the cookie; it's checked, then saved
nytg auth status

nytg stats                       # every game at a glance
nytg stats crossword             # averages, bests and streaks by weekday
nytg today                       # which of today's games you've played
nytg history crossword --from 2026-01-01 -f csv > solves.csv
nytg history wordle --from monday
nytg history bee

Cookies are read from --cookies, then the NYT_COOKIES environment variable, then the active profile.

Archiving

nytg archive connections --from first --out puzzles/

saves each date as puzzles/connections/YYYY-MM-DD.json. Run it again to resume: saved dates are skipped. Games: wordle, connections, strands, spelling-bee, letter-boxed, crossword-daily, crossword-mini and crossword-midi.

Output formats

Every command takes --format (-f), like gcloud:

nytg wordle --answers -f "value(solution)"
nytg stats -f json | jq '.[] | select(.game == "Wordle")'

Profiles and settings

Settings are saved per profile in ~/.config/nytg/config.ini (readable only by you), similar to gcloud configurations:

nytg config set format json      # default output format for this profile
nytg config list
nytg --profile alice auth login  # a second NYT account
nytg config profiles activate alice
nytg config profiles list

--profile or NYTG_PROFILE picks a profile for one command. Run nytg --install-completion for shell completion.

Building your own command line

nytgames.cli.extension lets you build a command line with every nytg command plus your own, sharing its root options (--profile, --cookies, --format), output formats and error messages:

import typer
from nytgames.cli.extension import FormatOption, create_app, emit, get_client, run

app = create_app(name="mytool", help="My NYT tools.", version="1.0.0")
db = typer.Typer(help="Query my archive.")
app.add_typer(db, name="db")


@db.command("midis")
def midis(fmt: FormatOption = None) -> None:
    """September's Midi crosswords."""
    puzzles = get_client().archive("crossword_midi", "2026-09-01", "2026-09-30")
    emit([{"date": p.print_date, "by": p.byline} for p in puzzles], fmt)


def main() -> None:   # point your [project.scripts] entry here
    run(app)

Each create_app() call returns an independent app. emit(data, fmt, table) prints JSON-compatible data in the requested format, with an optional function that renders the table format. get_client() returns a client with the cookies nytg would use. The other modules in nytgames.cli are internal.

REST API

The optional api extra serves everything as a REST API with FastAPI, including interactive docs at /docs.

pip install "nytimes-games[api]"
uvicorn nytgames.api:app

To customize it, write your own main.py:

from nytgames.api import create_app

app = create_app(title="My NYT Games API")   # any FastAPI settings

Or mount the routes in an existing FastAPI app:

from fastapi import FastAPI
from nytgames.api import add_exception_handlers, router

app = FastAPI()
app.include_router(router, prefix="/nyt")
add_exception_handlers(app)   # NYT errors become 404s and 403s instead of 500s

By default each request is made with the cookies sent to the API:

curl -H "Cookie: NYT-S=..." http://localhost:8000/player/stats

To use your own cookies for every request instead, override the client:

from nytgames import NYTGamesClient
from nytgames.api import get_client

app.dependency_overrides[get_client] = lambda: NYTGamesClient(cookies="NYT-S=...")

Anyone who can reach that API can then see your stats and progress, so keep it private.

examples/api has a complete main.py and Dockerfile for running your own instance in a container.

Endpoints

NYT errors are returned with NYT's status code, for example 404 for a date with no puzzle.

Contributing

NYT changes these APIs without notice, so bug reports with the failing date and error are very welcome. See CONTRIBUTING.md to set up a development environment.

License

MIT. This project is not affiliated with or endorsed by The New York Times. NYT puzzles are copyrighted by The New York Times; please respect their terms of service and don't republish puzzle content.