{"openapi":"3.1.0","info":{"title":"TerraFunded Water API","version":"1.2.0","summary":"Wells, well water quality and county rules for any point in Texas.","description":"Read-only JSON over HTTPS. Give a latitude and longitude in Texas and get, in one call: the depth, water level and yield of the home wells already drilled nearby (from every driller report filed with the Texas Water Development Board, refreshed every night); how the county's wells changed over 20 years; how many tested wells nearby were above the drinking-water limits for arsenic, nitrate, fluoride and dissolved solids; and the county's rules for wells, septic, electricity, mobile homes and the agricultural valuation, each with its official source.\n\nEvery figure carries its sample size, its dates and its source. Figures describe wells that exist; they are not a prediction for an undrilled tract.\n\nDocs: https://terrafunded.com/developers · Data dictionary: https://terrafunded.com/developers/data-dictionary · Terms: https://terrafunded.com/developers/terms","termsOfService":"https://terrafunded.com/developers/terms","contact":{"name":"TerraFunded, LLC","email":"rodrigo@terrafunded.com","url":"https://terrafunded.com/developers"},"license":{"name":"Data: CC BY 4.0 (attribution required)","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://terrafunded.com","description":"Production"}],"externalDocs":{"description":"Guide, examples and data dictionary","url":"https://terrafunded.com/developers"},"security":[{"bearer":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Point","description":"Answers for one latitude and longitude."},{"name":"County","description":"Answers for one of the 254 Texas counties."},{"name":"Statewide files","description":"Whole-state tables to load into your own system."},{"name":"Service","description":"Status and this document. No key needed."}],"paths":{"/api/v1/water":{"get":{"tags":["Point"],"operationId":"getWaterAtPoint","summary":"Water at a point: wells, water quality and county rules","description":"The full answer for one point. Wells: the smallest radius of 2, 3, 5, 10 or 15 miles with at least 10 home wells. Water quality: for each indicator, the first radius of 5, 10, 15 miles with at least 10 tested wells. Points outside Texas answer 422.","parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude in decimal degrees (WGS 84). Rounded to 5 decimals, about 1 m.","schema":{"type":"number","minimum":25.8,"maximum":36.6},"example":33.0124},{"name":"lon","in":"query","required":true,"description":"Longitude in decimal degrees (WGS 84), negative in Texas. Rounded to 5 decimals.","schema":{"type":"number","minimum":-106.7,"maximum":-93.5},"example":-94.3655},{"name":"include","in":"query","required":false,"description":"Sections to return, separated by commas. Default: all three.","schema":{"type":"string"},"example":"wells,water_quality","examples":{"all":{"value":"wells,water_quality,county_rules"}}},{"name":"records","in":"query","required":false,"description":"How many individual well reports to list under wells.nearby.nearest_reports, nearest first (0 to 60). 0 leaves the list out.","schema":{"type":"integer","minimum":0,"maximum":60,"default":10}},{"name":"lang","in":"query","required":false,"description":"Language of the county rule answers and of the page links: en (default) or es. Field names are always in English.","schema":{"type":"string","enum":["en","es"],"default":"en"}}],"responses":{"200":{"description":"The answer for the point.","headers":{"ETag":{"schema":{"type":"string"},"description":"Weak validator. Send it back in If-None-Match to get 304 when nothing changed."},"X-Request-Id":{"schema":{"type":"string"}},"X-Data-As-Of":{"schema":{"type":"string"},"description":"Date of the state file behind the well figures."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaterAtPoint"}}}},"400":{"description":"Invalid parameter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-invalid-parameter","title":"Invalid parameter","status":400,"code":"invalid_parameter","detail":"Invalid parameter","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"401":{"description":"API key required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-missing-key","title":"API key required","status":401,"code":"missing_key","detail":"Send your key in the Authorization header (Authorization: Bearer <key>) or in X-API-Key.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"422":{"description":"Point outside Texas","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-outside-texas","title":"Point outside Texas","status":422,"code":"outside_texas","detail":"This API covers Texas only. The point is outside the state's counties.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"503":{"description":"Data source temporarily unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-upstream-unavailable","title":"Data source temporarily unavailable","status":503,"code":"upstream_unavailable","detail":"The well database did not answer. Try again in a few seconds.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}}}}},"/api/v1/widget":{"get":{"tags":["Point"],"operationId":"getWidgetSummary","security":[{"widgetKey":[]}],"summary":"The summary the embeddable widget draws","description":"A shorter answer than /api/v1/water, made for a browser: nearby home wells, the county's 20-year change, tested wells nearby above each limit and the county rules, with no individual well reports. It opens with a publishable widget key (tfp_live_...) passed as ?key=, the same one that goes in the address of the widget frame. An API key works too.","parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude in decimal degrees (WGS 84). Rounded to 5 decimals, about 1 m.","schema":{"type":"number","minimum":25.8,"maximum":36.6},"example":33.0124},{"name":"lon","in":"query","required":true,"description":"Longitude in decimal degrees (WGS 84), negative in Texas. Rounded to 5 decimals.","schema":{"type":"number","minimum":-106.7,"maximum":-93.5},"example":-94.3655},{"name":"key","in":"query","required":true,"schema":{"type":"string"},"description":"Widget key."},{"name":"lang","in":"query","required":false,"description":"Language of the county rule answers and of the page links: en (default) or es. Field names are always in English.","schema":{"type":"string","enum":["en","es"],"default":"en"}}],"responses":{"200":{"description":"The summary for the point.","headers":{"ETag":{"schema":{"type":"string"},"description":"Weak validator. Send it back in If-None-Match to get 304 when nothing changed."},"X-Request-Id":{"schema":{"type":"string"}},"X-Data-As-Of":{"schema":{"type":"string"},"description":"Date of the state file behind the well figures."}},"content":{"application/json":{"schema":{"type":"object","description":"point, location, wells { nearby, county }, water_quality { indicators[] }, county_rules { topics }, caveat, attribution: a subset of WaterAtPoint with the same field names and meanings."}}}},"400":{"description":"Invalid parameter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-invalid-parameter","title":"Invalid parameter","status":400,"code":"invalid_parameter","detail":"Invalid parameter","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"401":{"description":"API key not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-invalid-key","title":"API key not valid","status":401,"code":"invalid_key","detail":"The key is not recognized, was revoked or has expired.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"422":{"description":"Point outside Texas","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-outside-texas","title":"Point outside Texas","status":422,"code":"outside_texas","detail":"This API covers Texas only. The point is outside the state's counties.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"503":{"description":"Data source temporarily unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-upstream-unavailable","title":"Data source temporarily unavailable","status":503,"code":"upstream_unavailable","detail":"The well database did not answer. Try again in a few seconds.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}}}}},"/api/v1/report":{"get":{"tags":["Point"],"operationId":"getWaterReport","security":[{"bearer":[]},{"apiKeyHeader":[]},{"widgetKey":[]}],"summary":"The answer for a point as a PDF report","description":"Three pages to keep or print, with the same figures as /api/v1/water: (1) home wells already drilled around the point, a small map and the nearest driller reports, each linked to the state's official record, with the county's 20-year change; (2) tested wells nearby above each limit and the county rules with their sources; (3) how the analysis was made, the sources and what the report is not. The credit and its link are printed on every page. It opens with a publishable widget key too, so a page can link to it directly.","parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude in decimal degrees (WGS 84). Rounded to 5 decimals, about 1 m.","schema":{"type":"number","minimum":25.8,"maximum":36.6},"example":33.0124},{"name":"lon","in":"query","required":true,"description":"Longitude in decimal degrees (WGS 84), negative in Texas. Rounded to 5 decimals.","schema":{"type":"number","minimum":-106.7,"maximum":-93.5},"example":-94.3655},{"name":"label","in":"query","required":false,"schema":{"type":"string","maxLength":110},"description":"A name for the place (an address or a listing title), printed under the report's title. Plain text, cut at 110 characters."},{"name":"download","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"download=1 asks the browser to save the file (Content-Disposition: attachment) instead of opening it."},{"name":"key","in":"query","required":false,"schema":{"type":"string"},"description":"Widget key or API key, when it is not sent in a header."}],"responses":{"200":{"description":"The report.","headers":{"X-Data-As-Of":{"schema":{"type":"string","format":"date"},"description":"Date of the state's well file behind the report."}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid parameter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-invalid-parameter","title":"Invalid parameter","status":400,"code":"invalid_parameter","detail":"Invalid parameter","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"401":{"description":"API key not valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-invalid-key","title":"API key not valid","status":401,"code":"invalid_key","detail":"The key is not recognized, was revoked or has expired.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"422":{"description":"Point outside Texas","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-outside-texas","title":"Point outside Texas","status":422,"code":"outside_texas","detail":"This API covers Texas only. The point is outside the state's counties.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"503":{"description":"Data source temporarily unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-upstream-unavailable","title":"Data source temporarily unavailable","status":503,"code":"upstream_unavailable","detail":"The well database did not answer. Try again in a few seconds.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}}}}},"/api/v1/water/sample":{"get":{"tags":["Point"],"operationId":"getWaterSample","security":[],"summary":"Live sample answer, no key","description":"The same answer as /api/v1/water for a few fixed points, so you can see a real response before asking for a key.","parameters":[{"name":"place","in":"query","required":false,"schema":{"type":"string","enum":["linden","dripping-springs","lubbock","weatherford"],"default":"linden"},"description":"linden: Linden, Cass County (Northeast Texas); dripping-springs: Dripping Springs, Hays County (Hill Country); lubbock: Lubbock, Lubbock County (South Plains); weatherford: Weatherford, Parker County (west of Fort Worth)"},{"name":"lang","in":"query","required":false,"description":"Language of the county rule answers and of the page links: en (default) or es. Field names are always in English.","schema":{"type":"string","enum":["en","es"],"default":"en"}}],"responses":{"200":{"description":"The answer for the sample point.","headers":{"ETag":{"schema":{"type":"string"},"description":"Weak validator. Send it back in If-None-Match to get 304 when nothing changed."},"X-Request-Id":{"schema":{"type":"string"}},"X-Data-As-Of":{"schema":{"type":"string"},"description":"Date of the state file behind the well figures."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaterAtPoint"}}}},"400":{"description":"Invalid parameter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-invalid-parameter","title":"Invalid parameter","status":400,"code":"invalid_parameter","detail":"Invalid parameter","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"503":{"description":"Data source temporarily unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-upstream-unavailable","title":"Data source temporarily unavailable","status":503,"code":"upstream_unavailable","detail":"The well database did not answer. Try again in a few seconds.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}}}}},"/api/v1/water/batch":{"post":{"tags":["Point"],"operationId":"postWaterBatch","summary":"Water at up to 20 points in one call","description":"Each point succeeds or fails on its own (ok: true or false). By default no individual well reports are listed (records: 0).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Points to answer.","properties":{"points":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","description":"One point.","properties":{"id":{"type":"string","description":"Your own identifier (a parcel id, for example). Returned as is."},"lat":{"type":"number","description":"Latitude."},"lon":{"type":"number","description":"Longitude."}},"required":["lat","lon"]}},"include":{"type":"array","items":{"type":"string","enum":["wells","water_quality","county_rules"]}},"records":{"type":"integer","minimum":0,"maximum":60,"default":0},"lang":{"type":"string","enum":["en","es"],"default":"en"}},"required":["points"]},"example":{"points":[{"id":"parcel-1","lat":33.0124,"lon":-94.3655},{"id":"parcel-2","lat":30.1902,"lon":-98.0867}],"include":["wells","water_quality"]}}}},"responses":{"200":{"description":"One result per point, in the order given.","headers":{"ETag":{"schema":{"type":"string"},"description":"Weak validator. Send it back in If-None-Match to get 304 when nothing changed."},"X-Request-Id":{"schema":{"type":"string"}},"X-Data-As-Of":{"schema":{"type":"string"},"description":"Date of the state file behind the well figures."}},"content":{"application/json":{"schema":{"type":"object","description":"Batch result.","properties":{"count":{"type":"integer","description":"Points received."},"succeeded":{"type":"integer","description":"Points answered."},"failed":{"type":"integer","description":"Points with an error."},"results":{"type":"array","items":{"type":"object","description":"ok: true with the same fields as /api/v1/water (without api and attribution), or ok: false with error { code, status, detail }."}},"attribution":{"$ref":"#/components/schemas/Attribution"}}}}}},"400":{"description":"Invalid parameter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-invalid-parameter","title":"Invalid parameter","status":400,"code":"invalid_parameter","detail":"Invalid parameter","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"401":{"description":"API key required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-missing-key","title":"API key required","status":401,"code":"missing_key","detail":"Send your key in the Authorization header (Authorization: Bearer <key>) or in X-API-Key.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"413":{"description":"Too many points","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-payload-too-large","title":"Too many points","status":413,"code":"payload_too_large","detail":"Too many points","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"503":{"description":"Data source temporarily unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-upstream-unavailable","title":"Data source temporarily unavailable","status":503,"code":"upstream_unavailable","detail":"The well database did not answer. Try again in a few seconds.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}}}}},"/api/v1/wells":{"get":{"tags":["Point"],"operationId":"listWellsAroundPoint","summary":"Individual well reports around a point","description":"Records only, separate from the summaries: one item per driller report, with the state's tracking number and the link to the official report. Owner, address and driller names are never loaded. At most 60 reports per call, nearest first; narrow the radius to page through a dense area.","parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude in decimal degrees (WGS 84). Rounded to 5 decimals, about 1 m.","schema":{"type":"number","minimum":25.8,"maximum":36.6},"example":33.0124},{"name":"lon","in":"query","required":true,"description":"Longitude in decimal degrees (WGS 84), negative in Texas. Rounded to 5 decimals.","schema":{"type":"number","minimum":-106.7,"maximum":-93.5},"example":-94.3655},{"name":"radius_miles","in":"query","required":false,"description":"Search radius, 0.5 to 15 miles. Default: the smallest of 2, 3, 5, 10 or 15 miles with at least 10 home wells.","schema":{"type":"number","minimum":0.5,"maximum":15}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":60,"default":60},"description":"How many reports to return."},{"name":"use","in":"query","required":false,"schema":{"type":"string","enum":["domestic","stock","irrigation","public supply"]},"description":"Keep only wells of this use (applied to the reports the database returned)."}],"responses":{"200":{"description":"Reports, nearest first.","headers":{"ETag":{"schema":{"type":"string"},"description":"Weak validator. Send it back in If-None-Match to get 304 when nothing changed."},"X-Request-Id":{"schema":{"type":"string"}},"X-Data-As-Of":{"schema":{"type":"string"},"description":"Date of the state file behind the well figures."}},"content":{"application/json":{"schema":{"type":"object","description":"Well reports around a point.","properties":{"point":{"$ref":"#/components/schemas/Point"},"county":{"$ref":"#/components/schemas/County"},"data_as_of":{"type":"string","description":"Date of the state file.","format":"date"},"radius_miles":{"type":"number","description":"Radius used."},"wells_in_radius":{"type":"object","description":"How many wells are inside the radius.","properties":{"home_with_depth":{"type":"integer","description":"Domestic wells with a reported depth."},"other_uses":{"type":"object","additionalProperties":{"type":"integer"}}}},"returned":{"type":"integer","description":"Reports in this response."},"truncated":{"type":"boolean","description":"true when the radius holds more reports than were returned."},"reports":{"type":"array","items":{"$ref":"#/components/schemas/WellReport"}},"attribution":{"$ref":"#/components/schemas/Attribution"}}}}}},"400":{"description":"Invalid parameter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-invalid-parameter","title":"Invalid parameter","status":400,"code":"invalid_parameter","detail":"Invalid parameter","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"401":{"description":"API key required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-missing-key","title":"API key required","status":401,"code":"missing_key","detail":"Send your key in the Authorization header (Authorization: Bearer <key>) or in X-API-Key.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"422":{"description":"Point outside Texas","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-outside-texas","title":"Point outside Texas","status":422,"code":"outside_texas","detail":"This API covers Texas only. The point is outside the state's counties.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"503":{"description":"Data source temporarily unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-upstream-unavailable","title":"Data source temporarily unavailable","status":503,"code":"upstream_unavailable","detail":"The well database did not answer. Try again in a few seconds.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}}}}},"/api/v1/counties/{id}":{"get":{"tags":["County"],"operationId":"getCounty","summary":"One county: wells, water quality and rules","parameters":[{"name":"id","in":"path","required":true,"description":"FIPS code (48067), page slug (cass-county) or name (cass).","schema":{"type":"string"},"example":"48067"},{"name":"include","in":"query","required":false,"description":"Sections to return, separated by commas. Default: all three.","schema":{"type":"string"},"example":"wells,water_quality","examples":{"all":{"value":"wells,water_quality,county_rules"}}},{"name":"lang","in":"query","required":false,"description":"Language of the county rule answers and of the page links: en (default) or es. Field names are always in English.","schema":{"type":"string","enum":["en","es"],"default":"en"}}],"responses":{"200":{"description":"The county.","headers":{"ETag":{"schema":{"type":"string"},"description":"Weak validator. Send it back in If-None-Match to get 304 when nothing changed."},"X-Request-Id":{"schema":{"type":"string"}},"X-Data-As-Of":{"schema":{"type":"string"},"description":"Date of the state file behind the well figures."}},"content":{"application/json":{"schema":{"type":"object","description":"County profile.","properties":{"county":{"$ref":"#/components/schemas/County"},"wells":{"$ref":"#/components/schemas/CountyWells"},"water_quality":{"type":"object","description":"indicators[] with county and texas count blocks."},"county_rules":{"$ref":"#/components/schemas/CountyRules"},"attribution":{"$ref":"#/components/schemas/Attribution"}}}}}},"400":{"description":"Invalid parameter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-invalid-parameter","title":"Invalid parameter","status":400,"code":"invalid_parameter","detail":"Invalid parameter","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"401":{"description":"API key required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-missing-key","title":"API key required","status":401,"code":"missing_key","detail":"Send your key in the Authorization header (Authorization: Bearer <key>) or in X-API-Key.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-not-found","title":"Not found","status":404,"code":"not_found","detail":"Not found","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"503":{"description":"Data source temporarily unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-upstream-unavailable","title":"Data source temporarily unavailable","status":503,"code":"upstream_unavailable","detail":"The well database did not answer. Try again in a few seconds.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}}}}},"/api/v1/counties":{"get":{"tags":["Statewide files"],"operationId":"listCounties","summary":"All 254 counties in one table (JSON or CSV)","description":"Home well depth, water level, yield, 20-year change and tested wells above each limit, one row per county. Rebuilt when the nightly refresh publishes a new state file.","parameters":[{"name":"format","in":"query","required":false,"description":"json (default) or csv (a file download).","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"The table.","content":{"application/json":{"schema":{"type":"object","description":"County table.","properties":{"data_as_of":{"type":"object"},"count":{"type":"integer","description":"254."},"counties":{"type":"array","items":{"$ref":"#/components/schemas/CountyRow"}},"attribution":{"$ref":"#/components/schemas/Attribution"}}}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Invalid parameter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-invalid-parameter","title":"Invalid parameter","status":400,"code":"invalid_parameter","detail":"Invalid parameter","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"401":{"description":"API key required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-missing-key","title":"API key required","status":401,"code":"missing_key","detail":"Send your key in the Authorization header (Authorization: Bearer <key>) or in X-API-Key.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"503":{"description":"Data source temporarily unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-upstream-unavailable","title":"Data source temporarily unavailable","status":503,"code":"upstream_unavailable","detail":"The well database did not answer. Try again in a few seconds.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}}}}},"/api/v1/grid":{"get":{"tags":["Statewide files"],"operationId":"getDepthGrid","summary":"Statewide grid of home well depth (JSON or CSV)","description":"Median depth of home wells in every 0.1 degree cell of Texas (about 6 by 7 miles) that has enough wells. A layer you can join to parcels without calling the API per parcel.","parameters":[{"name":"format","in":"query","required":false,"description":"json (default) or csv (a file download).","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"The grid.","content":{"application/json":{"schema":{"type":"object","description":"Depth grid.","properties":{"data_as_of":{"type":"string","description":"Date of the state file.","format":"date"},"step_degrees":{"type":"number","description":"Cell size in degrees."},"count":{"type":"integer","description":"Cells."},"cells":{"type":"array","items":{"type":"object","description":"One cell.","properties":{"south":{"type":"number","description":"South edge, degrees."},"west":{"type":"number","description":"West edge."},"north":{"type":"number","description":"North edge."},"east":{"type":"number","description":"East edge."},"home_wells":{"type":"integer","description":"Home wells with depth in the cell."},"depth_ft_median":{"type":"integer","description":"Median depth, feet."}}}},"attribution":{"$ref":"#/components/schemas/Attribution"}}}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Invalid parameter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-invalid-parameter","title":"Invalid parameter","status":400,"code":"invalid_parameter","detail":"Invalid parameter","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"401":{"description":"API key required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-missing-key","title":"API key required","status":401,"code":"missing_key","detail":"Send your key in the Authorization header (Authorization: Bearer <key>) or in X-API-Key.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}},"503":{"description":"Data source temporarily unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://terrafunded.com/developers#error-upstream-unavailable","title":"Data source temporarily unavailable","status":503,"code":"upstream_unavailable","detail":"The well database did not answer. Try again in a few seconds.","request_id":"req_5f0c1e7a9b2d3c4e10","docs":"https://terrafunded.com/developers"}}}}}}},"/api/v1/status":{"get":{"tags":["Service"],"operationId":"getStatus","security":[],"summary":"What the API is serving right now","description":"Dataset dates, the last nightly refresh, the hash of the state file and sizes. No key needed; safe to poll every few minutes.","responses":{"200":{"description":"Status.","headers":{"ETag":{"schema":{"type":"string"},"description":"Weak validator. Send it back in If-None-Match to get 304 when nothing changed."},"X-Request-Id":{"schema":{"type":"string"}},"X-Data-As-Of":{"schema":{"type":"string"},"description":"Date of the state file behind the well figures."}},"content":{"application/json":{"schema":{"type":"object","description":"Service status.","properties":{"api":{"type":"object"},"status":{"type":"string","description":"ok or degraded.","enum":["ok","degraded"]},"datasets":{"type":"object","description":"wells, water_quality and county_rules, each with its dates, license, DOI and upstream sources."},"coverage":{"type":"object"}}}}}}}}},"/api/v1/openapi.json":{"get":{"tags":["Service"],"operationId":"getOpenApi","security":[],"summary":"This document","responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Authorization: Bearer <your key>"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"The same key in a header of its own."},"widgetKey":{"type":"apiKey","in":"query","name":"key","description":"Publishable widget key (tfp_live_...). Only opens /api/v1/widget and /api/v1/report."}},"schemas":{"Problem":{"type":"object","description":"Error body (RFC 9457 problem details).","properties":{"type":{"type":"string","description":"URL of the error in the docs."},"title":{"type":"string","description":"Short name of the error."},"status":{"type":"integer","description":"HTTP status."},"code":{"type":"string","description":"Stable machine-readable code.","enum":["missing_key","invalid_key","invalid_parameter","missing_parameter","outside_texas","not_found","method_not_allowed","payload_too_large","upstream_unavailable","internal_error"]},"detail":{"type":"string","description":"What went wrong and how to fix it."},"request_id":{"type":"string","description":"Quote it when you write to us."},"docs":{"type":"string","description":"Docs URL."}},"required":["type","title","status","code","detail"]},"Point":{"type":"object","description":"The point, after rounding to 5 decimals.","properties":{"lat":{"type":"number","description":"Latitude."},"lon":{"type":"number","description":"Longitude."}}},"County":{"type":"object","description":"A Texas county.","properties":{"fips":{"type":"string","description":"5-digit FIPS code.","example":"48067"},"name":{"type":"string","description":"Name.","example":"Cass County"},"slug":{"type":"string","description":"Slug of its pages on terrafunded.com.","example":"cass-county"}}},"Attribution":{"type":"object","description":"Credit line that must be shown next to any figure taken from the API (see the terms).","properties":{"required":{"type":"boolean"},"text":{"type":"string","description":"The line."},"url":{"type":"string","description":"Where it must link."},"html":{"type":"string","description":"Ready-made anchor tag."},"terms":{"type":"string","description":"Terms URL."}}},"Range":{"type":"object","description":"Quartiles.","properties":{"p25":{"type":"number","description":"25th percentile."},"median":{"type":"number","description":"Median."},"p75":{"type":"number","description":"75th percentile."}}},"CountBlock":{"type":"object","description":"How many tested wells were above the limit. Below 10 tested wells there is no percentage, only the count.","properties":{"wells_tested":{"type":"integer","description":"Wells with an accepted lab test that decides (above or not above the limit)."},"wells_above_limit":{"type":"integer","description":"Of those, wells whose most recent accepted test was above the limit."},"share_above_limit_pct":{"oneOf":[{"type":"number","description":"Percent above the limit, one decimal. null with fewer than 10 tested wells."},{"type":"null"}]},"share_95_interval_pct":{"oneOf":[{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"95% Wilson interval of that percent. It assumes independent wells; wells near each other are not, so the real interval is wider."},{"type":"null"}]},"wells_undetermined":{"type":"integer","description":"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."},"median_test_year":{"oneOf":[{"type":"integer","description":"Median year of the tests used."},{"type":"null"}]}}},"WellReport":{"type":"object","description":"One driller report (a calculated field is never mixed in here).","properties":{"state_report_id":{"type":"integer","description":"Texas Water Development Board well report tracking number."},"state_report_url":{"type":"string","description":"The official report on the state's site."},"distance_miles":{"type":"number","description":"Great-circle miles from the point."},"lat":{"type":"number","description":"Latitude on the report, 5 decimals."},"lon":{"type":"number","description":"Longitude on the report, 5 decimals."},"use":{"type":"string","description":"Proposed use on the report.","examples":["Domestic","Stock","Irrigation","Public Supply"]},"year_completed":{"oneOf":[{"type":"integer","description":"Year the well was completed."},{"type":"null"}]},"depth_ft":{"oneOf":[{"type":"integer","description":"Total depth, feet."},{"type":"null"}]},"static_water_level_ft":{"oneOf":[{"type":"number","description":"Depth to water when the well was finished, feet below ground."},{"type":"null"}]},"yield_gpm":{"oneOf":[{"type":"number","description":"Reported yield, gallons per minute."},{"type":"null"}]},"yield_test_method":{"oneOf":[{"type":"string","description":"How the yield was measured (Pump, Bailer, Jetted, Estimated, Unknown)."},{"type":"null"}]},"ground_elevation_ft":{"oneOf":[{"type":"integer","description":"Ground elevation from terrain tiles, feet (added by the Well Atlas, not on the report)."},{"type":"null"}]}}},"NearbyWells":{"type":"object","description":"Home wells around the point.","properties":{"population":{"type":"string","description":"Which wells are counted."},"radius_miles":{"type":"number","description":"Radius used."},"radius_rule":{"type":"string","description":"How the radius was chosen."},"wells":{"type":"integer","description":"Home wells with depth inside the radius."},"reliability":{"type":"string","description":"high: 20+ wells within 3 miles with a tight spread; medium: 10+ wells within 5 miles; low: otherwise.","enum":["high","medium","low"]},"depth_ft":{"oneOf":[{"$ref":"#/components/schemas/Range"},{"type":"null"}]},"static_water_level_ft":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/Range"}],"description":"Depth to water, feet below ground, with the number of wells that reported it."},{"type":"null"}]},"yield_gpm":{"oneOf":[{"type":"object","description":"Reported yield.","properties":{"median":{"type":"number","description":"Median, gallons per minute."},"wells":{"type":"integer","description":"Wells that reported a yield."},"share_measured_by_pump_test":{"oneOf":[{"type":"number","description":"Share of those measured with a pump test, 0 to 1."},{"type":"null"}]}}},{"type":"null"}]},"nearest_well_miles":{"oneOf":[{"type":"number","description":"Distance to the nearest home well."},{"type":"null"}]},"wells_completed_last_10_years":{"type":"integer","description":"Of those wells, how many were completed in the last 10 years."},"oldest_completed":{"oneOf":[{"type":"string","description":"Oldest completion date.","format":"date"},{"type":"null"}]},"newest_completed":{"oneOf":[{"type":"string","description":"Newest completion date.","format":"date"},{"type":"null"}]},"other_uses_in_radius":{"type":"object","additionalProperties":{"type":"integer"},"description":"Wells of other uses in the same radius, by use."},"nearest_reports":{"type":"array","items":{"$ref":"#/components/schemas/WellReport"},"description":"The nearest reports of any use (see the records parameter)."}}},"Trend":{"type":"object","description":"Home wells completed in 2003-2007 against 2021-2025, for the county.","properties":{"comparable":{"type":"boolean","description":"false when either period has too few wells."},"periods":{"type":"object","description":"The two periods.","properties":{"early":{"type":"string","description":"2003-2007"},"late":{"type":"string","description":"2021-2025"}}},"rule":{"type":"string","description":"When a change counts."},"depth":{"type":"object","description":"Total depth.","properties":{"early_median_ft":{"type":"number","description":"Median, early period."},"late_median_ft":{"type":"number","description":"Median, late period."},"early_wells":{"type":"integer","description":"Wells, early."},"late_wells":{"type":"integer","description":"Wells, late."},"change_ft":{"type":"number","description":"Late minus early."},"change_pct":{"type":"number","description":"Percent change."},"change_95_interval_ft":{"type":"array","items":{"type":"number"}},"result":{"type":"string","description":"Result.","enum":["deeper","shallower","no_clear_change"]}}},"static_water_level":{"oneOf":[{"type":"object","description":"Depth to water. A positive change means the water stands lower.","properties":{"early_median_ft":{"type":"number","description":"Median, early."},"late_median_ft":{"type":"number","description":"Median, late."},"change_ft":{"type":"number","description":"Late minus early, feet."},"change_95_interval_ft":{"type":"array","items":{"type":"number"}},"result":{"type":"string","description":"Result.","enum":["lower","higher","no_clear_change"]}}},{"type":"null"}]}}},"CountyWells":{"type":"object","description":"Home wells of the county.","properties":{"wells":{"type":"integer","description":"Wells used."},"period":{"type":"string","description":"Which wells: the last 10 years when there are 30 or more, otherwise all since 2001."},"confidence":{"type":"string","description":"standard: 30+ wells; limited: 10 to 29; insufficient: fewer than 10, no figure.","enum":["standard","limited","insufficient"]},"depth_ft":{"oneOf":[{"type":"object","description":"Depth percentiles.","properties":{"p10":{"type":"number","description":"10th."},"p25":{"type":"number","description":"25th."},"median":{"type":"number","description":"Median."},"p75":{"type":"number","description":"75th."},"p90":{"type":"number","description":"90th."}}},{"type":"null"}]},"static_water_level_ft":{"oneOf":[{"$ref":"#/components/schemas/Range"},{"type":"null"}]},"yield_gpm":{"oneOf":[{"$ref":"#/components/schemas/Range"},{"type":"null"}]},"texas_median_depth_ft":{"oneOf":[{"type":"number","description":"Statewide median, for comparison."},{"type":"null"}]},"aquifers":{"type":"array","items":{"type":"object","description":"Aquifer under the county (state maps).","properties":{"name":{"type":"string","description":"Name."},"kind":{"type":"string","description":"major or minor."},"zone":{"oneOf":[{"type":"string","description":"outcrop or subsurface."},{"type":"null"}]},"share_of_county":{"type":"number","description":"Share of the county's area, 0 to 1."}}}},"change_over_20_years":{"$ref":"#/components/schemas/Trend"}}},"WaterQualityIndicator":{"type":"object","description":"One indicator at one limit.","properties":{"id":{"type":"string","description":"Stable id.","enum":["arsenic","nitrate","fluoride","fluoride_secondary","tds"]},"name":{"type":"string","description":"Name."},"limit":{"type":"object","description":"The yardstick.","properties":{"value":{"type":"number","description":"Limit."},"unit":{"type":"string","description":"Unit."},"comparison":{"type":"string","description":"above: equal to the limit does not count."},"basis":{"type":"string","description":"Where the limit comes from."}}},"nearby":{"allOf":[{"$ref":"#/components/schemas/CountBlock"},{"type":"object","description":"Tested wells around the point.","properties":{"radius_miles":{"type":"number","description":"Radius used: 5, 10 or 15."},"radius_rule":{"type":"string","description":"first_radius_with_10_tested_wells, or all_within_15_miles when not even 15 miles gathers 10."},"oldest_test_year":{"oneOf":[{"type":"integer","description":"Oldest test used."},{"type":"null"}]},"newest_test_year":{"oneOf":[{"type":"integer","description":"Newest test used."},{"type":"null"}]},"nearest_tested_well_miles":{"oneOf":[{"type":"number","description":"Distance to the nearest tested well for this indicator."},{"type":"null"}]}}}]},"county":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/CountBlock"},{"type":"object","description":"Published county figure.","properties":{"domestic_share_of_tested_wells_pct":{"oneOf":[{"type":"number","description":"Percent of the tested wells that are domestic."},{"type":"null"}]},"sensitivity_range_pct":{"oneOf":[{"type":"array","items":{"type":"number"},"description":"Lowest and highest percent when the counting rules are changed one at a time."},{"type":"null"}]}}}]},{"type":"null"}]},"texas":{"$ref":"#/components/schemas/CountBlock"}}},"CountyRules":{"type":"object","description":"Rules for rural land in the county.","properties":{"last_review":{"type":"string","description":"Date of the last full review.","format":"date"},"language":{"type":"string","description":"en or es."},"topics":{"type":"object","description":"water_well, septic, electricity, mobile_home_rv, ag_valuation.","additionalProperties":{"type":"object","description":"One topic.","properties":{"status":{"type":"string","description":"answered, no_rule_found_at_this_level, no_official_source_found, under_review or not_reviewed."},"answer":{"oneOf":[{"type":"string","description":"Plain-language answer."},{"type":"null"}]},"verified":{"oneOf":[{"type":"string","description":"Date the answer was verified against its sources.","format":"date"},{"type":"null"}]},"sources":{"type":"array","items":{"type":"object","description":"Official source.","properties":{"url":{"type":"string","description":"URL."},"title":{"oneOf":[{"type":"string","description":"Title."},{"type":"null"}]},"date":{"oneOf":[{"type":"string","description":"Date of the document."},{"type":"null"}]}}}}}}}}},"WaterAtPoint":{"type":"object","description":"Everything about water for one point.","properties":{"api":{"type":"object","description":"API name and version.","properties":{"name":{"type":"string","description":"Name."},"version":{"type":"string","description":"Semantic version."}}},"point":{"$ref":"#/components/schemas/Point"},"location":{"type":"object","description":"Where the point is.","properties":{"state":{"type":"string","description":"TX."},"county":{"$ref":"#/components/schemas/County"},"near_county_line":{"type":"boolean","description":"true within about 0.15 miles of a county line; then other_county names the neighbor."},"other_county":{"oneOf":[{"$ref":"#/components/schemas/County"},{"type":"null"}]}}},"wells":{"type":"object","description":"Driller reports: nearby home wells and the county.","properties":{"data_as_of":{"type":"string","description":"Date of the state file.","format":"date"},"last_checked":{"oneOf":[{"type":"string","description":"Last successful nightly run.","format":"date-time"},{"type":"null"}]},"nearby":{"$ref":"#/components/schemas/NearbyWells"},"county":{"oneOf":[{"$ref":"#/components/schemas/CountyWells"},{"type":"null"}]},"pages":{"type":"object","description":"Pages on terrafunded.com for this point and county."},"attribution":{"$ref":"#/components/schemas/Attribution"},"caveat":{"type":"string","description":"What the figures do and do not say."}}},"water_quality":{"type":"object","description":"Lab tests: tested wells nearby above each limit.","properties":{"data_as_of":{"type":"object","description":"Dates of the two upstream files."},"population":{"type":"string","description":"Which wells are counted."},"radius_rule":{"type":"string","description":"How the radius is chosen."},"tested_wells_within_15_miles":{"type":"integer","description":"Tested wells of any indicator within 15 miles."},"nearest_tested_well_miles":{"oneOf":[{"type":"number","description":"Distance to the nearest tested well."},{"type":"null"}]},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/WaterQualityIndicator"}},"attribution":{"$ref":"#/components/schemas/Attribution"},"caveat":{"type":"string","description":"What the counts do and do not say."}}},"county_rules":{"$ref":"#/components/schemas/CountyRules"},"attribution":{"$ref":"#/components/schemas/Attribution"}}},"CountyRow":{"type":"object","description":"One county in the statewide table. Flat on purpose, so it loads straight into a table. See the data dictionary for every column.","additionalProperties":true}}}}