Election Atlas

What's in the atlas: row counts by country and level, with the vintage of each layer.

When each upstream dataset was last fetched and checked, what period it describes (vintage), how often it is re-checked, and whether it is overdue. Includes the recent refresh history.

Who represents a place: members of the U.S. House and Senate, state legislators and the mayor, with contacts. Give a geography `id` (a congressional district, state, city 'us:place:...', county, town or ZIP 'us:zcta:...') or a point (`lat`, `lon`; geocode an address first). For a city, county or ZIP that spans several districts, each representative comes with `share` = share of that area's 2020 residents in the district; for an exact answer use a point. Members listed are those serving now (119th Congress, until January 3, 2027); the districts are the 120th Congress maps elected November 3, 2026. In states that redrew for 2026 (AL, CA, FL, LA, NC, OH, TN, TX, UT) a representative's `note` says they were elected under the previous map. A district with no member is vacant. State legislators (state_legislators=True, except for a whole state, where pass it explicitly) come from Open States; members in states that redrew legislative maps for 2026 (MI, MN, MS) carry a similar note. Mayors (local=True), of cities and, where towns and townships are the local government (NJ, PA, NY, New England, MI, MN, WI), of those too, come from Open States (larger cities, while their term runs) or, failing that, Wikidata (one current head of government, in office since 2010; their `note` says to confirm on the city's website). Sources: the @unitedstates congress-legislators dataset (CC0), Open States (public domain), Wikidata (CC0). US only for now.

Polygon boundaries as a GeoJSON FeatureCollection (EPSG:4326, RFC 7946 winding), for drawing dashboard maps. id: the geography to draw, e.g. 'us:county:34013'. children_level: draw everything at that level inside it instead, e.g. every 'precinct' in a county or state, every 'county' in a state, every 'polling_division' in a riding, or every 'precinct' overlapping a congressional district (any share; use related_geographies for shares). detail: 'high' (~10 m), 'medium' (~50 m, default) or 'low' (~200 m). Neighbouring shapes from the same source share identical edges at every detail level. clip_to_land: trim open water (ocean, bays, Great Lakes) using the state/province shoreline outline (default true; inland lakes are not trimmed; shorelines are generalized to ~1:500k, widened ~200 m so land isn't cut); false gives legal extents. include_districts: add each feature's congressional / state senate / state house district holding the largest share of its population. Feature properties: id, level, code, name, parent_id, region, population (2020 Census for precincts and towns, latest estimate for counties and states), vintage and source_id (2020 Census VTDs have source_id 'us-census-vtd-2020'; current precincts don't), shape_source. Small results come back inline as `geojson`. Larger ones are not returned inline (they'd flood the conversation): the hosted service returns a short-lived `download_url` (fetch it with curl into your project); a local server writes the file to its own export folder and returns `file` (copy it into your project). Page big selections with offset/limit (max 5000 features).

Full record for one geography: attributes, parent chain up to the country, child counts by level, and the source it came from (licence, vintage, last fetched).

Geographies directly under `id` (state -> counties and districts, county -> precincts and towns, province -> ridings). Filter with `level`; page with limit/offset (max 1000).

Every geography at one level, optionally within one state/province, e.g. all congressional districts in 'NJ' or all federal ridings in 'ON'. Page with limit/offset (max 1000).

Which geographies contain a point: precinct, county, town, congressional and state legislative districts in the US; province, census division and subdivision, federal riding, polling divisions and provincial districts in Canada. Point-in-polygon on stored boundaries (simplified to ~10 m, so a point within ~10 m of a line can land on either side). Geocode an address to lat/lon first. levels: restrict to some levels (default: all except 'vtd_2020'). If a point is just outside every shape of a level that its state/province has (a pier, a beach, a gap between precinct files), it is matched to the nearest shape of that level in the same state/province within ~1 km and flagged approximate=true with distance_m. not_found lists levels the state/province has data for but no shape here; no_data lists levels with no boundaries there at all (e.g. Nebraska has no state house; Ontario has no provincial polling divisions here).

Geographies at `level` whose internal point is closest to (lat, lon). This is a nearest-point approximation, not point-in-polygon. To find the geography containing a point, use locate_point.

Links between geographies that overlap without nesting, with population shares. Districts: for a precinct, county, town, city (place) or ZIP, the congressional, state senate and state house districts it falls in; for a district, the precincts, counties, towns, cities or ZIPs inside it (filter with `level`, e.g. 'precinct'). A city ('us:place:1714000') also lists its counties. A ZIP ('us:zcta:07102') lists the cities, counties, towns, precincts and districts it overlaps. Ask for `level='zcta'` on a city, county, town or district to list the ZIP codes in it. `weight` is the share of the smaller unit's 2020 population inside the other (for a ZIP, the share of the ZIP's residents in each unit; 0 for parts with land but no residents). relation 'within' means wholly inside (1.0), 'overlaps' means split, 'approximate' means the unit was too small to contain any 2020 block's internal point and was placed by the nearest block. Use min_weight to drop slivers. ZCTAs approximate USPS ZIP Codes.

Find geographies by name, e.g. 'Essex County', 'Newark ward 5', 'Toronto Centre'. country: 'US' or 'CA'. level: one of the levels from coverage_summary (e.g. 'county', 'precinct', 'congressional_district', 'federal_electoral_district'). region: USPS state or province code ('NJ', 'ON').