# Water Well API
> Water-well maths as an API, computed locally and deterministically — the casing, yield and pump-setting numbers a well driller, pump installer or rural homeowner works to. The casing-volume endpoint gives the standing water in a well: gallons per foot = π/4 · diameter² × 12 ÷ 231 (about 1.47 gal/ft for a 6-inch casing, 0.65 for a 4-inch) times the water column, so 100 feet of water in a 6-inch casing holds about 147 gallons — the figure you need to purge a few well volumes before sampling or to dose shock-chlorination. The specific-capacity endpoint turns a drawdown test into how freely the well gives up water: specific capacity = pumping rate ÷ drawdown (gpm per foot), and the projected yield ≈ that times the available drawdown — 15 GPM at 20 feet of drawdown is 0.75 gpm/ft and roughly 45 GPM at 60 feet. The pump-setting endpoint gives the depth to hang the pump: static water level + drawdown + submergence (typically 10–20 feet), so it never air-locks as the level draws down, with a check against the well depth. Everything is computed locally and deterministically, so it is instant and private. Ideal for well-drilling and pump-installer apps, rural-water and homeowner tools, hydrogeology calculators, and trade aids. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. Estimates — verify with a real drawdown test. For pump power/head use a pump API; for well chlorination use a pool-chemistry API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/wellpump-api/..."
```

## Pricing
- **Free** (Free) — 430 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 11,400 calls/Mo, 6 req/s
- **Pro** ($17/Mo) — 76,500 calls/Mo, 15 req/s
- **Mega** ($51/Mo) — 253,000 calls/Mo, 36 req/s

## Endpoints

### Well

#### `GET /v1/casing-volume` — Standing water in a casing

**Parameters:**
- `casing_diameter_in` (query, required, string) — Casing diameter in inches Example: `6`
- `water_column_ft` (query, required, string) — Standing water column in feet Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wellpump-api/v1/casing-volume?casing_diameter_in=6&water_column_ft=100"
```

**Response:**
```json
{
    "data": {
        "note": "Standing water = gallons per foot × the water column, where gallons per foot = π/4 · diameter² × 12 ÷ 231 (≈ 1.47 gal/ft for a 6-inch casing, 0.65 for a 4-inch). It is what you need for shock-chlorination dosing and to purge a few well volumes before sampling.",
        "inputs": {
            "water_column_ft": 100,
            "casing_diameter_in": 6
        },
        "gallons_per_foot": 1.469,
        "standing_water_gallons": 146.9
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:58.779Z",
        "request_id": "d652c8bc-8e3e-4ec2-9dee-9d904377351e"
    },
    "status": "ok",
    "message": "Casing volume",
    "success": true
}
```

#### `GET /v1/pump-setting` — Pump setting depth

**Parameters:**
- `static_water_level_ft` (query, required, string) — Static water level (depth to water) in feet Example: `50`
- `drawdown_ft` (query, required, string) — Drawdown in feet Example: `30`
- `submergence_ft` (query, optional, string) — Submergence below pumping level (default 20) Example: `20`
- `well_depth_ft` (query, optional, string) — Total well depth in feet Example: `120`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wellpump-api/v1/pump-setting?static_water_level_ft=50&drawdown_ft=30&submergence_ft=20&well_depth_ft=120"
```

**Response:**
```json
{
    "data": {
        "note": "Set the pump below the pumping water level (static level + drawdown) with enough submergence — usually 10–20 ft — so it never breaks suction and air-locks as the level draws down. Keep it above the screen and the bottom sediment, and leave room for a dry season dropping the static level further.",
        "inputs": {
            "drawdown_ft": 30,
            "submergence_ft": 20,
            "static_water_level_ft": 50
        },
        "pump_setting_depth_ft": 100,
        "pumping_water_level_ft": 80,
        "clearance_above_bottom_ft": 20
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:58.847Z",
        "request_id": "9ce26b27-ed08-4acb-94b7-d1b84fa59d6a"
    },
    "status": "ok",
    "message": "Pump setting",
    "success": true
}
```

#### `GET /v1/specific-capacity` — Specific capacity & yield

**Parameters:**
- `pumping_rate_gpm` (query, required, string) — Pumping rate in GPM Example: `15`
- `drawdown_ft` (query, required, string) — Drawdown in feet Example: `20`
- `available_drawdown_ft` (query, optional, string) — Available drawdown for projected yield Example: `60`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wellpump-api/v1/specific-capacity?pumping_rate_gpm=15&drawdown_ft=20&available_drawdown_ft=60"
```

**Response:**
```json
{
    "data": {
        "note": "Specific capacity = pumping rate ÷ drawdown (the drop in water level while pumping) — gallons per minute per foot. It measures how freely the well gives up water. Projected yield ≈ specific capacity × the available drawdown, but the relationship flattens at higher rates, so treat it as an upper guide and test at the real rate.",
        "inputs": {
            "drawdown_ft": 20,
            "pumping_rate_gpm": 15
        },
        "projected_yield_gpm": 45,
        "specific_capacity_gpm_ft": 0.75
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:58.900Z",
        "request_id": "bda164a5-7bfc-4ab4-b9fe-97e414d56dd4"
    },
    "status": "ok",
    "message": "Specific capacity",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/wellpump-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "US units (feet, inches, gallons, GPM). gal/ft = π/4·D²·12/231; specific capacity = rate/drawdown; pump setting = static + drawdown + submergence. Estimates — verify with a real drawdown test. For pump power/head use a pump API; for well chlorination use a pool-chemistry API.",
        "service": "wellpump-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/pump-setting": "Pump setting depth below the pumping water level.",
            "GET /v1/casing-volume": "Standing water gallons and gallons per foot for a casing.",
            "GET /v1/specific-capacity": "Specific capacity (gpm/ft) and projected yield from a pumping test."
        },
        "description": "Water-well maths: standing water in a casing, specific capacity and projected yield from a drawdown test, and the pump setting depth."
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:58.970Z",
        "request_id": "9c7e6292-48fd-4b75-a5bf-ee657133c4b3"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/wellpump-api
OpenAPI spec: https://www.oanor.com/api/wellpump-api/openapi.json