API Documentation v1

Day-level school calendar data for every US public school district. One row per district per day—every school day classified, every break named and typed—for 13,700+ districts covering 44.5 million students.

Ready to get started?

Subscribe and get your API key instantly. $99/month, cancel anytime.

Get API Access

Authentication

All data endpoints require a valid API key, passed as a Bearer token in the Authorization header.

Your API key starts with ssd_live_ and is displayed once after purchase. Store it securely—we store only a SHA-256 hash and cannot recover it for you.

# Include your API key in every request
curl https://api.hazeydata.ai/ssd/v1/districts \
  -H "Authorization: Bearer ssd_live_your_key_here"

Base URL

https://api.hazeydata.ai/ssd/v1/

All endpoints return JSON with Content-Type: application/json unless otherwise noted (the CSV export returns text/csv).

Rate Limits

Each subscription includes 10,000 API calls per month. Usage resets on the 1st of each month. If you exceed the limit, requests return 429 Too Many Requests until the next reset.

Need higher volume? Contact us for enterprise pricing.

List Districts

GET /ssd/v1/districts Auth Required

Search and list US public school districts. Results are ordered by enrollment (largest first).

Query Parameters

Parameter	Type	Description
state	string	Two-letter state code (e.g. `CA`, `TX`). Case-insensitive.
search	string	Search district names. Partial match (e.g. `search=Houston`).
min_enrollment	integer	Filter to districts with at least this many students.
limit	integer	Results per page. Default `100`, max `1000`.
offset	integer	Pagination offset. Default `0`.

Example Request

curl "https://api.hazeydata.ai/ssd/v1/districts?state=FL&min_enrollment=10000" \
  -H "Authorization: Bearer ssd_live_your_key"

Example Response

{
  "total": 32,
  "limit": 100,
  "offset": 0,
  "districts": [
    {
      "district_id": "FL_00870",
      "district_name": "Miami-Dade County Public Schools",
      "state": "FL",
      "enrollment": 334235
    },
    ...
  ]
}

Get School Days

GET /ssd/v1/days Auth Required

The core endpoint. Returns day-level calendar data showing whether each district is in session on each date, with break names and confidence scores.

Query Parameters

Parameter	Type	Description
district_id	string	Filter to a specific district (e.g. `FL_00870`).
state	string	Two-letter state code.
date	string	Exact date (`YYYY-MM-DD`). Returns all districts for that date.
date_from	string	Start of date range (`YYYY-MM-DD`).
date_to	string	End of date range (`YYYY-MM-DD`).
school_year	string	School year (e.g. `2025-2026`).
limit	integer	Max rows. Default `365`, max `5000`.

Tip: The most common query pattern is date=2025-12-25&state=FL — "which Florida districts are off on Christmas?" Or district_id=FL_00870&date_from=2025-12-20&date_to=2026-01-05 for a single district's winter break window.

Example Request

# What does spring break look like in Texas?
curl "https://api.hazeydata.ai/ssd/v1/days?state=TX&date_from=2026-03-09&date_to=2026-03-20" \
  -H "Authorization: Bearer ssd_live_your_key"

Example Response

{
  "total": 2,
  "days": [
    {
      "district_id": "TX_04302",
      "district_name": "Houston Independent School District",
      "state": "TX",
      "enrollment": 189854,
      "date": "2026-03-09",
      "school_year": "2025-2026",
      "is_in_session": 0.0,
      "day_type": "BREAK",
      "break_name": "Spring Break",
      "confidence": 0.92,
      "source_method": "markitdown_extraction"
    },
    ...
  ]
}

Search Breaks

GET /ssd/v1/breaks Auth Required

Search specifically for school breaks, holidays, and non-school days (excluding weekends). Useful for finding when spring break, winter break, or teacher workdays fall across districts.

Query Parameters

Parameter	Type	Description
state	string	Two-letter state code.
break_name	string	Search break names. Partial match (e.g. `Spring`, `Thanksgiving`).
date_from	string	Start of date range.
date_to	string	End of date range.
limit	integer	Max rows. Default `100`, max `1000`.

Example

# When is spring break in California?
curl "https://api.hazeydata.ai/ssd/v1/breaks?state=CA&break_name=Spring" \
  -H "Authorization: Bearer ssd_live_your_key"

Export CSV

GET /ssd/v1/export Auth Required

Bulk download school calendar data as a CSV file. Ideal for loading into a data warehouse, spreadsheet, or analytics tool.

