Make your first request
Make a first DistrictFacts API request, read a district record, and verify its hash.
Start with the open host. Every numbered step includes the relevant response.
1. Request the API index
curl
curl --fail --silent --show-error \
https://www.districtfacts.com/data/v1/index.jsoncurl
const response = await fetch("https://www.districtfacts.com/data/v1/index.json");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
interface ApiIndex {
api_version: string;
states: Array<{ state: string; name: string; api_url: string }>;
}
const index = (await response.json()) as ApiIndex;
console.log(index.states.length, "published states");JavaScript
const response = await fetch("https://www.districtfacts.com/data/v1/index.json");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data);Python
import json
from urllib.request import Request, urlopen
request = Request("https://www.districtfacts.com/data/v1/index.json")
with urlopen(request, timeout=30) as response:
data = json.load(response)
print(json.dumps(data, indent=2))Relevant response excerpt
{ "api_version": "1.8.0", "states": [{ "state": "de", "api_url": "/data/v1/de/districts.json" }] }
Omitted: generated_at, licence, attribution, docs, changelog, version_policy, excluded, other state fields, and other states.2. Read one district
curl
curl --fail --silent --show-error \
https://www.districtfacts.com/data/v1/de/districts/capital-school-district.jsoncurl
const response = await fetch("https://www.districtfacts.com/data/v1/de/districts/capital-school-district.json");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
interface DistrictRecord {
api_version: string;
state: string;
leaid: string | null;
slug: string;
name: string;
measures: Array<{ status: "published" | "withheld" | "not_collected"; key: string }>;
schools: Array<{ code: string; name: string }>;
line_items: Array<{ code: string; label: string }>;
licence_status: "final" | "under_review";
}
const district = (await response.json()) as DistrictRecord;
console.log(district.name, `${district.measures.length} measures`);JavaScript
const response = await fetch("https://www.districtfacts.com/data/v1/de/districts/capital-school-district.json");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data);Python
import json
from urllib.request import Request, urlopen
request = Request("https://www.districtfacts.com/data/v1/de/districts/capital-school-district.json")
with urlopen(request, timeout=30) as response:
data = json.load(response)
print(json.dumps(data, indent=2))Relevant response excerpt
{ "name": "Capital School District", "leaid": "1000190", "measures": [{ "status": "published", "key": "edstats_revenue_per_pupil", "period": "2024-2025", "value": 2592280, "unit": "cents per pupil", "source_id": "de-edstats-fy25" }] }
Omitted: other top-level fields, other measures, and the selected measure’s label, category, definition, and locator.3. Verify one district record
Hash the raw district-record bytes against that record's directory-row sha256. A mismatch means the bytes are not the indexed release: do not use or store them.
curl
directory=$(mktemp)
record=$(mktemp)
curl --fail --silent --show-error https://www.districtfacts.com/data/v1/de/districts.json -o "$directory"
expected=$(jq -r '.[] | select(.slug == "capital-school-district") | .sha256' "$directory")
curl --fail --silent --show-error https://www.districtfacts.com/data/v1/de/districts/capital-school-district.json -o "$record"
actual=$(shasum -a 256 "$record" | awk '{print $1}')
[ "$actual" = "$expected" ] || { echo "record hash mismatch" >&2; exit 1; }
echo "verified capital-school-district $actual"curl
import { createHash } from "node:crypto";
interface DirectoryEntry {
slug: string;
name: string;
sha256: string;
api_url: string;
}
const base = "https://www.districtfacts.com";
const directory = (await fetch(base + "/data/v1/de/districts.json").then(response => response.json())) as DirectoryEntry[];
const entry = directory.find(record => record.slug === "capital-school-district");
if (!entry) throw new Error("District not found");
const body = Buffer.from(await fetch(base + entry.api_url).then(response => response.arrayBuffer()));
const actual = createHash("sha256").update(body).digest("hex");
if (actual !== entry.sha256) throw new Error("Record hash mismatch");
console.log("verified", entry.slug, actual);JavaScript
import { createHash } from "node:crypto";
const base = "https://www.districtfacts.com";
const directory = await fetch(base + "/data/v1/de/districts.json").then(response => response.json());
const entry = directory.find(record => record.slug === "capital-school-district");
const body = Buffer.from(await fetch(base + entry.api_url).then(response => response.arrayBuffer()));
const actual = createHash("sha256").update(body).digest("hex");
if (actual !== entry.sha256) throw new Error("Record hash mismatch");
console.log("verified", entry.slug, actual);Python
import hashlib
import json
from urllib.request import urlopen
base = "https://www.districtfacts.com"
with urlopen(base + "/data/v1/de/districts.json") as response: directory = json.load(response)
entry = next(record for record in directory if record["slug"] == "capital-school-district")
with urlopen(base + entry["api_url"]) as response: body = response.read()
actual = hashlib.sha256(body).hexdigest()
if actual != entry["sha256"]: raise ValueError("Record hash mismatch")
print("verified", entry["slug"], actual)verified capital-school-district f53a2c4796667e78c01257a50cb3c10d5d0e60027627b8577b57f9bb18663f284. Use the keyed host
curl
curl --fail --silent --show-error \
-H "Authorization: Bearer $DISTRICTFACTS_API_KEY" \
https://api.districtfacts.com/data/v1/index.jsoncurl
const response = await fetch("https://api.districtfacts.com/data/v1/index.json", {
headers: { Authorization: `Bearer ${process.env.DISTRICTFACTS_API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
interface ApiIndex {
api_version: string;
states: Array<{ state: string; name: string; api_url: string }>;
}
const index = (await response.json()) as ApiIndex;
console.log(index.states.length, "published states");JavaScript
const response = await fetch("https://api.districtfacts.com/data/v1/index.json", {
headers: { Authorization: `Bearer ${process.env.DISTRICTFACTS_API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data);Python
import os
import json
from urllib.request import Request, urlopen
request = Request("https://api.districtfacts.com/data/v1/index.json", headers={"Authorization": f"Bearer {os.environ['DISTRICTFACTS_API_KEY']}"})
with urlopen(request, timeout=30) as response:
data = json.load(response)
print(json.dumps(data, indent=2))Relevant response excerpt
{ "api_version": "1.8.0", "states": [{ "state": "de", "api_url": "/data/v1/de/districts.json" }] }
The keyed host returns the same response bytes as the open host.