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.json

curl

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.json

curl

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 f53a2c4796667e78c01257a50cb3c10d5d0e60027627b8577b57f9bb18663f28

4. Use the keyed host

curl

curl --fail --silent --show-error \
  -H "Authorization: Bearer $DISTRICTFACTS_API_KEY" \
  https://api.districtfacts.com/data/v1/index.json

curl

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.

Developer documentation