Homeschool Fox

Homeschool Fox
Compliance API

Overview

The Homeschool Fox Compliance API is a read-only HTTP API that exposes structured, versioned U.S. state homeschool compliance data — required hours, days, subjects, assessment rules, ESA programs, tax credits, and source citations for all 50 states + DC.

What it is

  • A stable contract over data that's already public but is otherwise tedious to maintain — the value is the editorial process behind it, not the bits.
  • Versioned per-state with cryptographically anchored history (every version is backed by a git commit on data/compliance/states/*.yml).
  • Point-in-time queryable: ?as_of=2026-03-01 returns what the data looked like on that date.
  • Diffable: the change feed lets integrators sync only what's moved since their last poll.

What it is not (in v1)

  • Not write-capable. Read endpoints only.
  • Not metered or billed. The free tier is the only tier today — 60 requests a minute, every endpoint. There is no paid plan and no usage billing.
  • Not for user-scoped data. Student records, activities, goals, etc. are not exposed here. The compliance API only covers reference data about the 51 jurisdictions.
  • Not webhooks. Pull-based change feed only — push notifications are a roadmap item.

Getting access

Keys are self-serve and free at /developers. We ask one thing in return: if you publish anything derived from this data, credit Homeschool Fox with a visible link back.

Audience

  • Our own Rails app (eventual internal consumer).
  • Third-party homeschool apps that don't want to scrape DOE pages themselves.
  • Researchers and analysts who want a clean, citable, queryable view of state homeschool law over time.

Architecture in one paragraph

The canonical source of truth is YAML files committed to the repo at data/compliance/states/<abbr>.yml. A boot-time service (ComplianceData) reads + schema-validates them. A compliance:reindex_history rake task walks git log for those files and writes one row per version into a compliance_snapshots table. The API reads from ComplianceData for current data and from compliance_snapshots for historical (as_of / pinned-version) lookups. Auth is API keys with constant-time hash comparison; rate limiting is via rack-attack, keyed per-key.