API Documentation

REST API for water asset intelligence

Access 4M+ water assets, aquifer boundaries, water quality data, and intelligence scores programmatically. Free tier available — no credit card required.

Quick Start View Tiers Swagger UI

API Tiers

FreePublic

No signup required

✓ 200 req/min per IP
✓ All public GET endpoints
✓ 1,000 results per call
✓ JSON + GeoJSON
✓ Attribution encouraged

DeveloperKey required

Free with email signup

✓ 10,000 requests/day
✓ All public endpoints
✓ 5,000 results per call
✓ Priority during traffic spikes
✓ Usage dashboard

ResearchContact

Custom

Academic / non-profit

✓ Unlimited requests
✓ Bulk data exports
✓ Historical snapshots
✓ Custom endpoints
✓ Direct support

Free forever during beta. All tiers include the same data — only rate limits differ.Contact us →

Quick Start

Base URL:

https://api.hi3water.com/api/v1

Try it — fetch Oregon springs with WIS 70+:

curl "https://api.hi3water.com/api/v1/assets?state_province=Oregon&asset_type=spring&min_score=70"

Python example:

import requests

# Search for high-value springs in Oregon
response = requests.get(
    "https://api.hi3water.com/api/v1/assets",
    params={
        "state_province": "Oregon",
        "asset_type": "spring",
        "min_score": 70,
        "limit": 10
    }
)
assets = response.json()
for asset in assets:
    print(f"{asset['name']} — WIS: {asset['water_intelligence_score']}")

Authentication

Public endpoints (listed below) require no authentication. They are rate-limited to 200 requests per minute per IP address.

Authenticated endpoints (write operations, saved assets, alerts) require a JWT Bearer token obtained via /auth/login.

# Authenticated request
curl -H "Authorization: Bearer <your-jwt-token>" \
  "https://api.hi3water.com/api/v1/alerts/saved"

Rate Limits

Endpoint	Limit	Scope
All endpoints (default)	200/minute	Per IP or user
POST /auth/register	5/minute	Per IP
POST /auth/login	10/minute	Per IP
POST /auth/forgot-password	3/minute	Per IP

Exceeding limits returns 429 Too Many Requests. Contact us for higher limits for research projects.

Water Assets

GET/assets

List water assets with filtering, sorting, and pagination

Query Parameters

Name	Type	Description
asset_type	string	Filter by type: spring, aquifer, well, fossil_water, river, lake, reservoir
state_province	string	Filter by state name (e.g., Oregon)
availability	string	Filter: for_sale, private, public_access
min_score	integer	Minimum Water Intelligence Score (0-100)
max_risk	integer	Maximum risk score (0-100)
min_flow	float	Minimum flow rate in GPM
max_depth	float	Maximum well depth in feet
max_price	float	Maximum asking price in USD
min_acreage	float	Minimum acreage
is_verified	boolean	Only verified assets
is_fossil_water	boolean	Only fossil water assets
data_quality	string	Filter: gold, silver, bronze, unverified
skip	integer	Pagination offset (default: 0)
limit	integer	Results per page (default: 20, max: 500)

Example Request

GET https://api.hi3water.com/api/v1/assets?state_province=Oregon&asset_type=spring&min_score=70&limit=10

Response

[
  {
    "id": "412c1fe0-...",
    "name": "Opal Springs",
    "slug": "opal-springs",
    "asset_type": "spring",
    "availability": "private",
    "latitude": 44.818,
    "longitude": -120.829,
    "state_province": "Oregon",
    "county": "Crook County",
    "water_intelligence_score": 97,
    "overall_risk_score": 20,
    "flow_rate_gpm": 2500.0,
    "acreage": 320.0,
    "is_verified": true,
    "is_fossil_water": false,
    "data_quality": "gold"
  }
]

GET/assets/{slug}

Get full asset detail by slug or UUID

Example Request

GET https://api.hi3water.com/api/v1/assets/opal-springs

Response

{
  "id": "412c1fe0-...",
  "name": "Opal Springs",
  "asset_type": "spring",
  "water_intelligence_score": 97,
  "flow_score": 25,
  "geological_score": 20,
  "legal_score": 20,
  "sustainability_score": 19,
  "rarity_score": 13,
  "overall_risk_score": 20,
  "dryup_risk": 5,
  "legal_risk_score": 5,
  "environmental_risk": 10,
  "flow_rate_gpm": 2500.0,
  "depth_ft": 350,
  "aquifer_type": "confined",
  "rock_type": "Basalt",
  "geological_formation": "Deschutes Formation",
  "water_rights_type": "prior_appropriation",
  "water_rights_verified": true,
  "ph_level": 7.1,
  "tds_ppm": 145,
  ...
}

GET/assets/search

Full-text search across asset names, states, and counties

Query Parameters

