API documentation v1

Day-level school calendar data for every US public school district — one row per district per day, every break named and typed, every row scored for confidence.

12,023 districts across 49 states, DC, Guam, Puerto Rico and the US Virgin Islands (53 jurisdictions) for 2026-27. Hawaii is not yet covered for 2026-27. A rolling three-year window. Flat $99/month — get a key, then read on.

Overview

Responses are read-only JSON (the CSV export returns text/csv), versioned under /v1. Every calendar row carries a source_method and a confidence so you always know whether a date was read from a real calendar or estimated. It's the same archive that powers this site.

Authentication

All data endpoints require a valid API key, passed as a Bearer token in the Authorization header. Keys start with ssd_live_ and are shown once, after purchase and in your account — we store only a SHA-256 hash and can't recover it for you.

Base URL

All endpoints return application/json unless noted (the CSV export returns text/csv).

Rate limits

Each subscription includes 50,000 API calls per month, resetting on the 1st. Exceed it and requests return 429 Too Many Requests until reset. Track usage live in your account dashboard. Need higher volume? Contact us for enterprise pricing.

GET /districts auth

Search and list districts, ordered by enrollment (largest first).

GET /days auth

The core endpoint — day-level rows showing whether each district is in session on each date, with break names and confidence.

GET /breaks auth

Just the breaks, holidays, and non-school days (weekends excluded) — for "when is spring break across these districts?"

Key scope. A trial key is restricted to one state and one school year. An out-of-scope request returns 403 naming the restriction — it is never silently narrowed to what the key can see (Issue #211).

GET /export auth

Bulk CSV, same fields as /days, flattened for a warehouse or spreadsheet.

Returns text/csv with a suggested filename — pipe with -o or load with pd.read_csv().

GET /sample no auth

Free — no key required. The top 100 districts by enrollment, plus calendar: one full district calendar for 2026-27 in the /days row shape, every day labeled confirmed or estimated by its source_method (table). Every other calendar needs a key.

Data model

School day object

source_method: confirmed or estimated

There is no estimated field. Every day carries a source_method; this table is the one definition of which labels are confirmed and which are estimated.

unresolved is not a label: it marks the no-basis sentinel described below.

state_composite: read from the state education agency's own published table of district calendars (2026-27: SC, KY, WA). Labelled as read from a state table, not from the district's calendar.

state_majority_v2: for a district we haven't read a calendar for, each school weekday is what most of its state's calendar-read districts do that day. It is used only in states with at least 5 such districts, and only where the method's confidence passed a held-out check (2026-27: TX, CA, IL, MA, MI, NJ, NY, PA).

national_breaks_v1: a date marked out of session because nearly every state is off that day: Labor Day, Thanksgiving and the Friday after, December 24 to January 1, and Memorial Day. It is used only for districts in states where we have too few calendars to estimate the whole year, and only on a date that was an estimated school day. Every other date of the district's year is unchanged.

School years

The oldest year drops off each September. Requests outside the window return 403.

Confidence scores

confidence is a 0-1 score reflecting the source behind each day; filter on source_method (table), not on confidence.

On state_majority_v2 rows, confidence is a measured probability: the share of days the method got right, on districts held out of the fit, at the same level of agreement among the state's districts. A 0.97 day was right about 97 times in 100. In Texas it runs from 0.548 (the state split nearly in half) to 0.998 (every district agrees).

On national_breaks_v1 rows, confidence is measured: the share of calendar-read districts that were off on that date when their own state was left out of the call. 2026-27: Labor Day 0.983, Thanksgiving and the Friday after 0.989, December 24 to January 1 and Memorial Day 0.991. A date under 0.95 is not written (Martin Luther King Jr. Day measured 0.931). For every other method, confidence is not a measured probability.

Errors

Support

Something not working? Email us — you'll get a real human, usually within a few hours. Include your API key prefix (first 16 characters) so we can find your account. Most first-request issues are a missing Bearer prefix in the header.

Email support →