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.
OpenAPI specification
The whole v1 surface is described by a machine-readable OpenAPI 3.1 document. It needs no key — read it before deciding whether the API is worth integrating.
curl https://api.freedomrankings.com/api/v1/openapi.json
The rate-limit table inside the spec is generated from the same configuration the API enforces, so it cannot drift from what your key actually gets. Point Swagger UI, Redocly, Postman or your generator of choice straight at that URL.
Free access for research
Journalists, academics, students and non-profits can have Pro-level API limits at no cost. The only condition is attribution — a link to FreedomRankings wherever you publish.
We would rather be the number that gets cited than charge the people most likely to cite us. Applications are read by a person, so tell us who you are and what you are working on; there is no automated approval.
Apply for research access →Students and educators: the student research guide covers what to cite, how to cite it, and the discounted and free access routes in one place.
Doing whole-dataset work? Skip the API and take the bulk CSV and JSON downloads instead — they carry the same data with a published data dictionary, and no key or rate limit at all.
Authentication
The base URL is https://api.freedomrankings.com. 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://api.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 |
| GET /api/v1/officials/{id}/stock-trades | STOCK Act PTR trade disclosures, newest first. Filter with ?ticker= or ?type=. 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.