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

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>"
}

Developer documentation