Developers
FreedomRankings API
A REST API over the same civic dataset that powers the site — state freedom rankings, official profiles, voting records, and campaign finance — returned as JSON. API access is included with every plan and scales with your subscription.
Authentication
Every request must carry your API key as a bearer token. Create and manage keys from your profile. Keep keys secret — they grant your plan’s access. The full key is shown only once at creation.
curl https://freedomrankings.com/api/v1/rankings \ -H "Authorization: Bearer fr_live_your_key_here"
Plans & rate limits
| Plan | Requests / day | Burst / min | Active keys | Max page size |
|---|---|---|---|---|
| Citizen | 100 | 20 | 1 | 50 |
| Supporter | 1,000 | 60 | 3 | 100 |
| Pro | 10,000 | 120 | 10 | 200 |
Responses carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. Exceeding a window returns 429 with Retry-After. Compare plans →
Endpoints
| Endpoint | Description | Min plan |
|---|---|---|
| GET /api/v1/me | Your key’s tier, quota, and scopes. | Citizen |
| GET /api/v1/rankings | All states ranked, with category scores. Paginated. | Citizen |
| GET /api/v1/states/{id} | One state by two-letter id, with category details. | Citizen |
| GET /api/v1/officials/{id} | Core profile, role, scores, committees. | Supporter |
| GET /api/v1/officials/{id}/votes | Vote records, newest first. Paginated. | Supporter |
| GET /api/v1/compare?states=CA,TX | Compare states side by side. | Supporter |
| GET /api/v1/officials/{id}/finance | Net-worth band, total raised, donor totals. | Pro |
| GET /api/v1/officials/{id}/donors | Full itemized donor list. Paginated. | Pro |
Conventions
- Success responses are
{ "data": …, "meta": … }; errors are{ "error": "code", "message": … }. - List endpoints take
?page=and?pageSize=(clamped to your plan’s max). - Large integers (net worth, totals) are returned as strings to stay JSON-safe.
- Calling an endpoint above your plan returns
403 scope_not_allowedwith therequiredTier.