nytimes-games

Unofficial Python client and API for the New York Times Games APIs (Wordle, Connections, Strands, Spelling Bee, Letter Boxed and the Daily, Mini, Midi and Bonus crosswords). Responses are validated with Pydantic models.

This repo contains:

nytgames/: the Python library, published on PyPI as nytimes-games
api/: a FastAPI service built on the library, deployed to Cloud Run

Puzzles are available without logging in. Your game progress and stats require your NYT session cookie (NYT-S) from a logged in nytimes.com browser session.

Library

pip install nytimes-games

The package installs as nytimes-games and is imported as nytgames.

from nytgames import NYTGamesClient, spelling_bee_hints

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

client.wordle("2025-06-12").solution
client.connections("2025-06-12").categories
client.letter_boxed("2026-10-03").sides
client.crossword()                        # today's daily crossword
client.crossword("mini", "2025-06-12")    # daily, mini, midi or bonus
client.crossword_oracle("midi")           # current and next puzzle IDs
client.crossword_game(24287)              # your saved progress on a puzzle
client.crossword_puzzles("daily", date_start="2025-06-01", date_end="2025-06-30")
client.player_stats().stats.connections.current_streak   # your stats for every game

puzzle = client.spelling_bee_puzzle("2026-10-03")   # any date from 2018-05-06
spelling_bee_hints(puzzle)                          # Spelling Bee Forum style hints
client.spelling_bee_puzzles()   # {print_date: puzzle} from the game page, about two weeks

cookies can be a dict, a Cookie header string, or a list of cookie objects with name and value keys, such as a JSON export from the Cookie-Editor browser extension.

HTTP errors from NYT are raised as NYTGamesHTTPError, a subclass of requests.HTTPError: NYTGamesAuthenticationError for 401 and 403 (usually a missing or expired NYT-S cookie) and NYTGamesNotFoundError for 404 (e.g. a date with no puzzle).

API

Each endpoint calls NYT with the cookies sent to the API:

curl -H "Cookie: NYT-S=..." http://localhost:8080/crosswords/mini/today

Interactive docs are served at /docs and /redoc.

Endpoints

Route	Upstream NYT endpoint
`GET /connections/{date}`	`svc/connections/v2/{date}.json`
`GET /crosswords/daily/today`	`svc/crosswords/v6/puzzle/daily.json`
`GET /crosswords/daily/{date}`	`svc/crosswords/v6/puzzle/daily/{date}.json`
`GET /crosswords/mini/today`	`svc/crosswords/v6/puzzle/mini.json`
`GET /crosswords/mini/{date}`	`svc/crosswords/v6/puzzle/mini/{date}.json`
`GET /crosswords/bonus/{date}`	`svc/crosswords/v6/puzzle/bonus/{date}.json`
`GET /crosswords/puzzles`	`svc/crosswords/v3/puzzles.json`
`GET /crosswords/midi/today`	`svc/crosswords/v6/puzzle/midi.json`
`GET /crosswords/midi/{date}`	`svc/crosswords/v6/puzzle/midi/{date}.json`
`GET /crosswords/oracle/{publish_type}`	`svc/crosswords/v2/oracle/{publish_type}.json` (current and next puzzle; `daily`, `midi`, `mini`)
`GET /crosswords/game/{game_id}?publish_type=daily`	`svc/games/state/crossword_{publish_type}/latests?puzzle_ids={game_id}` (your saved progress)
`GET /letter-boxed/{date}`	`svc/letter-boxed/v1/{date}.json`
`GET /player/stats`	`svc/games/state/wordleV2/latests?puzzle_ids=0` (your stats for every game)
`GET /spelling-bee`	Scraped from `puzzles/spelling-bee`
`GET /spelling-bee/latest`	`svc/games/state/spelling_bee/latests` (up to 30 `puzzle_ids`)
`GET /spelling-bee/{date}`	`svc/spelling-bee/v1/{date}.json` (from 2018-05-06)
`GET /spelling-bee/{date}/hints`	Computed from the puzzle above
`GET /strands/{date}`	`svc/strands/v2/{date}.json`
`GET /wordle/latest`	`svc/games/state/wordleV2/latests`
`GET /wordle/{date}`	`svc/wordle/v2/{date}.json`

Upstream errors (e.g. a 404 for a date with no puzzle) are returned with the upstream status code.

Development

pip install -e ".[api,test]"
pytest
cd api && uvicorn main:app --reload --port 8080

api/build.sh builds the image locally. api/develop.sh runs the deployed image with the repo mounted and auto-reload enabled.

Deployment

api/cloudbuild.yaml builds the image, pushes it to Artifact Registry (us-central1-docker.pkg.dev/$PROJECT_ID/docker/nytgames) tagged latest and $SHORT_SHA, and deploys it to the nytgames Cloud Run service in us-central1.

License

MIT. This project is not affiliated with The New York Times.

Metadata

Release files for nytimes-games 0.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nytimes-games 0.3.2
File	Size	Uploaded
nytimes_games-0.3.2.tar.gz	19.7 kB	Oct 4, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for nytimes-games 0.3.2
File	Interpreter	ABI	Platform	Reset
nytimes_games-0.3.2-py3-none-any.whl 13.0 kB Oct 4, 2026	Python 3	none	any	Details

Total release size: 32.7 kB

Release files / nytimes_games-0.3.2.tar.gz

Download URL	nytimes_games-0.3.2.tar.gz
Size	19.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`b95a55171229dde9d5eb2215bd115486a525d712bd8de96b4e6fd58f6961e0f6`
BLAKE2b-256 checksum How to use checksums	`f95c92ea6f7360b9e9dc888b3a6bf0fc3956fcfda1e18cfddd6c959924f6db9e`
Upload date	Oct 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/lukwam/nytimes-games
Publishing commit: github.com/lukwam/nytimes-games/tree/3ee8d9994d518682ef489d77bc15fcf9bbaa4c24

Workflow

Publishing configuration: github.com/lukwam/nytimes-games/blob/3ee8d9994d518682ef489d77bc15fcf9bbaa4c24/.github/workflows/publish.yml
Publishing logs: github.com/lukwam/nytimes-games/actions/runs/37186338508/attempts/1

Artifact

Subject: nytimes_games-0.3.2.tar.gz
SHA-256 checksum: b95a55171229dde9d5eb2215bd115486a525d712bd8de96b4e6fd58f6961e0f6 Verifying attestations

Release files / nytimes_games-0.3.2-py3-none-any.whl

Download URL	nytimes_games-0.3.2-py3-none-any.whl
Size	13.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7772706f5fedd4236f6d1a9f1b88b96542a58af9f549e341d7af14c76f850aaf`
BLAKE2b-256 checksum How to use checksums	`e2df26cd93fccd066051fc3797580fbc6c219b84810893bf7486c1a675b9e958`
Upload date	Oct 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/lukwam/nytimes-games
Publishing commit: github.com/lukwam/nytimes-games/tree/3ee8d9994d518682ef489d77bc15fcf9bbaa4c24

Workflow

Publishing configuration: github.com/lukwam/nytimes-games/blob/3ee8d9994d518682ef489d77bc15fcf9bbaa4c24/.github/workflows/publish.yml
Publishing logs: github.com/lukwam/nytimes-games/actions/runs/37186338508/attempts/1

Artifact

Subject: nytimes_games-0.3.2-py3-none-any.whl
SHA-256 checksum: 7772706f5fedd4236f6d1a9f1b88b96542a58af9f549e341d7af14c76f850aaf Verifying attestations