Name	Type	Description
q	string	Search query (min 2 characters)
limit	integer	Max results (default: 10, max: 50)

Example Request

GET https://api.hi3water.com/api/v1/assets/search?q=opal&limit=5

Response

[{ "name": "Opal Springs", "slug": "opal-springs", ... }]

GET/assets/geojson

GeoJSON FeatureCollection for map rendering

Query Parameters

Name	Type	Description
asset_type	string	Filter by asset type
state_province	string	Filter by state
min_score	integer	Minimum WIS score

Example Request

GET https://api.hi3water.com/api/v1/assets/geojson?state_province=Oregon

Response

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": { "type": "Point", "coordinates": [-120.829, 44.818] },
    "properties": {
      "name": "Opal Springs",
      "asset_type": "spring",
      "water_intelligence_score": 97,
      ...
    }
  }]
}

GET/assets/stats

Platform statistics (public, no auth required)

Example Request

GET https://api.hi3water.com/api/v1/assets/stats

Response

{
  "total_assets": 61833,
  "states_covered": 48,
  "verified_assets": 342
}

GET/assets/{slug}/water-quality

Historical water quality measurements for an asset

Query Parameters

Name	Type	Description
parameter	string	Filter by parameter name (e.g., pH, Nitrate)

Example Request

GET https://api.hi3water.com/api/v1/assets/opal-springs/water-quality

Response

{
  "asset_id": "412c1fe0-...",
  "parameters": ["pH", "Specific conductance", "Nitrate"],
  "total_measurements": 47,
  "data": {
    "pH": [
      { "date": "2020-03-15", "value": 7.1, "unit": "std units" },
      { "date": "2021-06-22", "value": 7.2, "unit": "std units" }
    ]
  }
}

Aquifer Boundaries

GET/aquifers

List aquifer boundaries (without geometry for performance)

Query Parameters

Name	Type	Description
rock_type	string	Filter by rock type (e.g., Sandstone, Carbonate)
limit	integer	Max results (default: 200, max: 500)

Example Request

GET https://api.hi3water.com/api/v1/aquifers?rock_type=Basalt&limit=10

Response

[{
  "id": "...",
  "name": "Columbia Plateau basaltic-rock aquifers",
  "aquifer_code": "110",
  "rock_type": "Sand and gravel",
  "centroid_lat": 46.5,
  "centroid_lon": -119.2
}]

GET/aquifers/geojson

GeoJSON FeatureCollection with aquifer boundary polygons

Query Parameters

Name	Type	Description
rock_type	string	Filter by rock type

Example Request

GET https://api.hi3water.com/api/v1/aquifers/geojson

Response

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": { "type": "MultiPolygon", "coordinates": [...] },
    "properties": { "name": "...", "rock_type": "Basalt", ... }
  }]
}

GET/aquifers/stats

Aquifer boundary statistics by rock type

Example Request

GET https://api.hi3water.com/api/v1/aquifers/stats

Response

{
  "total_boundaries": 4637,
  "by_rock_type": [
    { "rock_type": "Sand and gravel", "count": 1523 },
    { "rock_type": "Sandstone", "count": 987 }
  ]
}

Articles

GET/articles

List published articles

Query Parameters

Name	Type	Description
category	string	Filter: aquifers, water_rights, geology, finding_water, investing
limit	integer	Max results

Example Request

GET https://api.hi3water.com/api/v1/articles?category=aquifers&limit=5

Response

[{
  "id": "...",
  "title": "Understanding Confined vs Unconfined Aquifers",
  "slug": "confined-vs-unconfined-aquifers",
  "category": "aquifers",
  "tier": "free",
  "read_time_minutes": 8,
  "excerpt": "..."
}]

GET/articles/{slug}

Get full article content by slug

Example Request

GET https://api.hi3water.com/api/v1/articles/confined-vs-unconfined-aquifers

Response

{
  "title": "Understanding Confined vs Unconfined Aquifers",
  "content": "# Understanding Confined vs Unconfined...",
  "category": "aquifers",
  "published_at": "2026-04-02T..."
}

Water Intelligence Score (WIS)

Every asset includes a composite WIS score (0-100) broken into five sub-scores:

Field	Max	Description
flow_score	25	Flow rate, consistency, artesian status
geological_score	20	Rock type, aquifer classification, formation
legal_score	20	Water rights type, verification, seniority
sustainability_score	20	Recharge, depth, environmental resilience
rarity_score	15	Asset type scarcity, fossil water, uniqueness

Risk scores (overall_risk_score, dryup_risk, legal_risk_score, environmental_risk) are also available on each asset.

Interactive API Explorer

Try endpoints directly in the browser with our Swagger UI documentation.

Open Swagger UI

Need higher rate limits, bulk data access, or a custom integration? Contact us.