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. An optional extra serves everything as 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.

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.

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.