SHOW YOUR WORK
How we mapped more than 2,000 state and local races and measures across California
Statewide contests are easy to map. Mapping local contests across California’s 58 counties is much, much harder. Here’s how we did it.
My Ballot, a new tool in CalMatters’ 2026 Voter Guide, tells you what’s on your California ballot for the November election. Enter your address, and it lists the contests you can vote on, from statewide contests like governor and propositions all the way down to local races and measures for cities, school districts, water and fire districts, regional transit agencies and more.
Statewide, congressional and legislative districts are well mapped. Local contests are harder: what appears on your ballot depends on which of the dozens of overlapping districts your home falls in and no single source maps them all. So we built those maps ourselves, county by county, from the records counties use to run their elections. Here’s how we did it.
Methodology
Under state law, California county election officials are required to provide election data to the Legislature. Secretary of State memos for the 2026 June primary and November general election spell out the kinds of records counties submit at different points in an election cycle, including what we needed to build My Ballot:
- Digital precinct maps. Precincts are geographic areas that election officials use to organize voters. Your voter registration address places you in a particular precinct.
- Election records that connect precincts to the contests that applied there.
In theory, once we had both, we could connect each precinct map to the contests that belonged to it.
In practice, we sent public records requests to all 58 California counties, and they sent us maps and records that differed widely in format and detail. Geographic files varied from county to county. In most counties, the precinct maps lined up with the election records. In two counties, the geographic files did not show smaller precinct divisions that appeared in other election records, even though those divisions affected which ballots voters received. In those cases, we relied on additional records from the county — such as street-level precinct files or district boundaries — to reconstruct the smaller precinct divisions. In seven counties, precinct maps could not be tied directly to election records, so we built the shapes another way, mostly from the counties’ district maps.
The records connecting precincts to contests varied just as much. Counties sent reports in different formats, with different names and different levels of detail. Sometimes that came in one file; other times, we had to combine several reports.
Most counties used one of three election management systems, the software that tracks voters, precincts and ballots. Even so, counties on the same systems sent us different kinds of reports. Usually we could work with what they sent, with some exceptions. For example, San Bernardino exported and sent us only a subset of the data that Siskiyou sent using the same election system. Other counties, like Alameda and Monterey, had already published everything we needed online.
Some counties didn’t send what we needed, or shared it in a format that was hard to use, such as a separate sample ballot PDF for every precinct, which we had to extract one-by-one. For example, Merced linked us to its precincts map and said, “you can download the precinct shapefile, as well as click the link that reads ‘View Table Data’ to access links [to] the County voter information guides (in pdf format). The sample ballot included in the voter guides will show what contests coincide with each precinct.”
Sourcing maps
When counties did not provide precinct boundaries, we worked through a set of backup sources. We first looked for records the county had already published on its elections website or GIS portal. We also checked the Statewide Database, which collects and manages election data on behalf of the Legislature using records counties are required to provide.
We used these sources to find precinct maps or build the records linking them to contests in 12 counties. Four of those counties later confirmed the precinct maps we found. For two counties, Lassen and Sierra, we used the Statewide Database’s precinct maps from the November 2025 special election, after both counties confirmed by phone that their precincts hadn’t changed.
If we still could not get usable precinct geography, we looked for publicly available maps of the districts themselves, preferably from the county’s website, as we did in Humboldt and Shasta. When those were not available, we turned to other public sources, such as California’s GIS portal or maps published by local districts, to reconstruct where a contest applied.
Mapping local contests
For most counties, we could rely on contest records exported from their election software, such as reports listing races and measures in each precinct. We also created a reusable AI workflow — sometimes called a “skill” — to inventory what elections offices and local districts had published about their contests online. We used that research as a backup and check on the county data, not as a primary source for our maps.
The AI workflow was designed to flag uncertainty. When data sources conflicted or were incomplete, it flagged the issues for a person to review. We also checked the underlying sources by following links to county and district websites and doing additional reporting.
In many counties, we ran the workflow before we knew whether we would receive complete contest records. If counties sent us the direct records later, we used the county’s data instead. Whenever we compared the two, the research identified the same contests.
In a few counties, the elections office published its contests online but didn’t provide records tying contests to the precincts or districts where they appeared on the ballot. There, our AI workflow collected the list of contests from the county’s election pages and matched each contest to a district on the county’s maps. We reviewed each match, and recorded it with its source in a decisions log we kept for each county, so anyone could trace how a contest got its boundaries. (See Data Processing.)
Connecting contest and candidate data
For the parts of My Ballot beyond the maps and lookup tool on our site, we hired Branch, the team behind local voter guides and ballot lookups in Texas, Georgia and Minnesota. Branch provided the underlying platform, VoterGuideOS, that matched a voter’s location to district boundaries and connected the resulting districts to races, measures and candidates. Branch’s team also researched and validated the contests and candidates in the tool. That division of work let us concentrate our reporting and data work on collecting county election records and determining exactly where each local contest applied.
The VoterGuideOS platform also let us attach coverage links to individual contests. CalMatters covers state government and politics, so we don’t report on most local races. For local races, we pointed readers to local voter guides from our partner newsrooms.
Data processing
For each county, we had to turn a set of records, including various geographic files, contest reports, spreadsheets and sample ballots, into a single map of where each local contest appeared on the ballot. Most of the file processing was done with an AI coding tool that read documents and wrote and ran code. We reviewed its code for the first several counties we processed, then packaged what we learned into a set of processing protocols it followed for the rest. The protocols specified which records to use, how to read them, which checks to run on the results and when to stop. Missing records or conflicting sources had to be flagged to a human to resolve.
Each county’s processing was reproducible: a journalist running the same scripts on the same source files produced the same map. Names were preserved exactly as they appeared in records. Any judgment calls needed to connect those records, such as matching different spellings of a district’s name, were documented with a reason and a source in a decisions log for each county. Our processing code read directly from that log, so none of those calls were written into the scripts themselves. We reviewed and approved every entry before producing the final map.
Many county records arrived as PDFs, and some were scans of paper printouts. Our AI coding tool wrote code to extract the data and check results against summaries within the records, when available, or other county reports. When reading paper printouts, it used text recognition software, which can misread characters, so it compared what it read with other county records, by default. For one scanned report of precincts per district, the code read every precinct identifier several ways, such as enlarging the image or raising its contrast, and flagged disagreements, which a journalist reviewed. Our data team spot-checked a sample of the extracted data against the original records.
The data team also reviewed the process to build the final maps for several select counties from start to finish. We picked those counties to ensure the main types of extraction and linking processes were covered by the review.
Auditing maps
Counties assign every registered address to a precinct, and they keep that assignment as a list, in addition to digital maps. My Ballot relied on the digital maps because the VoterGuideOS platform looks up contests by location. Building My Ballot on address lists, which most counties didn’t share with us, would have meant cleaning up millions of addresses and storing every contest for each one.
But digital maps don’t always match the lists exactly: lines can leave gaps and overlaps, a precinct map can lag behind a recent boundary change, and a district’s map can differ from the county’s. Because the difference of a few feet can decide which contests an address is assigned, we checked the maps several ways before using them.
We wrote many of these checks into our processing protocols, and our AI tool flagged what needed a closer look for us to review manually. For example, the protocols measured every gap between a county’s precincts. Most were slivers too small to hold anything, sometimes fractions of a square meter, but where a gap or overlap was large enough to matter, we looked at it on satellite imagery to see whether any homes were there.
Depending on the county, we ran some or all of these checks:
- Holes in the map: A hole means a home address would only get the countywide contests and no local ones, like contests for board seats or measures on special district taxes. The tool compared the outer edge of a county’s boundary with its precincts or districts, and every gap and overlap between that county’s precincts or districts. We confirmed the differences, such as coastal water or lakes, by manually inspecting the areas on satellite imagery. If we decided that an area could hold a home, we used different factors to determine which contests the area should receive (See Limitations). If an area did not hold a home, the area would only receive countywide contests.
- Which map the county used: Some precinct maps were not sent directly to us from the county’s election office. To check for accuracy, the tool compared the maps, from the ones counties sent us directly to maps we found on county websites and versions found on Statewide Database. We asked counties to confirm which maps were current, and if they did not respond, we chose the maps that best aligned with other records a county sent or recent data the county posted online.
- Homes that appeared misplaced: Sometimes, based on district boundaries, it seemed like counties might have assigned homes to the wrong contests. For example, in one area, our tool flagged that homes with even-numbered street addresses belonged to one trustee area and ones with odd-numbered addresses belonged to a different trustee area — with one exception. In another instance, our tool found a city line that cut through a precinct. In these scenarios, we asked counties to confirm each home’s ballot when possible. Based on the county’s response (or lack thereof) or the data available, we manually reviewed district or parcel shapes on satellite imagery or street maps to assign which districts homes belonged to. If it was not possible to confirm with counties or make a good estimate, we defaulted to the county’s most recent election records.
- County borders: Neighboring county boundaries rarely matched exactly. As needed, the tool compared federal Census county lines, precinct lines or district lines, and identified gaps and overlaps. We manually reviewed areas with homes near a county line using satellite imagery, parcel maps and county address lookup tools, then chose which border to use based on which was more accurate. In open land, we defaulted to using the Census line. (See Limitations: County borders.)
We asked counties about discrepancies or anything we believed could be an error on the county’s maps. After hearing from us, multiple counties either corrected their records and sent their updated files, or confirmed that we had found an error and said they would make corrections. In these cases, we made those same corrections in My Ballot.
Limitations
Missing counties
Six counties — Calaveras, Kings, Modoc, Mono, Tehama and Yuba — didn’t send us the records we needed to map local contests by My Ballot’s launch. My Ballot may instead show a limited selection of contests within that county. We’re looking into additional public records that may allow us to update My Ballot with more contests.
Google address search
My Ballot relies on Google to turn a voter’s address into precise map coordinates. VoterGuideOS, Branch’s platform, then identifies which contests apply to those coordinates using our digital precinct boundaries. Near a boundary, Google may set incorrect coordinates that place an address in the wrong county. That can happen with any home close to a line, not just one that sits on it. Condo and apartment complexes are especially tricky: Google sometimes places a single point for an address rather than for each unit or building, so in a complex near a line, that point can fall on the wrong side of a voter’s unit. We cannot correct where Google places an address.
Place boundaries
In the week before launching My Ballot, we confirmed that for many counties and some other boundaries, such as cities and school districts, VoterGuideOS used boundaries from its own sources instead of the ones we supplied to decide which local contests a My Ballot user would see. This may cause voters who live near boundaries to see the wrong local races. We’re reviewing those cases with Branch.
County borders
Two neighboring counties’ maps rarely matched exactly, leaving slivers that both or neither county claimed. Where homes sat near a county line, and in some less-populated places too, we downloaded the counties’ parcel maps, reviewed the areas on satellite imagery and checked addresses with the counties’ parcel and voter lookup tools. Then we chose one line so that no address fell in both counties or neither. In open land, we defaulted to using the federal Census county line unless a manual spot check revealed a better choice.
In a few places, neighboring counties’ records overlapped, so wherever we drew the boundary, it cut through land both counties claimed. At one condo complex on the San Francisco–San Mateo border, for example, both counties’ property records list the same address, and their parcel maps overlap by a few feet; we gave the overlap to San Mateo.
Those reviews relied on what we could see, so a home we couldn’t see, or one built recently, could still fall on the wrong side. The same goes for the small areas inside a county that no precinct covers, usually parks, water or open land: an address there would get only countywide contests, and we checked those areas on satellite imagery too.
Counties with open questions or special handling
Most counties provided CalMatters with records that connected every precinct to its contests, or the county’s district maps followed its precinct lines.
For the following counties, we had to build the connection between precincts and contests differently, or we still needed more information from the county to build those connections.
Amador
Amador sent its precinct map and a report listing the contests in each voting precinct (larger units made up of several precincts), but not a current list of which precincts make up each voting precinct. We found data on which precincts make up each voting precinct on Amador’s GIS portal. In one location, two voting precincts overlapped in an area where we could see houses. Both the county’s precinct map and its supervisorial district map put those homes in District 4, so we assigned them to that district’s voting precinct. We asked the county for a list of which precincts make up each voting precinct, and have not yet heard back.
Humboldt
Humboldt’s elections office told us it had no records matching our request and pointed us to the county’s online maps. The county’s map viewer included a precinct map from the county’s planning department and the county’s district maps. We laid the district maps over the precincts and assigned each precinct to the districts covering most of it; the two maps lined up closely. But in three precincts, the district lines more accurately reflected the contests voters in those areas would receive. In those cases, we split the precincts along district lines.
Where the county’s district maps fell short, we used other official maps. Humboldt Bay Municipal Water District’s Division 5 had no digital map, but the district’s published static map included precinct lines, with the division lines following them, and listed its map projection, so we could lay it over the county’s precincts and identify the ones in Division 5. We also used the county’s tax-rate areas, which record the districts each parcel belongs to, for a few districts the county’s maps left out or drew without some homes.
Marin
Marin sent its precinct map but no records linking precincts to contests. The county published a map of the districts each precinct belongs to. Web searches with an AI tool led us to a few sample ballots, enough to show the naming pattern, which turned up 84 sample ballots all. We could not find where the sample ballots were publicly linked on the county’s website.
Since we could not find any records linking the 84 sample ballots to precincts, we took the contests from the sample ballots, matched each one to a district, and then checked our work. If our inference was correct, then the districts of each precinct should add up to exactly one sample ballot — and in every precinct they did. But three sample ballots did not match with any precinct and we couldn’t find where they applied: the county’s district maps lined up with its precincts, with no split that would explain them.
Santa Cruz
Santa Cruz sent its precinct map and a report linking contests to precincts. For one Watsonville precinct with 47 registered voters, the county’s contest report placed it in City Council District 5, but the county’s precinct map, council district map and the city’s map put it in District 6. We followed the ballot report, since that’s what the county used to assign ballots, and asked the county to confirm. We have not yet heard back.
Shasta
Shasta sent its precinct maps, but no records linking precincts to contests. We built Shasta’s map from the county’s district maps rather than from precincts. Unlike the other counties built this way, Shasta’s district lines didn’t always follow its precinct lines: about one in 10 of its precincts had a district line running through it. The county’s district maps didn’t include Gateway Unified School District’s trustee areas and Gateway’s website had no map either. We called the district, which emailed us PDF maps of the two trustee areas on the November ballot, drawn by the county elections office in 2012. We digitized the lines between the areas and used them in My Ballot.
Credits and acknowledgements
CalMatters was able to build our own digital election maps because of the following:
- Data reporting by Soo Oh
- Additional reporting by John Osborn D’Agostino and Kate Li
- Data spot-checking and methodology review by Mohamed Al Elew, Jeremia Kimelman and Natasha Uzcátegui-Liggett
- Editing by Sisi Wei
Our digital election maps fuel our My Ballot tool, which was made possible because of:
- Design and art direction by Gabriel Hongsdusit
- Web development by Matt McVickar
- Editing by Andrew Losowsky, Soo Oh and Sisi Wei
The CalMatters 2026 voter guide is a huge team effort. See our full credits on the voter guide homepage.
Thank you to Paul Mitchell for helping us understand how precincts form the basis of election ballots, and pointing us toward the records we used to map local contests.
Finally, thank you to the Branch team for both researching and providing for CalMatters details of every race and candidate in the state, and creating an infrastructure that allowed us to manage every contest, candidate and district in California.
