Authentication
Choose the open or keyed DistrictFacts API host and send an API key safely.
The open www.districtfacts.com host needs no key. The api.districtfacts.com host accepts existing keys in Authorization: Bearer or X-API-Key. Keys begin with dfk_live_. Never put a key in a URL: URLs reach logs, and the service refuses and revokes a valid query-string key.
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))Authentication errors
A missing or invalid key returns 401. A revoked key or suspended developer account returns 403. Errors use application/problem+json.
{
"type": "https://www.districtfacts.com/developers/errors#missing_key",
"title": "API key required",
"status": 401,
"detail": "Send an API key in Authorization: Bearer <key> or X-API-Key.",
"request_id": "<request UUID>"
}