us-water-quality-data 1.0.0 → 2026.3.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +69 -54
  2. package/data/metadata.json +38 -0
  3. package/data/water-quality.json +1 -0
  4. package/index.d.ts +63 -18
  5. package/index.js +84 -31
  6. package/package.json +18 -17
  7. package/LICENSE +0 -37
  8. package/data.json +0 -132491
  9. package/index.mjs +0 -42
package/README.md CHANGED
@@ -1,6 +1,9 @@
1
1
  # us-water-quality-data
2
2
 
3
- 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.
3
+ U.S. water quality data by ZIP code, packaged for Node.js. Includes violation history, lead/copper levels, radon zone classification, historical score trends, and Home Safety Scores for 41,344 ZIP codes, sourced from 20 federal data sources including the EPA Safe Drinking Water Information System (SDWIS).
4
+
5
+ [![npm](https://img.shields.io/npm/v/us-water-quality-data.svg)](https://www.npmjs.com/package/us-water-quality-data)
6
+ [![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)
4
7
 
5
8
  ## Install
6
9
 
@@ -11,86 +14,98 @@ npm install us-water-quality-data
11
14
  ## Usage
12
15
 
13
16
  ```js
14
- const { getByZip, getByState, getUnsafe, getByContaminant } = require('us-water-quality-data');
17
+ const water = require('us-water-quality-data');
15
18
 
16
- // Lookup by ZIP
17
- const result = getByZip('60172');
18
- console.log(result);
19
+ // Lookup a specific ZIP code
20
+ const nyc = water.lookup('10001');
21
+ console.log(nyc);
19
22
  // {
20
- // zip: '60172',
21
- // city: 'Roselle',
22
- // state: 'IL',
23
- // system_name: 'ROSELLE VILLAGE OF',
24
- // total_violations: 3,
25
- // health_violations: 1,
26
- // lead_level_mg_l: 0.004,
27
- // home_safety_score: 72,
28
- // home_safety_grade: 'C',
29
- // ...
23
+ // zip: '10001', city: 'New York', state: 'NY',
24
+ // home_safety_score: 36, home_safety_grade: 'F',
25
+ // total_violations: 7, lead_level_mg_l: 0.01, ...
30
26
  // }
31
27
 
32
- // All ZIPs in a state
33
- const texas = getByState('TX');
34
- console.log(`${texas.length} ZIP codes in Texas`);
28
+ // All ZIP codes in California
29
+ const ca = water.getState('CA');
30
+ console.log(`${ca.length} ZIP codes in CA`);
35
31
 
36
- // ZIPs with low safety scores
37
- const unsafe = getUnsafe(30);
38
- console.log(`${unsafe.length} ZIPs scored 30 or below`);
32
+ // 10 worst scores in the country
33
+ const worst = water.getWorst(10);
34
+ worst.forEach(z => console.log(`${z.zip} ${z.city}, ${z.state}: ${z.home_safety_score}`));
39
35
 
40
- // ZIPs with a specific contaminant
41
- const pfas = getByContaminant('PFAS');
42
- console.log(`${pfas.length} ZIPs with PFAS detections`);
43
- ```
36
+ // 10 best scores
37
+ const best = water.getBest(10);
44
38
 
45
- ### ESM
39
+ // All states in the dataset
40
+ console.log(water.states()); // ['AK', 'AL', 'AR', ...]
46
41
 
47
- ```js
48
- import { getByZip } from 'us-water-quality-data';
42
+ // Total ZIP codes
43
+ console.log(water.count()); // 41344
44
+
45
+ // Search by city
46
+ const chicago = water.searchCity('chicago');
47
+
48
+ // Dataset metadata
49
+ console.log(water.meta.updated); // '2026-03-24'
50
+ console.log(water.meta.total_zips); // 41344
51
+ console.log(water.meta.states_covered); // 51
49
52
  ```
50
53
 
51
- ### TypeScript
54
+ ### ESM / TypeScript
52
55
 
53
- Full type definitions included (`index.d.ts`).
56
+ ```ts
57
+ import water, { WaterQualityRecord } from 'us-water-quality-data';
58
+
59
+ const record: WaterQualityRecord | null = water.lookup('90210');
60
+ ```
54
61
 
55
62
  ## Data Fields
56
63
 
57
64
  | Field | Type | Description |
58
65
  |-------|------|-------------|
59
- | `zip` | string | 5-digit ZIP code |
66
+ | `zip` | string | 5-digit U.S. ZIP code |
60
67
  | `city` | string | City name |
61
68
  | `state` | string | 2-letter state abbreviation |
69
+ | `home_safety_score` | integer\|null | Composite score 0-100 |
70
+ | `home_safety_grade` | string | Letter grade: A / B / C / D / F |
71
+ | `total_violations` | integer | Total violations in past 5 years |
72
+ | `health_violations` | integer | Health-based violations in past 5 years |
73
+ | `unresolved_violations` | integer | Currently unresolved violations |
74
+ | `contaminant_count` | integer | Distinct health-based contaminants |
75
+ | `health_contaminant_names` | string | Semicolon-separated contaminant names |
76
+ | `lead_level_mg_l` | float\|null | 90th percentile lead level (mg/L) |
77
+ | `copper_level_mg_l` | float\|null | 90th percentile copper level (mg/L) |
78
+ | `radon_zone` | integer\|null | EPA radon zone: 1 (highest) to 3 (lowest) |
79
+ | `water_source` | string | `SW` = Surface Water, `GW` = Groundwater |
62
80
  | `system_name` | string | Primary water system name |
63
81
  | `pwsid` | string | EPA Public Water System ID |
64
- | `population` | number | Population served |
65
- | `water_source` | string | SW=Surface Water, GW=Groundwater |
66
- | `total_violations` | number | Total violations in past 5 years |
67
- | `health_violations` | number | Health-based violations in past 5 years |
68
- | `unresolved_violations` | number | Currently unresolved violations |
69
- | `lead_level_mg_l` | number \| null | 90th percentile lead level (mg/L) |
70
- | `copper_level_mg_l` | number \| null | 90th percentile copper level (mg/L) |
71
- | `radon_zone` | 1 \| 2 \| 3 \| null | EPA radon zone (1=highest risk) |
72
- | `home_safety_score` | number \| null | Composite score 0-100 |
73
- | `home_safety_grade` | string \| null | A/B/C/D/F letter grade |
74
- | `latitude` | number | ZIP centroid latitude |
75
- | `longitude` | number | ZIP centroid longitude |
76
- | `contaminant_count` | number | Distinct health-based contaminants |
77
- | `health_contaminant_names` | string | Semicolon-separated contaminant list |
82
+ | `population` | integer\|null | Population served |
83
+ | `latitude` | float | ZIP centroid latitude |
84
+ | `longitude` | float | ZIP centroid longitude |
85
+
86
+ ## Coverage
87
+
88
+ - **ZIP codes:** 41,344
89
+ - **States:** All 50 U.S. states + D.C.
90
+ - **Data sources:** 20 federal sources
91
+ - **Violation window:** Rolling 5 years
92
+ - **Historical trends:** Score history backfilled 2021--2025 with violation timeline data
93
+ - **Update frequency:** New npm versions published with each dataset refresh
78
94
 
79
95
  ## Data Source
80
96
 
81
- [U.S. EPA Safe Drinking Water Information System (SDWIS)](https://www.epa.gov/enviro/sdwis-search). Updated weekly via [ZipCheckup](https://zipcheckup.com).
97
+ Data is derived from 20 federal sources including the [EPA Safe Drinking Water Information System (SDWIS)](https://www.epa.gov/enviro/sdwis-overview), FEMA NFIP, Census ACS, EPA ECHO, and others. Lead and copper levels come from EPA Lead and Copper Rule (LCR) sampling. Radon zones are county-level EPA classifications.
82
98
 
83
- ## Methodology
99
+ **Home Safety Score** is a composite 0-100 score that penalizes health-based violations, unresolved violations, lead exceedances, and contaminant count. Methodology: [zipcheckup.com/about/home-safety-score/](https://zipcheckup.com/about/home-safety-score/)
84
100
 
85
- - **Violations:** 5-year window, resolved violations weighted at 0.25x
86
- - **Lead/Copper:** 90th percentile from LCR sample results
87
- - **Radon:** EPA county-level zone mapping
88
- - **Home Safety Score:** Composite 0-100 from water violations + lead + radon + flood risk
101
+ ## Related
89
102
 
90
- Full methodology: [zipcheckup.com/methodology/](https://zipcheckup.com/methodology/)
103
+ - **Live site:** [zipcheckup.com](https://zipcheckup.com) — free water quality reports by ZIP
104
+ - **Open dataset (CSV/JSON):** [zipcheckup.com/data/](https://zipcheckup.com/data/)
105
+ - **API:** [api.zipcheckup.com/v1/](https://api.zipcheckup.com/v1/)
91
106
 
92
107
  ## License
93
108
 
94
- Data: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — free to use with attribution.
109
+ Data: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Code: MIT.
95
110
 
96
- Code: MIT
111
+ > Data by [ZipCheckup.com](https://zipcheckup.com) — sourced from EPA SDWIS.
package/data/metadata.json ADDED
@@ -0,0 +1,38 @@
1
+ {
2
+ "name": "ZipCheckup U.S. Water Quality Dataset",
3
+ "description": "Water quality violations, lead/copper levels, radon zones, and Home Safety Scores for U.S. ZIP codes. Based on EPA SDWIS data.",
4
+ "license": "CC-BY-4.0",
5
+ "source": "U.S. EPA Safe Drinking Water Information System (SDWIS)",
6
+ "url": "https://zipcheckup.com",
7
+ "updated": "2026-03-27",
8
+ "total_zips": 41344,
9
+ "total_violations": 275456,
10
+ "states_covered": 51,
11
+ "fields": {
12
+ "zip": "5-digit ZIP code",
13
+ "city": "City name",
14
+ "state": "2-letter state abbreviation",
15
+ "system_name": "Primary water system name",
16
+ "pwsid": "EPA Public Water System ID",
17
+ "population": "Population served",
18
+ "water_source": "SW=Surface Water, GW=Groundwater",
19
+ "total_violations": "Total violations in past 5 years",
20
+ "health_violations": "Health-based violations in past 5 years",
21
+ "unresolved_violations": "Currently unresolved violations",
22
+ "lead_level_mg_l": "90th percentile lead level (mg/L), null if no data",
23
+ "copper_level_mg_l": "90th percentile copper level (mg/L), null if no data",
24
+ "radon_zone": "EPA radon zone (1=highest, 3=lowest), null if no data",
25
+ "home_safety_score": "Composite score 0-100, null if insufficient data",
26
+ "home_safety_grade": "A/B/C/D/F letter grade",
27
+ "latitude": "ZIP centroid latitude",
28
+ "longitude": "ZIP centroid longitude",
29
+ "contaminant_count": "Number of distinct health-based contaminants",
30
+ "health_contaminant_names": "Semicolon-separated list of health-based contaminant names",
31
+ "ccr_contaminant_count": "Number of contaminants reported in Consumer Confidence Report (CCR), null if no CCR data",
32
+ "ccr_violation_count": "Number of violations reported in CCR, null if no CCR data",
33
+ "enforcement_action_count": "Total EPA/state enforcement actions against the water system",
34
+ "enforcement_health_violations": "Number of health-based violations from enforcement records",
35
+ "has_active_issues": "Whether the system has currently active enforcement or violation issues (true/false)",
36
+ "boil_water_advisories": "Number of boil water advisories issued"
37
+ }
38
+ }