# Official source notes

Access date: 6 September 2026. The source family notes below identify agency, URLs, coverage, updates, geographic scope, observation grain, exclusions and provisional status. Exact files, bytes and checksums are in the adjacent manifests. No news, law-firm, SEO or aggregator statistics were used. The City plan’s secondary-source national comparison chart was excluded.

# City of San Jose source acquisition notes

Access date: 2026-09-06. These notes distinguish source discovery from validated event downloads.

## Official provenance

The City's [Vision Zero page](https://www.sanjoseca.gov/your-government/departments-offices/transportation/safety/vision-zero) links its all-crash dashboard (`5f9532cf115442d48c0073d7efbd62c3`), KSI dashboard (`fccd37bd69984b229905e68d73d5c701`), and [PSC map](https://maps.visualizedot.com/TrafficSafety/VisionZeroCorridors/). Their downloaded ArcGIS configuration JSON establishes these data dependencies:

- All-crash webmap `fbd8d23079a041beac6ba66123a400dc`: `https://geo.sanjoseca.gov/server/rest/services/DOT/DOT_BikePed/MapServer/18`, **Vision Zero Crash Facts Last Five Years**.
- PSC webmap `3e9535d51e774c0b8c77d1f6fdb5ec1f`: `https://geo.sanjoseca.gov/server/rest/services/DOT/DOT_BikePed/MapServer/8`.
- The City's official ArcGIS organization is `6kSayNlqm3HvsYZ8`; public source items owned by `sanjose` are the City's open-data publication.

Official open-data items used:

| Dataset | ArcGIS item | Layer | Unit |
|---|---|---|---|
| Crash Locations | `8f2f6943cf93404fa33abdf1e6f4a3b2` | OPN/OPN_OpenDataService/MapServer/512 | Crash |
| Crash Locations Last Five Years | `cb673c383983406abe0c890dd8b63e86` | Same service, 553 | Crash |
| Crash Vehicles Involved | `9f590a6644a9468da48ea87b5b48d821` | Same service, 513 | Vehicle/party, including nonmotorists |
| Vision Zero Safety Corridors | `e7b97ab9f9874715b3abf7eee5825936` | Same service, 514 | Corridor geometry |
| Street Intersections | `a3106e85fc154cd58b17140dab0ed716` | Same service, 276 | Intersection |
| Streets | `4c094a4cbdcb4048948fd8f8c6a81862` | Same service, 60 | Street centerline link |
| City Limits | `f9d06700dae94c35a46cdf34c47e6e4e` | Same service, 372 | Municipal multipolygon |

Each can be inspected with `https://www.arcgis.com/sharing/rest/content/items/{item}?f=json`; Hub metadata is `https://hub.arcgis.com/api/v3/datasets/{item}_{layer}`. Raw metadata is retained.

## Freshness discovery and required correction

