Data dictionary
Every field the Water API returns, with its type, its unit and the rule behind it. Then the sources with their dates, and the checks the numbers passed before going out.
Sources, processing and refresh
| Dataset | Public sources | What we do to them | Refresh | License and DOI |
|---|---|---|---|---|
| Wells | Texas Water Development Board, Submitted Driller's Reports database; U.S. Census Bureau, 2024 cartographic boundary file, counties (1:500,000) | Keep water-supply wells (domestic, stock, irrigation, public supply; new wells and replacements). Drop coordinates that are missing, outside Texas or flagged by the driller as wrong, and mark whether each point falls in its reported county. Classify each driller's rock log into layer types. Read ground elevation from terrain tiles. Never load owner, address or driller names. | Every night, from the state's file of that day | CC BY 4.0, 10.5281/zenodo.24126380 |
| Water quality | Texas Water Development Board, Groundwater Database (file of 2026-11-13); Water Quality Portal (USGS and EPA) (file of 2026-11-15) | Accept only results with a known sampling protocol. Match the same well across the two sources so it counts once. Turn the three ways nitrate is stored into nitrogen. Take each well's most recent accepted test since 1992 and compare it with the limit; a 'less than' above the limit leaves the well undetermined. | Versioned releases; the upstream databases change slowly | CC BY 4.0, 10.5281/zenodo.24287393 |
| County rules | County and district rules, state agency maps and lists; each answer links its own | Read the rule, write a plain answer, keep the quote and the document behind it, record the date verified. | Reviewed by hand; each answer has its date | CC BY 4.0 |
| County of a point | U.S. Census Bureau, 2024 cartographic boundary file, counties (1:500,000) | Texas counties, lines simplified by at most about 11 m (62,284 vertices). | With each Census release | Public domain |
Methods in full: wells, water quality. What is ours and not in the public files: the cleaning rules, the per-point and per-county summaries, the 20-year comparison with its bootstrap intervals, the layer classification of the drillers' logs, the water quality counting rules and their study, and the county rule answers.
GET /api/v1/water
Location
| Field | Type | Meaning |
|---|---|---|
point | object | The point, after rounding to 5 decimals. |
point.lat | number | Latitude. |
point.lon | number | Longitude. |
location | object | Where the point is. |
location.state | string | TX. |
location.county | object | A Texas county. |
location.county.fips | string | 5-digit FIPS code. |
location.county.name | string | Name. |
location.county.slug | string | Slug of its pages on terrafunded.com. |
location.near_county_line | boolean | true within about 0.15 miles of a county line; then other_county names the neighbor. |
location.other_county | object or null | A Texas county. |
location.other_county.fips | string | 5-digit FIPS code. |
location.other_county.name | string | Name. |
location.other_county.slug | string | Slug of its pages on terrafunded.com. |
wells.nearby
| Field | Type | Meaning |
|---|---|---|
population | string | Which wells are counted. |
radius_miles | number | Radius used. |
radius_rule | string | How the radius was chosen. |
wells | integer | Home wells with depth inside the radius. |
reliability | string: high, medium, low | high: 20+ wells within 3 miles with a tight spread; medium: 10+ wells within 5 miles; low: otherwise. |
depth_ft | object or null | Quartiles. |
depth_ft.p25 | number | 25th percentile. |
depth_ft.median | number | Median. |
depth_ft.p75 | number | 75th percentile. |
static_water_level_ft | object or null | Depth to water, feet below ground, with the number of wells that reported it. |
static_water_level_ft.p25 | number | 25th percentile. |
static_water_level_ft.median | number | Median. |
static_water_level_ft.p75 | number | 75th percentile. |
yield_gpm | object or null | Reported yield. |
yield_gpm.median | number | Median, gallons per minute. |
yield_gpm.wells | integer | Wells that reported a yield. |
yield_gpm.share_measured_by_pump_test | number or null | Share of those measured with a pump test, 0 to 1. |
nearest_well_miles | number or null | Distance to the nearest home well. |
wells_completed_last_10_years | integer | Of those wells, how many were completed in the last 10 years. |
oldest_completed | string or null | Oldest completion date. |
newest_completed | string or null | Newest completion date. |
other_uses_in_radius | object | Wells of other uses in the same radius, by use. |
nearest_reports[] | array of object | The nearest reports of any use (see the records parameter). |
wells.county
| Field | Type | Meaning |
|---|---|---|
wells | integer | Wells used. |
period | string | Which wells: the last 10 years when there are 30 or more, otherwise all since 2001. |
confidence | string: standard, limited, insufficient | standard: 30+ wells; limited: 10 to 29; insufficient: fewer than 10, no figure. |
depth_ft | object or null | Depth percentiles. |
depth_ft.p10 | number | 10th. |
depth_ft.p25 | number | 25th. |
depth_ft.median | number | Median. |
depth_ft.p75 | number | 75th. |
depth_ft.p90 | number | 90th. |
static_water_level_ft | object or null | Quartiles. |
static_water_level_ft.p25 | number | 25th percentile. |
static_water_level_ft.median | number | Median. |
static_water_level_ft.p75 | number | 75th percentile. |
yield_gpm | object or null | Quartiles. |
yield_gpm.p25 | number | 25th percentile. |
yield_gpm.median | number | Median. |
yield_gpm.p75 | number | 75th percentile. |
texas_median_depth_ft | number or null | Statewide median, for comparison. |
aquifers[] | array of object | Aquifer under the county (state maps). |
aquifers[].name | string | Name. |
aquifers[].kind | string | major or minor. |
aquifers[].zone | string or null | outcrop or subsurface. |
aquifers[].share_of_county | number | Share of the county's area, 0 to 1. |
change_over_20_years | object | Home wells completed in 2003-2007 against 2021-2025, for the county. |
change_over_20_years.comparable | boolean | false when either period has too few wells. |
change_over_20_years.periods | object | The two periods. |
change_over_20_years.periods.early | string | 2003-2007 |
change_over_20_years.periods.late | string | 2021-2025 |
change_over_20_years.rule | string | When a change counts. |
change_over_20_years.depth | object | Total depth. |
change_over_20_years.depth.early_median_ft | number | Median, early period. |
change_over_20_years.depth.late_median_ft | number | Median, late period. |
change_over_20_years.depth.early_wells | integer | Wells, early. |
change_over_20_years.depth.late_wells | integer | Wells, late. |
change_over_20_years.depth.change_ft | number | Late minus early. |
change_over_20_years.depth.change_pct | number | Percent change. |
change_over_20_years.depth.change_95_interval_ft[] | array of number | |
change_over_20_years.depth.result | string: deeper, shallower, no_clear_change | Result. |
change_over_20_years.static_water_level | object or null | Depth to water. A positive change means the water stands lower. |
change_over_20_years.static_water_level.early_median_ft | number | Median, early. |
change_over_20_years.static_water_level.late_median_ft | number | Median, late. |
change_over_20_years.static_water_level.change_ft | number | Late minus early, feet. |
change_over_20_years.static_water_level.change_95_interval_ft[] | array of number | |
change_over_20_years.static_water_level.result | string: lower, higher, no_clear_change | Result. |
A well report
Returned by /api/v1/wells and under wells.nearby.nearest_reports. One driller report as filed with the state, plus two added fields: the distance to your point and the ground elevation.
| Field | Type | Meaning |
|---|---|---|
state_report_id | integer | Texas Water Development Board well report tracking number. |
state_report_url | string | The official report on the state's site. |
distance_miles | number | Great-circle miles from the point. |
lat | number | Latitude on the report, 5 decimals. |
lon | number | Longitude on the report, 5 decimals. |
use | string | Proposed use on the report. |
year_completed | integer or null | Year the well was completed. |
depth_ft | integer or null | Total depth, feet. |
static_water_level_ft | number or null | Depth to water when the well was finished, feet below ground. |
yield_gpm | number or null | Reported yield, gallons per minute. |
yield_test_method | string or null | How the yield was measured (Pump, Bailer, Jetted, Estimated, Unknown). |
ground_elevation_ft | integer or null | Ground elevation from terrain tiles, feet (added by the Well Atlas, not on the report). |
water_quality.indicators[]
| id | What is measured | Limit | Where the limit comes from |
|---|---|---|---|
arsenic | Arsenic (dissolved) | above 10 µg/L | Federal drinking-water standard for public water systems (EPA maximum contaminant level) |
nitrate | Nitrate (as nitrogen) | above 10 mg/L as N | Federal drinking-water standard for public water systems (EPA maximum contaminant level) |
fluoride | Fluoride (dissolved) | above 4 mg/L | Federal drinking-water standard for public water systems (EPA maximum contaminant level) |
fluoride_secondary | Fluoride (dissolved), secondary level | above 2 mg/L | Federal secondary level (EPA secondary maximum contaminant level) |
tds | Total dissolved solids | above 1,000 mg/L | Texas secondary level for public water systems |
The limits are standards for public water systems, used here as a yardstick. No law applies them to a private well. "Above" means greater than the limit; equal does not count.
Fields
| Field | Type | Meaning |
|---|---|---|
id | string: arsenic, nitrate, fluoride, fluoride_secondary, tds | Stable id. |
name | string | Name. |
limit | object | The yardstick. |
limit.value | number | Limit. |
limit.unit | string | Unit. |
limit.comparison | string | above: equal to the limit does not count. |
limit.basis | string | Where the limit comes from. |
nearby | object | Tested wells around the point. |
nearby.wells_tested | integer | Wells with an accepted lab test that decides (above or not above the limit). |
nearby.wells_above_limit | integer | Of those, wells whose most recent accepted test was above the limit. |
nearby.share_above_limit_pct | number or null | Percent above the limit, one decimal. null with fewer than 10 tested wells. |
nearby.share_95_interval_pct[] | array of number or null | 95% Wilson interval of that percent. It assumes independent wells; wells near each other are not, so the real interval is wider. |
nearby.wells_undetermined | integer | Wells whose most recent test could not be compared with the limit (a 'less than' with a reporting limit above it). They are left out of wells_tested. |
nearby.median_test_year | integer or null | Median year of the tests used. |
nearby.radius_miles | number | Radius used: 5, 10 or 15. |
nearby.radius_rule | string | first_radius_with_10_tested_wells, or all_within_15_miles when not even 15 miles gathers 10. |
nearby.oldest_test_year | integer or null | Oldest test used. |
nearby.newest_test_year | integer or null | Newest test used. |
nearby.nearest_tested_well_miles | number or null | Distance to the nearest tested well for this indicator. |
county | object or null | Published county figure. |
county.wells_tested | integer | Wells with an accepted lab test that decides (above or not above the limit). |
county.wells_above_limit | integer | Of those, wells whose most recent accepted test was above the limit. |
county.share_above_limit_pct | number or null | Percent above the limit, one decimal. null with fewer than 10 tested wells. |
county.share_95_interval_pct[] | array of number or null | 95% Wilson interval of that percent. It assumes independent wells; wells near each other are not, so the real interval is wider. |
county.wells_undetermined | integer | Wells whose most recent test could not be compared with the limit (a 'less than' with a reporting limit above it). They are left out of wells_tested. |
county.median_test_year | integer or null | Median year of the tests used. |
county.domestic_share_of_tested_wells_pct | number or null | Percent of the tested wells that are domestic. |
county.sensitivity_range_pct[] | array of number or null | Lowest and highest percent when the counting rules are changed one at a time. |
texas | object | How many tested wells were above the limit. Below 10 tested wells there is no percentage, only the count. |
texas.wells_tested | integer | Wells with an accepted lab test that decides (above or not above the limit). |
texas.wells_above_limit | integer | Of those, wells whose most recent accepted test was above the limit. |
texas.share_above_limit_pct | number or null | Percent above the limit, one decimal. null with fewer than 10 tested wells. |
texas.share_95_interval_pct[] | array of number or null | 95% Wilson interval of that percent. It assumes independent wells; wells near each other are not, so the real interval is wider. |
texas.wells_undetermined | integer | Wells whose most recent test could not be compared with the limit (a 'less than' with a reporting limit above it). They are left out of wells_tested. |
texas.median_test_year | integer or null | Median year of the tests used. |
Counts are of wells that someone chose to test, using each well's most recent accepted lab test since 1992. They are not a sample of all wells and say nothing certain about the water of a particular well or an undrilled tract. The only way to know a well's water is to test it. The limits are standards for public water systems, used here as a yardstick; no law applies them to a private well.
county_rules
| Field | Type | Meaning |
|---|---|---|
last_review | string | Date of the last full review. |
language | string | en or es. |
topics | object | water_well, septic, electricity, mobile_home_rv, ag_valuation. |
Topics: water_well (groundwater district, permit or registration for a home well), septic (who permits it and what it costs), electricity (utilities with certificated territory in the county), mobile_home_rv (county orders that apply), ag_valuation (the agricultural appraisal rule and the appraisal district). Summaries of county and district rules with their official sources and the date each was verified. Rules change: confirm with the office named in the source before acting. Not legal advice.
Statewide files
/api/v1/counties (one row per county)
| Column | Meaning |
|---|---|
fips, name, slug | County FIPS code, name and the slug of its pages on terrafunded.com. |
centroid_lat, centroid_lon | A point inside the county (not the geometric center), decimal degrees. |
home_wells | Home wells with a reported depth used for the county figure. |
wells_period | last_10_years when the county has 30 or more wells in that period, otherwise since_2001. |
wells_confidence | standard (30+ wells), limited (10 to 29), insufficient (fewer than 10: the depth columns are empty). |
depth_ft_p25, depth_ft_median, depth_ft_p75 | Quartiles of total well depth, feet. |
static_water_level_ft_median | Median depth to water when the well was finished, feet below ground. |
yield_gpm_median | Median reported yield, gallons per minute. |
depth_change_20yr_result, depth_change_20yr_pct | 2003 to 2007 against 2021 to 2025: deeper, shallower or no_clear_change, and the percent change of the median. |
water_level_change_20yr_result, water_level_change_20yr_ft | The same for the depth to water: lower, higher or no_clear_change, and the change in feet (positive: the water stands lower). |
main_aquifers | Aquifers under at least 10% of the county, from the state's maps. |
{indicator}_wells_tested | Wells with an accepted lab test since 1992 that decides, for arsenic, nitrate, fluoride (4 mg/L) and tds. |
{indicator}_wells_above_limit | Of those, wells whose most recent accepted test was above the limit. |
{indicator}_share_above_limit_pct | Percent above the limit, one decimal. Empty with fewer than 10 tested wells. |
/api/v1/grid (one row per cell)
| Column | Meaning |
|---|---|
south, west, north, east | Edges of the cell in decimal degrees. Cells are 0.1 by 0.1 degrees, about 6.9 miles north to south and 5.6 to 6.2 miles east to west in Texas. |
home_wells | Home wells with a reported depth in the cell. Cells with fewer than 3 are left out. |
depth_ft_median | Median total depth of those wells, feet. |
How the numbers were checked
- Wells. The API reads the same database functions as the Texas Well Atlas pages, so a point or a county returns the figures the atlas shows. Each nightly run stops before loading anything if a download fails or more than 0.5% of wells get no elevation.
- Water quality, statewide and county. The table behind the API reproduces to the well the five published statewide figures (for example, 742 of 10,379 wells above the arsenic limit) and all 1,016 county figures of the atlas. The build refuses to write the table otherwise.
- Water quality, nearby. The count of tested wells around a point equals the study's own count for 96.9% of 8,475 test wells and is within one well for 99.9%.
- Intervals. The Wilson intervals computed by the API equal the published ones in all 874 county figures with 10 or more wells.
- Counties. The point the atlas keeps for each of the 254 counties falls inside that county's boundary.
- Three independent programs. The atlas's water quality figures were computed by three programs that share no code, and the study's results by ours and two written only from the rules.
The water quality atlas had no external review by specialists; its pages say so. The lab results are public and anyone can recount them with the published rules.
