Skip to content
CivicGrid
Developer documentation

Civic data, without the scraping.

A read-only REST API for US city leadership. Every request uses an API key from your dashboard.

Quick start

  1. Sign in and create a key on your dashboard.
  2. Send it as a bearer token on every request.
  3. Read pagination.total to page through results.
Example request (replace the key with your own)
curl "https://api.civicgrid.org/cities?state=MD&limit=10" \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

Interactive OpenAPI reference: api.civicgrid.org/docs ↗

Rate limits

TierPer dayPer minuteFull export
Free10010No
Starter10,000100Yes
Pro100,000500Yes

Day limits are a rolling 24-hour window. Over the limit, requests return HTTP 429 with a retry time. Full-export endpoints return HTTP 403 with upgrade_required on the Free tier.

Endpoints

  • GET/citiesCities with their current leader. Filters: state, city_type, min_pop, max_pop, search. Paginate with limit and offset (up to 25 per page on Free, 500 on paid tiers).
  • GET/cities/allStarter & ProEvery city with its current leader in one response.
  • GET/cities/{id}One city with provenance, its published leadership history, and reviewer-published changes.
  • GET/leaders/currentCurrent leaders. Filters: party, state. Paginate with limit and offset (up to 25 per page on Free).
  • GET/leaders/exportStarter & ProEvery leader, current and former, grouped by city.
  • GET/statsAggregate counts.
  • GET/stats/statesPer-state city counts and population.
  • GET/stats/states/{state_code}One state's aggregates.
  • GET/healthLiveness and database readiness. No key required.

City record fields

Returned by /cities and /cities/all. Fields marked verification tell you how fresh a record is.

city, state_code, state_name, county
Where the city is.
population
Census Bureau estimate. null when no figure is on file; 0 is a real value.
leader_name, leader_title
The current published leader and their exact title, e.g. Mayor or Village President.
governance_typeverification
mayor, council_manager, select_board, town_administrator, commission, unknown, or null if not classified.
leader_last_verified_atverification
When the current leader was last confirmed against a source. null if never.
last_verified_methodverification
human (a reviewer confirmed it) or automated (matched the official page).
verification_source_urlverification
The source used for that confirmation.
last_checked_atverification
The latest check attempt of any outcome. A failed check never moves leader_last_verified_at.
last_check_resultverification
confirmed, under_review (a possible change awaits review), or check_failed.
official_leader_pageverification
The city's official leadership page, when one has been found.