The [City's June 2, 2026 announcement](https://www.sanjoseca.gov/Home/Components/News/News/7334/5104) describes the dashboard period as 2020–2024. That prose is insufficient to establish the current source period.

The first default last-five-years CSV export had 24,152 rows: 2020 4,341; 2021 4,707; 2022 5,158; 2023 4,540; 2024 5,399; 2025 7. Hub's download metadata dates this cache to 2025-06-24. Current indexed metadata reported 24,648 records. The discrepancy is real and the cached file must not be described as a current complete extract.

A newly requested source export of layer 553 filtered to 2020–2024 contained **no 2020 records**, and 19,993 records in 2021–2024 (4,707; 5,154; 4,538; 5,594). This proves that the current last-five-years layer no longer exposes the older cached five-year window. The canonical 2020–2024 study must use a newly generated export of full archive layer 512. File `crashes_2020_2024_fresh.csv` is this **553 diagnostic extract, containing 2021–2024 only**, and must not be mistaken for the final five-year input.

The newly generated full archive 512 export completed at **2026-09-06 12:50:44 UTC**. Raw file `crash512_2020_2024_fresh.csv.gz` contains **24,359** unique CRASHNAME and TCRNUMBER values, with all X/Y and four injury-count fields populated. Annual counts are 2020 4,339; 2021 4,707; 2022 5,150; 2023 4,540; 2024 5,623. Fatal-person totals are respectively 48, 59, 63, 52, and 47. These are downloaded-source totals before the root study's geographic and jurisdiction QA, not final municipal-boundary findings.

Fresh 512 and fresh 553 still differ: within 2021–2024, 39 IDs occur only in 512 and 12 only in 553. Two shared records have differing fatal injury counts; 2,037 shared IDs have different geometry coordinates. Those are differences between official published layers, not permission to combine records. `fresh_source_reconciliation.json` retains exact IDs and counts. The canonical study uses the fresh archive snapshot and discloses the disagreement.

Current 553 indexed year statistics explicitly cover **2021–2025** (including 4,655 records in 2025) and reconcile exactly to the 24,648 indexed count. The study's continued use of 2020–2024 therefore requires a stated common-period rationale, not a claim that 2020–2024 is still the latest source window. Archive 512 indexed year statistics are less reliable: its metadata marks the year statistics as failed due to a query timeout, and the fresh export contains three historical records more than those indexed 2020–2024 statistics. Indexed statistics are retained as a discrepancy check, not treated as an exact live count.

The entire cached 512 archive was independently downloaded (418,890,365 bytes, lossless gzip); its 2020–2024 slice has 24,193 rows, also differing from the cached 553 export. This is another snapshot, not a second crash source to add. Full raw party archive was independently downloaded (433,679,555 bytes, 1,216,231 rows); 49,788 of its party records date to 2020–2024.

## How fresh files were requested

Direct City GIS HTTPS requests consistently timed out during TLS handshake, and HTTP timed out. Repeated attempts covered JSON/HTML and server/arcgis paths. ArcGIS Hub itself can reach the official source. Its default download serves cached files even when freshness is unknown, as described in [Esri's documentation](https://doc.arcgis.com/en/hub/content/data-download-settings.htm).

We used the public POST export API implemented by Esri's `@esri/hub-downloads` package (`hubRequestDatasetExport`), not a third-party mirror:

```
POST https://hub.arcgis.com/api/v3/datasets/{item}_{layer}/downloads
Content-Type: application/json
{"format":"csv","spatialRefId":4326,"where":"YEAR >= '2020' AND YEAR <= '2024'"}
```

Poll GET on the same downloads endpoint with `formats=csv`, `spatialRefId=4326`, and the exact `where`. Wait for ready/ready_unknown **and a new contentLastModified timestamp**; record job progress, URL, headers, file size, and SHA-256. Party layer has **no YEAR field**; its filter must use CRASHDATETIME and timestamp literals. The initial YEAR filter for parties returned HTTP 500 and was corrected.

`collect_city.py` reproduces fresh crash and party exports, preserving raw response bytes in lossless gzip. Raw hashes are hashes of the original uncompressed response bytes.

## Geometry and interpretation pitfalls

- Original cached CSV X/Y uses California State Plane zone III US survey feet (EPSG 2227). New requested exports set spatialRefId=4326, so their X/Y is longitude/latitude. Never interpret the former X/Y as degrees.
- GeoJSON exports are WGS84/CRS84. Public LATITUDE/LONGITUDE attributes can differ from the service's geometry and must be retained separately. Map the source geometry, then report displacement from the published attributes and reference intersections.
- `REPORTEDLOCATIONFOUND` has only a Yes/No coded-domain definition. It does not safely mean that a crash itself is unverifiable. In the old 2020–2024 extract, all 9,792 crashes marked `PROXIMITYTOINTERSECTION=Intersection` had this flag No. For records that match the reference intersection table, No coordinates are a median 1.28 m from that intersection (95th percentile 1.33 m); Yes median is 21.04 m (95th percentile 147.15 m). This pattern is consistent with a flag describing offset-location placement, but that interpretation is **an inference**, not documented City methodology. Treat explicit intersection records differently from nonintersection records whose offset placement failed.
- Intersections are joined by crash INTERSECTIONNUMBER to reference INTNUM. Reference streets have ASTREETNAME/BSTREETNAME. Street centerlines use FROMINTERID/TOINTERID, which are not necessarily INTNUM.
- The downloaded hosted `CSJWebMapBase/FeatureServer/5` layer labelled City of San Jose Boundary is an outside-city display mask including a large rectangle. **Do not use it as the municipal boundary.** Use the official OPN/372 City Limits export (`boundary_geojson_retry.response`), whose last-update attribute is 2026-05-06. It is a present-day boundary, not a historical annexation reconstruction.
- A street type `Freeway/Expressway (CA)` is not a reliable state-freeway flag: the category includes county expressways, and a freeway named as a cross street may describe a ramp terminal. Jurisdiction classification needs independent spatial and CHP route evidence.
- PSC export has 31 features. The action plan describes 30 named streets; feature count, list count, and named-road count should not be conflated. Corridor geometry overlaps neighboring jurisdictions.

## Party data limitations

Party files must never be counted as crashes. CRASHNAME joins to crashes; VEHICLERECORDNAME identifies the party record. PARTYTYPE includes Car, Bicycle, Pedestrian, Motorcycle/Moped, and other conveyances. The service does not expose a separate one-row-per-person table. Sex/age describe the operator, not every occupant.

In the cached 2020–2024 party slice, 16,593 rows have missing FATALINJURIES and other injury values. Summed explicit party fatalities are zero in 2020 and ten in 2021, while the crash table reports 49 and 60. Thus absence of party injury values is not zero, and whole-period person-level mode injury totals cannot be reported without a substantial completeness qualification. Mode **involvement** is still available from party types, but mode-involved crash KSI is distinct from KSI people of that mode.

The **fresh** party export was successfully recovered after a transient final-conversion status gap: the status temporarily returned no entries and the download returned 404, but a subsequent status request without the formats filter exposed completed files. The CSV was generated at **2026-09-06 13:12:05 UTC** and contains **50,234 unique party IDs representing 24,391 crash IDs**. Its annual party counts are 8,970; 9,659; 10,691; 9,360; and 11,554. Missing at least one injury-count field affects respectively 8,361; 8,211; 35; 1; and 2 party rows. This confirms the early-period injury attribution gap remains in current data. Raw file: `vehicle513_2020_2024_fresh.csv.gz`.

Annual retry export requests were submitted while the full-period file appeared unavailable. Those requests and their responses are retained for troubleshooting; the successfully recovered full-period fresh export is the final input. Do not replace it with the older cached party extract. `normalize_city_parties.py` records unmatched IDs, count reconciliation, classification conflicts, and the strict eligibility gate for person metrics.

The completed normalization joins 50,234 party records to 24,359 canonical City crash IDs. It finds 59 party crash IDs absent from the crash snapshot and 27 canonical crash IDs without party records. Exactly 24,324 crashes have party-row counts matching the crash VEHICLECOUNT field; 16,258 reconcile all four severity sums; 14,006 also have unambiguous modes and pass every gate for person metrics. The yearly eligible counts are 217, 538, 4,465, 3,964, and 4,822. Conflicting source type/category evidence is retained for audit but does not create a positive headline mode flag. An unambiguous other party can independently establish that mode. `party_qa.json` and `party_coverage_by_year.csv` contain the checks.

## Cause-indicator completeness

The stored SPEEDINGFLAG and HITANDRUNFLAG have sharp population discontinuities around 2022. Their explicit False values cannot be treated as confirmed negative classifications across the entire study. `crash_factor_population_checks.csv` compares each year's flags against the separately recorded decoded speeding violations. Any positive source evidence can identify a reported speeding-related record; absence of positive evidence must not imply the behavior did not occur. A before/after factor trend is not publication-safe merely because the crash dates are complete.

Party layer 513 contains no dedicated hit-and-run indicator. A small subset has the decoded violation `Leave Accident Scene`; this can add positive evidence but cannot restore a complete hit-and-run history. `SOBRIETY` distinguishes being under alcohol influence, under drug influence, having drunk with unknown impairment, having drunk without being under the influence, and unknown impairment. The latter categories must not be silently relabelled DUI.

## City methodology and limitations

The [2025 Vision Zero Action Plan](https://www.sanjoseca.gov/home/showpublisheddocument/118265/638761805841100000), page 26, describes the 2023 PSC update using 2017–2021 data, weighting fatal and severe injuries three times other injuries. Existing corridors were retained. Its list includes 28 corridors in City jurisdiction and two fully under Santa Clara County, plus some portions in neighboring jurisdictions. A contemporary analyst score can test the same person weighting but must not claim to reproduce the City's selection algorithm or its historical period.

The plan PDF and main City pages returned HTTP 403 on direct raw download, including tested case and query variants. This was resolved through the City's official legislative attachment: [2025 Vision Zero Action Plan, Council File 25-151](https://sanjose.legistar.com/View.ashx?GUID=D06949E0-EF76-4BDB-9BF4-F78BA3AFA9E9&ID=13758090&M=F). The complete 11,168,806-byte PDF is retained as `vision_zero_2025_legistar_attachment.pdf`; pages 11 and 26 were visually inspected. Page 11 expressly states that San Jose Vision Zero reports only SJPD-collected crashes on City streets and County expressways. That is official documentation of scope. The national comparison chart on that page is credited to a newspaper and is **excluded from this study's factual claims**, notwithstanding its inclusion in a City publication.

The similarly named hosted service `https://services1.arcgis.com/F1v0ufATbBQScMtY/arcgis/rest/services/Vision_Zero_Dashboard/FeatureServer` is **excluded**: its fields refer to City of Las Vegas and the organization is not San Jose. Its inspected schema is retained solely as rejection evidence (`hosted_layers_metadata.json`). No records from it enter this study.


---

# CHP CCRS / SWITRS and UC Berkeley TIMS acquisition notes

Access date: 2026-09-06. Acquisition and normalization scripts are in this directory. These notes accompany the City-led canonical workflow; this directory's geographic candidate tables are not a published San Jose sample.

## California Highway Patrol: CCRS

Agency: California Highway Patrol (CHP). Dataset: California Crash Reporting System (CCRS), annual Crashes, Parties, and InjuredWitnessPassengers exports for 2020–2024. Official catalog: <https://data.ca.gov/dataset/ccrs>. Official machine-readable catalog: <https://data.ca.gov/api/3/action/package_show?id=ccrs>. CHP links that catalog from <https://www.chp.ca.gov/iswtrs/> and states that CCRS replaced public ISWITRS access on January 8, 2025.

All 15 annual full-state tables were downloaded and CSV-parsed successfully, not merely discovered. The original `/dataset/.../resource/.../download/...csv` URLs each returned HTTP 403 after three attempts. The official CKAN DataStore full-export endpoint succeeded: `https://data.ca.gov/datastore/dump/RESOURCE_ID?format=csv`. The catalog explicitly reports `datastore_contains_all_records_of_source_file=true` for these resources. The alternate official export adds its `_id` storage field and may serialize data types differently from the original uploaded CSV; we do not claim byte identity to a blocked upload. We preserve exact received export bytes losslessly inside gzip files. Their uncompressed SHA-256 values and compressed-file SHA-256 values, bytes, row counts, schemas, URLs, source dates, and access timestamps are in `data/raw/chp/datastore_download_manifest.json`. The original failed download attempts are in `download_manifest.json` and individual manifests.

Disk space was exhausted during the first attempt to store uncompressed statewide files. Only our incomplete `.part` downloads were removed. Completed response streams were losslessly compressed and subsequent downloads streamed directly into gzip; original response checksums and parsed record counts were preserved. All final 15 archives were CSV-validated with zero malformed row lengths. The final archives occupy approximately 320.5 MB compressed.

Coverage: California statewide, crashes dated within each annual file. Data are police-reported, not a census of every collision that occurred. Geography is reported `City Code`, `City Name`, `County Code`, and officer-reported coordinates. San Jose appears as City Code 4313 in County Code 43, while San Jose State University is coded separately as 4317. Full-state raw data are retained. Derived candidates contain County Code 43, City Code 4313/4317, or coordinates inside the broad envelope latitude 37.1–37.6 / longitude -122.1–-121.5. This envelope deliberately overselects and does not establish city jurisdiction. The root workflow must use official municipal boundaries and its own inclusion rules.

Update dates: catalog metadata downloaded September 6, 2026; per-resource source descriptions state September 5, 2026 evening updates (catalog's printed local times). Resource `last_modified` metadata and HTTP information are retained where supplied. These are snapshots that may be revised. A record's `Is Preliminary=False` is not proof that the whole annual dataset is final. TIMS explicitly designates 2024 and later as provisional; the 2024 file remains labeled provisional in our normalization. For 2020–2023 we retain the official CCRS snapshot date rather than asserting that its current bytes equal a frozen annual release.

### Unit of observation and keys

- `Crashes`: one record per `Collision Id`. All five statewide files passed per-year key-uniqueness checks; candidate IDs also passed cross-year uniqueness. Normalized key is `CHP:<Collision Id>`.
- `Parties`: one party per `PartyId`, joined to a crash by `CollisionId`. `PartyNumber` locates the party within a crash. A party is not a crash, and a party is not necessarily an injured person.
- `InjuredWitnessPassengers`: one stored person-related record per `InjuredWitPassId`, joined to a crash by `CollisionId` and, when applicable, to a party by `(CollisionId, PartyNumber)`. This table includes witnesses and passengers, so its row count must never be called number injured. Only recognized injury codes are injury outcomes. `IsWitnessOnly=True` records are excluded from injury counting.
- Storage `_id` fields are not canonical crash identity. Do not assume modern CCRS `Collision Id` equals legacy SWITRS `CASE_ID`. Do not join different systems by those numeric IDs without a documented crosswalk.
- Report numbers may be missing; missing report numbers cannot be a shared deduplication key. In 2024 two different San Jose crashes have blank report numbers. They are different events, not duplicate crashes.

### Injury severity normalization and nulls

Source `NumberKilled` is authoritative for the normalized fatality count; absent values stay null. Injuries are derived from the linked person table only when the known source `NumberInjured` equals the count of recognized nonfatal injured people. A source zero can establish a true zero; absent people alone cannot. The 74,683-record broad candidate set contains seven known injury-count disagreements and 89 unknown normalized severity counts including missing source totals. Zero known fatality/person disagreements were found in this candidate set. Exception and QA files identify the limits.

The official TIMS codebook groups severe with suspected serious injury, visible with suspected minor injury, and complaint of pain with possible injury: <https://tims.berkeley.edu/help/crashdata/switrs-codebook.php>. CCRS person labels map accordingly:

| CCRS person code | Normalized outcome |
|---|---|
| Fatal | fatality |
| SuspectSerious, SevereInactive | severe injury |
| SuspectMinor, OtherVisibleInactive | moderate injury |
| PossibleInjury, ComplaintOfPainInactive | minor injury |
| blank / otherwise unrecognized | unknown, never inferred zero |

This labeling is for schema consistency with the City table. The distinction between moderate/minor is a crosswalk from the official California categories, not a newly observed medical assessment. `observed_severe_injuries` preserves observed positive person counts for audit even where reconciliation prevents use of a complete severe count.

`ksi_persons` is fatalities plus severe injuries when both are known. `ksi_crash` uses three-valued logic: a known fatal or severe positive establishes a KSI crash even if the other component is unknown. A crash's involvement of a pedestrian does not prove that the pedestrian sustained its severe outcome. Actual mode-specific KSI people require direct `InjuredPersonType` and, for drivers/passengers, an unambiguous party join and vehicle class. If any KSI person's mode remains unclassifiable, all mode-specific KSI person totals for that crash stay null. A separate `mode_ksi_classification_complete` flag documents this restriction.

Motorcycle-class vehicles include Motorcycle, PoliceMotorcycle, MotorDrivenCycleScooter15HpOrLess, and MotorizedBicycle. Bicycle-class vehicles include Bicycle and ElectricBicycles, as well as explicitly typed bicyclist people/parties. Vehicle occupants exclude people identified as motorcycle-class or bicycle-class. These are stated analytical groupings; they must be labeled consistently in publication.

### Time and conditions

2021's official DataStore export uses US month/day/year 12-hour date strings; other annual exports use ISO timestamps. Both are parsed explicitly. All 74,683 candidate crash dates parsed; 487 crash times are missing/invalid. Calendar year, month, day of week, and weekend use the parsed local date. No impossible/unknown time is converted into midnight. Normalized UTC is derived using America/Los_Angeles only when the local time is unambiguous; 14 DST ambiguous/nonexistent times keep UTC null. Local time and raw source time remain available. Rush hours are the analyst's weekday hours 07–09 and 16–18 inclusive. Lighting-based nighttime and clock-night 18:00–05:59 are separate measures.

Weather and collision descriptions use official text. Road-surface and traffic-control codes are crosswalked from the official codebook. Secondary distance units F/M are retained as feet/miles. A zero reported offset is not independently verified intersection location, and street-pair names are not proof that an event occurred at the intersection.

### Factor flags

Factors are reported police coding, not an independent finding of causation or legal fault. Explicit primary-factor and party-associated Vehicle Code sections produce analytical positive flags. No DUI-positive flag means unknown rather than a finding of sobriety. The source wording is retained in selected party tables. Unspecified associated violations prevent a false negative.

- Speeding-related codes: 22348, 22349, 22350, 22352, 22354, 22356, 22406, 22407.
- Turn/movement-related codes: 22100, 22101, 22102, 22103, 22105, 22106, 22107, 22108, 22109, 22110, 22111. These include turning, lane-change, signaling, and starting/backing provisions; label the grouping accordingly rather than implying every event was an unsafe turn alone.
- Red signal positive: 21453.
- DUI/intoxication positive: 23140, 23152, 23153, or party description HBD-UNDER INFLUENCE / UNDER_DRUG_INFLUENCE. This is narrower than any alcohol involvement.

Official references include the California Legislature's Vehicle Code speed laws (<https://leginfo.legislature.ca.gov/faces/codes_displayText.xhtml?article=1.&chapter=7.&division=11.&lawCode=VEH&part=&title=>), the Judicial Council's official 2024 CACI 705/706 instructions (<https://courts.ca.gov/system/files/2024-08/judicial_council_of_california_civil_jury_instructions_2024.pdf>), and the Judicial Council's offense descriptions (<https://courts.ca.gov/system/files/file/rules-20250313-materials_0.pdf>). Section groupings are analyst-defined; they are not a City of San Jose official factor metric.

## UC Berkeley SafeTREC: TIMS cross-check

Agency: University of California, Berkeley, Safe Transportation Research and Education Center (SafeTREC). Dataset/tool: official SWITRS Summary. URL: <https://tims.berkeley.edu/tools/summary/>. Accessed September 6, 2026; page states data are CHP crashes as of June 8, 2026, updated quarterly. The complete HTML and its script are retained with hashes, including embedded official city aggregates. `tims_san_jose_official_summary.csv` selects exact San Jose rows for 2020–2024.

The summary's embedded city arrays 4, 5, and 6 represent fatal-and-injury, fatal-and-serious-injury, and fatal results, respectively; this correspondence was verified against the downloaded official JavaScript severity labels and its city-array selection. `crashes` is crashes. `victims`, pedestrian/bicyclist/motorcyclist fields, and factor fields are people, not crashes. For example, a speeding field in the TIMS summary is victims of speed-related crashes, not number of crashes. `occupant` specifically means unrestrained/improperly restrained occupant victims; it is not all vehicle occupants.

Status and exclusions: TIMS labels 2024–2025 provisional and subject to change. Its overview explicitly explains that 2024 remains provisional because CHP has not issued that year's SWITRS annual report: <https://tims.berkeley.edu/help/crashdata/switrs.php>. TIMS excludes property-damage-only crashes. Its geocoded POINT_X/POINT_Y are distinct from officer-reported LATITUDE/LONGITUDE. Mapping displays only geocoded records, whereas downloaded query results can include records without geocodes: <https://tims.berkeley.edu/help/tools/analysis/query-and-map.php>. Its geocoding methods are documented at <https://tims.berkeley.edu/help/crashdata/switrs-geocoding.php>.

These are overlapping CHP/SWITRS data. They are cross-checks only and must never be added as extra crashes. The June TIMS snapshot and September CCRS snapshot disagree slightly for some years. The specific reason is unresolved; do not assert deletion, underreporting, or an error by either agency as the cause. Cross-check CSV retains exact differences. The posted official CCRS Raw Data Template DOCX remained inaccessible (403); the live official TIMS codebook and the self-describing CCRS schemas were obtained, and the failed DOCX request is logged.

## Reproduction order

1. `acquire_chp.py`: preserve catalog and document original download attempts.
2. `acquire_datastore_dump.py`: fetch all 15 full official DataStore exports and CSV-validate them.
3. `extract_county.py 2024 2023 2022 2021 2020`: build broad geographic candidates while checking statewide primary-ID uniqueness.
4. `summarize_chp.py`: raw San Jose city-code summaries and injury reconciliation exceptions (not spatial final totals).
5. `normalize_chp.py`: normalized candidate crashes and selected raw party/person tables in `data/processed/`, plus QA.
6. Root workflow applies official boundary validation, network separation, City/CHP duplicate review, and final publication gating. All CHP normalized records begin with `map_eligible=False` and `geographic_validation=pending_official_boundary`.

## Recorded vehicle-occupant involvement

`vehicle_occupant_crash` is a nullable crash-level evidence flag, separate from injured-person counts and from motorcycles/bicycles. `road_user_flags.py` uses an explicit whitelist of motor-vehicle source classes. A classified motor-vehicle Driver party establishes positive involvement. A non-witness Driver/Passenger person, including an explicitly marked uninjured `IsPassengerOnly=True` record, can independently establish it after an unambiguous PartyNumber join. ParkedVehicle, Other, or AutonomousVehicle parties alone do not establish occupancy; neither do unknown hit-and-run vehicle classes or newly encountered unclassified codes. Powered scooters and motorcycle/bicycle classes do not fall through into this group.

A negative flag requires a nonempty downloaded party set entirely classified as other road-user modes, without contradictory or unclassifiable occupied-person evidence. It describes the recorded party evidence; it does not certify a headcount of everyone at the scene. Unknown occupancy, missing parties, unknown vehicle classes, and unresolved person joins remain null. Existing mode-specific injured-person totals retain their separate severity reconciliation gates. `vehicle_occupant_evidence_note` records the supporting rule, and `chp_normalization_qa.json` supplies positive/negative/unknown coverage by year. `test_road_user_flags.py` tests the principal semantic failure cases.


---

# Official validation and exposure sources

Accessed 6 September 2026 UTC. `download_manifest.json` records URL, time, HTTP status, content type, byte length, SHA-256, Last-Modified where available, archive CRC checks, and all failed attempts. `download_manifest.csv` is the flattened index. Files under `data/raw/validation/` preserve response bytes; extracts and analysis stay here. No FARS or OTS rows were added to the primary crash table.

## NHTSA Fatality Analysis Reporting System (FARS)

Agency: National Highway Traffic Safety Administration. [Official source overview](https://www.nhtsa.gov/research-data/fatality-analysis-reporting-system-fars), [official download directory](https://www.nhtsa.gov/file-downloads?p=nhtsa/downloads/FARS/), [1975–2024 Analytical User's Manual](https://crashstats.nhtsa.dot.gov/Api/Public/ViewPublication/813794).

Downloaded each full national CSV ZIP and release notes from `https://static.nhtsa.gov/nhtsa/downloads/FARS/{year}/National/FARS{year}NationalCSV.zip` for 2020–2024. Every ZIP passed CRC verification; each has 34 archive members. The separate auxiliary ZIPs are not required for the calculations here, which use `accident.csv` and `person.csv` with their embedded official NAME labels.

FARS is a fatal-crash census. It excludes nonfatal crashes, and cannot validate all-crash incidence or all-crash injury rates. The manual defines qualifying deaths within 30 days following a motor-vehicle traffic crash. Its Accident table has one row per crash; the Person table has one row per person. Other files may contain multiple events/conditions per crash. Join on STATE/ST_CASE plus year; person keys additionally use VEH_NO/PER_NO. State=6 is California, County=85 is Santa Clara, and City=3340 has the official name SAN JOSE in these files. City codes are a separate geographic test from point-in-boundary inclusion.

Release notes establish:

| Year | Release status and later revisions |
|---|---|
| 2020 | Final file first released 2023-04-03; later files revised 2025-04-08. |
| 2021 | Final file first released 2024-04-01; later revisions through 2026-06-24. |
| 2022 | Final file first released 2025-04-08; additional updates 2026-04-01. |
| 2023 | Final file first released 2026-04-01. |
| 2024 | First annual file released 2026-04-01; not a final file. |

The manual (PDF pp.10 and 754) explains that an Annual Report File is replaced by a later final file and can contain more unknowns for medical, toxicology and other information received later. The downloaded 2024 annual release must not be called final.

The NHTSA manual endpoint returned a multipart-form response despite declaring application/pdf. Original bytes remain `fars_manual_1975_2024.pdf`; the contained document was extracted to `fars_manual_1975_2024_extracted.pdf` and parsed as 823 pages. This exception is documented in the manifest; a successful HTTP code alone was not accepted as format verification.

### Geography and person validation

All 558 Santa Clara County FARS Accident records for 2020–2024 were retained as candidates. Primary keys have no duplicates; 1,333 county Person rows have no duplicate person keys. Fatal person counts (INJ_SEV=4) reconcile exactly to FATALS for every county crash (584 people total). This is a source QA result, not a San Jose total.

`fars_santa_clara_crashes_boundary_checked.csv` uses the official City OPN372 boundary obtained by the City acquisition agent (`data/raw/city/boundary_geojson_retry.response`, SHA-256 `7ac8eb2f4fe8a69df5138654a5d6a57288f60f20e4af62355f5b966f7add628b`). Geometry is valid without repairs. The boundary is the 2026-05-06 snapshot; historical city boundaries were not reconstructed. Validity checks retain unknown or sentinel coordinates as unknown rather than outside.

| Year | FARS CITY=3340 fatal crashes | CITY=3340 fatalities | Boundary-known fatal crashes | Boundary-known fatalities | SJ-coded crashes without usable coordinates |
|---|---:|---:|---:|---:|---:|
| 2020 | 59 | 63 | 62 | 66 | 0 |
| 2021 | 79 | 80 | 69 | 70 | 10 |
| 2022 | 62 | 66 | 61 | 65 | 2 |
| 2023 | 62 | 63 | 63 | 64 | 0 |
| 2024 | 53 | 54 | 53 | 54 | 0 |

The boundary columns are coordinate-known counts, not complete city fatality totals. The county contains 11 missing-coordinate crashes in 2021 and 2 in 2022. There are also records whose city code and coordinates disagree: the audit reports these explicitly. Do not simply substitute these values for City Vision Zero counts, since FARS includes road facilities outside the SJPD reporting universe.

Person classifications are reproducible in `finish_validation.py` and `fars_observed_code_dictionary.csv`. PER_TYP=5 is pedestrian; 6 or 7 is bicyclist/other pedalcyclist, with label changes across years. Persons on personal conveyances are separate. Motorcycle occupants use in-transport occupant PER_TYP=1,2,9 and BODY_TYP=80–89, the NCSA BODY_TYP classification in the manual PDF p.656. Unknown body types remain a separate category. PER_TYP codes are documented on PDF pp.674–675. Counts of severe injuries in these tables are explicitly limited to people in fatal crashes and cannot measure the city's complete severe-injury burden.

## California Office of Traffic Safety (OTS)

[San Jose 2023 published rankings](https://www.ots.ca.gov/rankings/san-jose-2023/) and [official ranking methodology](https://www.ots.ca.gov/media-and-research/crash-rankings/) were downloaded and parsed directly from agency HTML. `ots_san_jose_2023_published_aggregates_verified.csv` preserves separate units. Page update date is not stated in the raw page; these are published 2023 aggregates.

The page gives 3,294 victims killed and injured, not 3,294 crashes. The 642 speed-related, 406 nighttime and 318 hit-and-run figures are fatal/injury collisions. The 679 DUI figure is arrests, not DUI crashes. OTS nighttime means 9 p.m.–2:59 a.m.; it differs from a lighting-based dark category. Alcohol-involved means a party was classified as having been drinking, and must not be renamed proven DUI causation.

OTS's stated city methodology covers incorporated cities but does not count CHP-taken reports on shared-jurisdiction roads against city rankings. Therefore the OTS city totals are not directly comparable with an all-agency boundary-only collection. OTS obtains crashes from SWITRS, population estimates from the California Department of Finance, and DVMT from Caltrans. Rankings use an empirical Bayesian method incorporating counts, population, and VMT; they are not intersection rankings or simple raw totals.

The Composite row displays 1,934 beneath a victims column, while the methodology describes Composite as a combination of other rankings. It is preserved but barred from interpretation as a distinct count of crashes or people. The page's 2023 DVMT=6,524,310 is citywide daily vehicle miles, not a denominator for individual corridors or intersections.

## Caltrans exposure

[Traffic Census Program](https://dot.ca.gov/programs/traffic-operations/census) lists the original all-vehicle AADT and District 4 ramp workbooks. All ten 2020–2024 workbooks downloaded and passed ZIP/Office archive CRC checks. XLSX sheets were successfully parsed. Full source URLs and update headers are in the manifest. Caltrans's program covers the State Highway System; these workbooks do not provide city-street or pedestrian/bicycle exposure.

`caltrans_aadt_santa_clara_2020_2024.csv` standardizes header differences and retains county=SCL source rows. The back and ahead AADT columns refer to adjacent roadway legs south/west and north/east of a count location, respectively; never add them as if they were complementary traffic directions. The data are estimated AADT based on sampled counts adjusted for season/day variations. The source describes a count year October 1–September 30, a temporal alignment caveat for calendar-year crashes.

| Workbook year | Santa Clara AADT rows | Santa Clara ramp rows | Ramp rows lacking that exact year's count |
|---|---:|---:|---:|
| 2020 | 202 | 681 | 681 |
| 2021 | 207 | 565 | 536 |
| 2022 | 208 | 568 | 294 |
| 2023 | 213 | 423 | 187 |
| 2024 | 216 | 437 | 200 |

Ramp workbooks contain ten historical year columns. Only the column for the indicated analysis year may be used; a populated older column is not a count for the current year. In particular, the 2020 Santa Clara ramp dataset supplies no 2020 counts. Missing values remain blank. A complete five-year ramp exposure ranking cannot be calculated from these files without additional official counts.

[The AADT feature layer](https://caltrans-gis.dot.ca.gov/arcgis/rest/services/CHhighway/Traffic_AADT/FeatureServer/0) yielded 422 Santa Clara point features, reconciled against the server count. [Its layer XML](https://caltrans-gis.dot.ca.gov/arcgis/rest/services/CHhighway/Traffic_AADT/FeatureServer/0/metadata) explicitly identifies `AADT_2023` and a 2026-02-26 metadata revision. It includes repeated route/postmile/count records on nearby carriageway points, so features are not independent exposure observations. The layer's linked item ID resolves to a Truck AADT item with a different URL: this catalog mismatch is retained and documented, and the truck item is not used as all-vehicle exposure evidence.

The subsequent exposure analysis validated a restricted join of crash jurisdiction/route, county, postmile prefix/postmile/suffix, carriageway/ramp, year, AADT leg, and measured route length. `output/exposure_analysis.md` documents 22 released mainline intervals containing 753 canonical CHP crashes (14 KSI crashes) during October 1, 2022–September 30, 2023. Calibrated geometry and matching adjacent Back/Ahead volumes pass strict checks; every numerator ID belongs to the main canonical core. The count-rate formula is `crashes * 1e8 / (AADT * 365 * mean(R_length_miles,L_length_miles))`. Conditional Poisson 95% intervals and direction-length sensitivity bounds are supplied, with assumptions explicit. This is a selected-interval 2023 traffic census-year comparison, not a five-year all-freeway risk ranking. An intersection requires entering volumes for the contributing approaches; dividing by one nearby station is not intersection risk. Other-year, city-street, intersection and ramp rates remain withheld.

The exposure supplement additionally acquired [Caltrans measured postmile line geometry](https://caltrans-gis.dot.ca.gov/arcgis/rest/services/RH/RestAPI/FeatureServer/0) (68 Santa Clara features, reconciled to server count), the independent [SHN direction-coded line layer](https://gisdata.dot.ca.gov/arcgis/rest/services/CHhighway/SHN_Lines/FeatureServer/0), and [Oak Ridge National Laboratory's Poisson confidence-interval method](https://info.ornl.gov/sites/publications/Files/Pub171008.pdf), section 8, printed page 15. The statistical-method document supplies no crash facts. Temporal route versions and postmile prefixes are respected. Raw URLs, last-modified headers and hashes are in the same acquisition manifest.

## City Vision Zero methodology

The current [2025 Vision Zero Action Plan](https://www.sanjoseca.gov/home/showpublisheddocument/118265/638761805841100000) returned HTTP403 on direct access after alternate official URL attempts. The same agency's [legislative attachment for item 25-151](https://sanjose.legistar.com/View.ashx?GUID=D06949E0-EF76-4BDB-9BF4-F78BA3AFA9E9&ID=13758090&M=F) downloaded successfully and parsed. Its first 55 pages are the 2025 plan; appended legislative materials remain intact. The archive is a policy/methodology source, not event records. Page 26 was rendered and visually inspected.

Page 26 documents the 2023 PSC update's 2017–2021 crash-data basis. Fatal and severe injuries receive triple the weight of minor/moderate injuries; the latter receive equal weights. Thus a reproduced person-outcome score `3*(fatalities+severe injuries)+moderate injuries+minor injuries` can be described as informed by the City's severity weighting. Applying this formula to another period or to intersections is an analyst-created score, not the City's official corridor metric or a measure of risk per exposure. A crash-based score `3*KSI crashes+lesser-injury crashes` is a different unit and must be labeled a custom alternative.

The plan describes 30 PSC streets in the 2023 network, including two county expressways and segments overlapping neighboring jurisdictions. Page 27 reports the network's 150 miles, 6% of roadways, and 46% of fatal/severe crashes. These are City-published network descriptors tied to the plan and should not be represented as independently recomputed 2020–2024 percentages. Page 11 explains that SJPD reports encompass city streets and county expressways in San Jose while FARS includes additional facilities. Some contextual figures in the plan cite newspapers or advocacy sources; those secondary-derived claims were not used in this research.

The legislative Attachment A discovered on the 2020 plan agenda is actually a historical 2014–2018 dashboard screenshot, as confirmed by content inspection. It is preserved and marked as such; it is not represented as the full 2020 plan.

## Acquisition interruptions and remaining publication gates

The device ran out of disk space during three downloads. Those attempts are logged as failures; each file was subsequently downloaded successfully after the main collection agent recovered task-owned temporary space. NHTSA HTML overview pages returned HTTP403 to the downloader, while official static data downloads succeeded. No untrusted substitute was used.

Remaining limitations include historical boundary differences, missing FARS coordinates, 2024 FARS annual-release status, and exposure matching outside the 22 qualified intervals. FARS city-code and boundary series must remain visibly separate. The exposure numerator is reconciled to the primary canonical core; the FARS and OTS files remain independent validation and must not be appended to City/CHP crash records or presented as all-crash hotspots.


---