API Documentation
Base URL https://wardatlas.com · JSON everywhere ·
all data endpoints require a key.
Authentication & plans
Pass your key as X-API-Key: adv_live_… (or Authorization: Bearer).
Request a key.
| Plan | Rate limit | Bulk endpoints |
|---|---|---|
| Free | 30 requests/min | Included, flat cost |
| Pro | 600 requests/min | Included, flat cost |
Endpoints
The core call: districts + every official for a location. Optional valid_on=YYYY-MM-DD
(temporal queries) and types= (comma list of district types, e.g. NATIONAL_LOWER,SCHOOL).
Returns { matched_address, accuracy, location, districts, officials[], warnings[], as_of }.
Geocoding: US Census primary with Geocodio fallback; a geocode_fallback warning marks the latter.
Districts only — for consumers that keep their own officials directory. The pivot object:
state, cd, state_upper, state_lower, county, county_district, county_subdivision, place,
school_district, ward, plus extras keyed by OCD division id.
Bulk roster at flat cost — seed a whole state or district set in one call. Weak
ETag on the data version: revalidate with If-None-Match for free 304s.
Full record by stable id (off_…) or any crosswalk identifier —
bioguide:D000624, openstates:…, fec:…. Includes typed phones,
addresses, socials, committees with roles, term dates, and per-field provenance.
Person ids whose data changed after since — refresh only what moved.
The change feed backing it: term_start, term_end, vacancy, contact_changed, official_changed,
redistricting, boundary_updated.
Address suggestions (beta) — house numbers preserved.
Open (no key): the live coverage map — baseline layer counts, activated deep-local areas, committee
coverage, and how to request activation for a new jurisdiction. Every lookup response also carries
local_coverage: deep | baseline for its own area.
Open (no key): database round-trip + current data_version.
The official record
Officials carry a compatibility core (name, first_name, last_name, title, short_title, party, level,
chamber, state, district, phone, email, contact_form, website, twitter, facebook, instagram — strings,
empty when absent, never null) plus:
| Field | Meaning |
|---|---|
official_id | Stable permanent id (off_…) |
identifiers | Crosswalk: bioguide, openstates, govtrack, fec, … |
district_type | NATIONAL_UPPER/LOWER, STATE_EXEC/UPPER/LOWER, COUNTY, LOCAL, SCHOOL, … |
phones[], addresses[] | Typed: capitol vs district office |
committees[] | Name, chamber, role (chair, vice_chair, ranking_member, member) |
contact_form_status | ok / failing / unchecked from nightly liveness checks |
term_start, term_end, next_election, is_vacant | Temporal facts |
provenance | Per field: { source_url, verified_at, confidence } |
Warning codes
approximate_location, multi_district_address, geocode_fallback, geocode_failed,
no_district_coverage, no_state_legislators, district_crosscheck_mismatch, vacant_seat
Freshness & sources
Every response carries as_of. Congress and the 50 states sync weekly from public-domain sources
(unitedstates/congress-legislators, Open States — both CC0); boundaries come from Census TIGER with
redistricting-aware vintages; local officials are AI-collected from official government pages with verbatim
source quotes, validated mechanically, and human-reviewed before publishing. Contact-form URLs are
liveness-checked nightly. Full credits and licenses: Data Sources & Attributions.
Legal
Use of the API is governed by the Terms of Service and Acceptable Use Policy; how we handle data is described in the Privacy Policy.