advent-of-code-data 0.0.2

Advent of Code API for submitting answers and getting inputs
Documentation

advent-of-code-data

A Rust library for fetching puzzle inputs and submitting answers to Advent of Code.

Quick Start

Install the crate:

$ cargo add advent-of-code-data

Fetch a puzzle input and submit an answer:

use advent_of_code_data::{get_input, submit_answer, Day, Part, Year};

fn main() -> anyhow::Result<()> {
    let input = get_input(Day(1), Year(2025))?;
    println!("{}", input);

    submit_answer(42.into(), Part::One, Day(1), Year(2025))?;
    Ok(())
}

Before running, you'll need to set your Advent of Code session cookie. See the Setup section below.

Setup

Your puzzle inputs are personalized. To fetch them, you need your Advent of Code session cookie.

Finding your Session Cookie

  1. Go to https://adventofcode.com and log in
  2. Open your browser's developer tools (F12)
  3. Navigate to Application → Storage → Cookies
  4. Find the session cookie and copy its value

Configuring Your Session

The fastest way to get started is to set the AOC_SESSION environment variable:

export AOC_SESSION=your_session_cookie_here

Alternatively, you can create a configuration file. See the Configuration section for details.

Configuration

By default, puzzle data is cached locally and encrypted. You only need to specify your session cookie.

Using Environment Variables

Set your session with the AOC_SESSION environment variable:

export AOC_SESSION=your_session_cookie_here

Other environment variables are available for advanced use:

  • AOC_PASSPHRASE: Custom passphrase for encryption (uses hostname by default)
  • AOC_PUZZLE_DIR: Custom directory for caching puzzles
  • AOC_SESSIONS_DIR: Custom directory for session data
  • AOC_CONFIG_PATH: Path to a specific config file (disables all other config locations)

Using a Configuration File

Create a aoc_settings.toml file in one of these locations:

Linux:

  • $XDG_CONFIG_HOME/advent_of_code_data/aoc_settings.toml
  • $HOME/.aoc_settings.toml
  • .aoc_settings.toml (current directory)

macOS:

  • $HOME/Library/Application Support/com.smacdo.advent_of_code_data/aoc_settings.toml
  • $HOME/.aoc_settings.toml
  • .aoc_settings.toml (current directory)

Windows:

  • %APPDATA%/com.smacdo.advent_of_code_data/config/aoc_settings.toml
  • %USERPROFILE%/.aoc_settings.toml
  • .aoc_settings.toml (current directory)

Example configuration file:

[client]
session_id = "your_session_cookie_here"

Configuration is loaded in this order, with later sources overriding earlier ones:

  1. User configuration directory or the user's home directory
  2. Current directory (.aoc_settings.toml)
  3. Environment variables (highest priority)

This lets you keep global settings in your user directory, override them with project-specific settings, and override those with environment variables.

Storing Puzzles in Your Project

If you want to cache puzzles directly in your project (instead of the system cache), set both puzzle_dir and a custom passphrase:

[client]
session_id = "your_session_cookie_here"
puzzle_dir = "./puzzles"
passphrase = "your_custom_passphrase"

Important: Do not commit your passphrase or session cookie to version control. Add your config file to .gitignore if it contains secrets.

Troubleshooting

Invalid or Expired Session

If you get a BadSessionId error, your session cookie has expired or is incorrect.

Solution:

  • Log in to https://adventofcode.com in your browser to refresh your session
  • Get a new session cookie and update your AOC_SESSION environment variable or config file

Puzzle Not Available Yet

AoC puzzles unlock at midnight EST each day. If you try to fetch a puzzle before it's released, you'll get a PuzzleNotFound error.

Solution:

Answer Submission Rate Limited

If you submit too many incorrect answers, AoC temporarily blocks further submissions and returns a SubmitTimeOut error.

Solution:

  • Wait the amount of time indicated in the error message before trying again
  • Consider testing your solution logic locally before submitting