Query Parameters

Parameter	Type	Description
school_year	string	School year to export. Default `2025-2026`.
state	string	Two-letter state code. Omit for all states.
limit	integer	Max rows. Default `50000`, max `100000`.

Example

# Download all Florida data as CSV
curl "https://api.hazeydata.ai/ssd/v1/export?state=FL&school_year=2025-2026" \
  -H "Authorization: Bearer ssd_live_your_key" \
  -o florida_2025_2026.csv

Tip: Returns text/csv with a Content-Disposition header suggesting a filename. Pipe directly to a file with -o or load into pandas with pd.read_csv(url, ...).

Sample Districts (Free)

GET /ssd/v1/sample/districts No Auth Required

Free endpoint—no API key needed. Returns the top 100 districts by enrollment. Use this to preview the data model before subscribing.

Example

# No auth required
curl "https://api.hazeydata.ai/ssd/v1/sample/districts"

Data Model

District Object

Field	Type	Description
district_id	string	Unique identifier. Format: `{STATE}_{NCES_ID}` (e.g. `TX_04302`).
district_name	string	Full district name.
state	string	Two-letter state code.
enrollment	integer	Total student enrollment.

School Day Object

Field	Type	Description
district_id	string	District identifier.
date	string	Calendar date (`YYYY-MM-DD`).
school_year	string	Academic year (e.g. `2025-2026`).
is_in_session	float	`1.0` = full school day, `0.5` = half day, `0.0` = no school. See Confidence Scores.
day_type	string	Category: `SCHOOL_DAY`, `WEEKEND`, `BREAK`, `HOLIDAY`, `TEACHER_WORKDAY`, `HALF_DAY`, `SUMMER`.
break_name	string \| null	Name of break/holiday if applicable (e.g. `Spring Break`, `Thanksgiving`, `Martin Luther King Jr. Day`).
confidence	float	Confidence score from `0.0` to `1.0`. See Confidence Scores.
source_method	string	How this data was obtained: `markitdown_extraction`, `pdf_extraction`, `deterministic` (weekends), `inferred`.

School Years

The API exposes a rolling 3-year window of school calendar data:

School Year	Period	Status
2024-2025	Aug 2024 – Jun 2025	Previous year (historical)
2025-2026	Aug 2025 – Jun 2026	Current year (most complete)
2026-2027	Aug 2026 – Jun 2027	Next year (as published by districts)

The oldest year drops off each September when a new school year begins. Subscribers building historical archives from the API accumulate data over time—the rolling window ensures the most relevant data is always fresh.

Confidence Scores

Every row in the database carries a confidence score indicating how reliable the classification is.

Range	Meaning	Examples
0.90 – 1.00	High confidence. Extracted directly from an official district calendar.	Named holidays, published break dates, first/last day of school.
0.70 – 0.89	Good confidence. Extracted from a PDF or secondary source.	PDF calendars with OCR, aggregator sites.
0.50 – 0.69	Moderate. Inferred from surrounding data or state-level patterns.	School days between known breaks, district-reported start/end dates only.
1.00 (deterministic)	Weekends and summer days classified by rule, not extraction.	Saturdays, Sundays, July.

Note: is_in_session is a float, not a boolean. Values of 0.5 represent half-days (early release, parent-teacher conference days, etc.). Filter with is_in_session > 0 to include half-days as "in session," or is_in_session = 1.0 for full days only.

Error Codes

Status	Meaning
200	Success.
400	Bad request. Check your query parameters.
401	Unauthorized. Missing or invalid API key. Double-check your `Authorization: Bearer ssd_live_...` header.
403	Forbidden. Subscription cancelled or suspended.
429	Rate limit exceeded. Resets on the 1st of the month.
500	Server error. Let us know if this persists.

Error responses include a JSON body with an error field describing the issue:

{
  "error": "Monthly rate limit exceeded (10000 calls). Resets on the 1st."
}

Support

Having trouble connecting? Something not working as expected? Email the founder directly—you'll get a real human response, usually within a few hours.

[email protected]

Include your API key prefix (first 16 characters) so we can look up your account quickly.

Common first-request issues: Getting a 401? Make sure you're including the full key (starts with ssd_live_) in the header as Authorization: Bearer ssd_live_.... The most common mistake is a missing Bearer prefix or an extra space.

Start building with real school calendar data

13,700+ districts. 44.5 million students. Day-level granularity. $99/month.

Get API Access