us-water-quality-data 1.0.0

package/LICENSE

@@ -0,0 +1,37 @@
+Creative Commons Attribution 4.0 International (CC BY 4.0)
+
+Copyright (c) 2026 ZipCheckup (https://zipcheckup.com)
+
+You are free to:
+- Share — copy and redistribute the material in any medium or format
+- Adapt — remix, transform, and build upon the material for any purpose, even commercially
+
+Under the following terms:
+- Attribution — You must give appropriate credit, provide a link to the license,
+  and indicate if changes were made.
+
+Full license text: https://creativecommons.org/licenses/by/4.0/legalcode
+
+---
+
+Code portions (index.js, index.mjs) are licensed under the MIT License:
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# us-water-quality-data
+
+U.S. water quality data for 6,300+ ZIP codes. Violations, lead/copper levels, radon zones, and Home Safety Scores based on EPA SDWIS data.
+
+## Install
+
+```bash
+npm install us-water-quality-data
+```
+
+## Usage
+
+```js
+const { getByZip, getByState, getUnsafe, getByContaminant } = require('us-water-quality-data');
+
+// Lookup by ZIP
+const result = getByZip('60172');
+console.log(result);
+// {
+//   zip: '60172',
+//   city: 'Roselle',
+//   state: 'IL',
+//   system_name: 'ROSELLE VILLAGE OF',
+//   total_violations: 3,
+//   health_violations: 1,
+//   lead_level_mg_l: 0.004,
+//   home_safety_score: 72,
+//   home_safety_grade: 'C',
+//   ...
+// }
+
+// All ZIPs in a state
+const texas = getByState('TX');
+console.log(`${texas.length} ZIP codes in Texas`);
+
+// ZIPs with low safety scores
+const unsafe = getUnsafe(30);
+console.log(`${unsafe.length} ZIPs scored 30 or below`);
+
+// ZIPs with a specific contaminant
+const pfas = getByContaminant('PFAS');
+console.log(`${pfas.length} ZIPs with PFAS detections`);
+```
+
+### ESM
+
+```js
+import { getByZip } from 'us-water-quality-data';
+```
+
+### TypeScript
+
+Full type definitions included (`index.d.ts`).
+
+## Data Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `zip` | string | 5-digit ZIP code |
+| `city` | string | City name |
+| `state` | string | 2-letter state abbreviation |
+| `system_name` | string | Primary water system name |
+| `pwsid` | string | EPA Public Water System ID |
+| `population` | number | Population served |
+| `water_source` | string | SW=Surface Water, GW=Groundwater |
+| `total_violations` | number | Total violations in past 5 years |
+| `health_violations` | number | Health-based violations in past 5 years |
+| `unresolved_violations` | number | Currently unresolved violations |
+| `lead_level_mg_l` | number \| null | 90th percentile lead level (mg/L) |
+| `copper_level_mg_l` | number \| null | 90th percentile copper level (mg/L) |
+| `radon_zone` | 1 \| 2 \| 3 \| null | EPA radon zone (1=highest risk) |
+| `home_safety_score` | number \| null | Composite score 0-100 |
+| `home_safety_grade` | string \| null | A/B/C/D/F letter grade |
+| `latitude` | number | ZIP centroid latitude |
+| `longitude` | number | ZIP centroid longitude |
+| `contaminant_count` | number | Distinct health-based contaminants |
+| `health_contaminant_names` | string | Semicolon-separated contaminant list |
+
+## Data Source
+
+[U.S. EPA Safe Drinking Water Information System (SDWIS)](https://www.epa.gov/enviro/sdwis-search). Updated weekly via [ZipCheckup](https://zipcheckup.com).
+
+## Methodology
+
+- **Violations:** 5-year window, resolved violations weighted at 0.25x
+- **Lead/Copper:** 90th percentile from LCR sample results
+- **Radon:** EPA county-level zone mapping
+- **Home Safety Score:** Composite 0-100 from water violations + lead + radon + flood risk
+
+Full methodology: [zipcheckup.com/methodology/](https://zipcheckup.com/methodology/)
+
+## License
+
+Data: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — free to use with attribution.
+
+Code: MIT