Calculate Endpoint

Calculate pool chemical dosing recommendations based on current water readings.

Request

POST /api/calculate/
Content-Type: application/json

No authentication required.

Request Body

Field	Type	Required	Description
`formula_id`	string	Yes	The formula to use for calculations. See valid formula IDs.
`readings`	object	Yes	Current pool water readings as `{reading_id: value}`. See valid reading IDs.
`pool`	object	Yes	Pool information. See pool object.
`target_levels`	array	No	Override default target ranges. See target levels.
`substitutions`	object	No	Override default treatments for specific readings. See substitutions.

Pool Object

Field	Type	Required	Description
`gallons`	number	Yes	Pool volume in gallons.
`water_type`	string	No	Sanitization method. One of: `chlorine`, `salt_water`, `bromine`, `minerals`, `copper`, `ozone`, `uv`.
`wall_type`	string	No	Pool wall material. One of: `vinyl`, `plaster`, `fiberglass`, `concrete`, `pebble`. Affects calcium hardness targets for concrete/plaster/pebble pools.

Target Levels

An array of objects to override default target ranges:

Field	Type	Description
`id`	string	The reading ID to override (e.g. `"fc"`, `"ph"`).
`min`	number	Minimum target value.
`max`	number	Maximum target value.

Substitutions

A mapping of reading ID to treatment overrides:

{
  "fc": { "up": "dichlor" },
  "ph": { "down": "sodium_bisulfate" }
}

Field	Type	Description
`up`	string	Treatment ID to use when raising this reading.
`down`	string	Treatment ID to use when lowering this reading.

Response

{
  "actions": [
    {
      "readings": [
        { "id": "fc", "name": "Free Chlorine", "short_name": "Free Chlorine", "units": "ppm" }
      ],
      "type": "raise",
      "treatment": {
        "id": "calc_hypo",
        "name": "Chlorine Granules",
        "type": "dryChemical",
        "concentration": 67,
        "description": "Pre-dissolve in a bucket of water and pour into pool.",
        "waitMinutes": 15
      },
      "ounces": 3.58,
      "treatment_options": [
        { "id": "chlorine_tablets", "name": "Chlorine Tablets", "type": "task", "concentration": 100, "description": "...", "waitMinutes": 60 },
        { "id": "calc_hypo", "name": "Chlorine Granules", "type": "dryChemical", "concentration": 67, "description": "...", "waitMinutes": 15 },
        { "id": "na_hclo", "name": "Liquid Chlorine", "type": "liquidChemical", "concentration": 10, "description": "...", "waitMinutes": 60 }
      ]
    }
  ]
}

Action Object

Field	Type	Description
`readings`	array	The readings this action addresses. Each has `id`, `name`, `short_name`, `units`.
`type`	string	One of `"raise"`, `"lower"`, `"special"`, `"warning"`.
`treatment`	object	The recommended treatment. See treatment object.
`ounces`	number	Amount in ounces. For `"warning"` type: the delta from ideal (negative = too low, positive = too high). For `"special"` wait actions: the number of minutes to wait.
`treatment_options`	array	Alternative treatments the user can choose from.

Treatment Object

Field	Type	Description
`id`	string	Treatment identifier.
`name`	string	Display name.
`type`	string	One of `"dryChemical"`, `"liquidChemical"`, `"task"`, `"calculation"`, `"warning"`, `"wait"`.
`concentration`	number	Percent active ingredient (0-100).
`description`	string	Instructions for applying the treatment.
`waitMinutes`	number	Minutes to wait after applying before the next treatment.
`taskName`	string	(Optional) Short name for task-type treatments.

Formula IDs

ID	Description
`chlorine_cal_hypo`	Standard chlorine pools (calcium hypochlorite). The most common formula.
`salt`	Salt water / salt chlorine generator pools.
`bromine`	Bromine-sanitized pools and hot tubs.
`minerals`	Mineral sanitization system pools.

Reading IDs

ID	Name	Units	Typical Range	Description
`fc`	Free Chlorine	ppm	0 - 10	Active sanitizer level. Target: 1-3 ppm.
`tc`	Total Chlorine	ppm	0 - 10	Free + combined chlorine.
`cc`	Combined Chlorine	ppm	0 - 1	Calculated as TC - FC. Indicates chloramines.
`ph`	pH	—	6.0 - 8.5	Water acidity/alkalinity. Target: 7.2-7.6.
`ta`	Total Alkalinity	ppm	0 - 300	pH buffer capacity. Target: 80-120 ppm.
`cya`	Cyanuric Acid (CYA)	ppm	0 - 300	UV stabilizer for chlorine. Target: 30-50 ppm.
`ch`	Calcium Hardness	ppm	0 - 800	Calcium content. Target: 175-225 ppm (200-275 for plaster/concrete).
`salt`	Salt	ppm	0 - 5000	Salinity level for salt water pools. Target: 2700-3400 ppm.
`bro`	Bromine	ppm	0 - 20	Bromine sanitizer level. Target: 3-5 ppm.
`copper`	Copper	ppm	0 - 3	Copper ion level. Target: 0.2-0.4 ppm.
`disox`	Dissolved Oxygen	ppm	0 - 20	Dissolved oxygen level.

Treatment IDs

ID	Name	Type
`calc_hypo`	Chlorine Granules	dryChemical
`na_hclo`	Liquid Chlorine	liquidChemical
`chlorine_tablets`	Chlorine Tablets	task
`dichlor`	Dichlor	dryChemical
`bromine`	Bromine	dryChemical
`cal_chlor`	Hardness Increaser	dryChemical
`soda_ash`	Soda Ash (pH Up)	dryChemical
`m_acid`	Muriatic Acid (pH Down)	liquidChemical
`sodium_bisulfate`	Dry Acid (pH Down)	dryChemical
`baking_soda`	Baking Soda (TA Up)	dryChemical
`alk_increaser`	Alkalinity Increaser	dryChemical
`ph_increaser`	pH Increaser	dryChemical
`cya`	Stabilizer (CYA)	dryChemical
`salt`	Pool Salt	dryChemical
`swg_up`	Increase SWG Output	task
`shock`	Shock	dryChemical
`drain`	Drain & Refill	task

Examples

Basic Request

curl -X POST https://api.poolcloud.com/api/calculate/ \
  -H "Content-Type: application/json" \
  -d '{
    "formula_id": "chlorine_cal_hypo",
    "readings": {
      "fc": 0,
      "ph": 7.2,
      "ta": 80,
      "tc": 0,
      "cya": 0,
      "ch": 0
    },
    "pool": {
      "gallons": 10000,
      "water_type": "chlorine",
      "wall_type": "plaster"
    }
  }'

With Substitutions

Use dichlor instead of the default chlorine treatment:

curl -X POST https://api.poolcloud.com/api/calculate/ \
  -H "Content-Type: application/json" \
  -d '{
    "formula_id": "chlorine_cal_hypo",
    "readings": { "fc": 1, "ph": 7.4 },
    "pool": { "gallons": 15000 },
    "substitutions": {
      "fc": { "up": "dichlor" }
    }
  }'

With Custom Target Levels

Override the default target range for free chlorine:

curl -X POST https://api.poolcloud.com/api/calculate/ \
  -H "Content-Type: application/json" \
  -d '{
    "formula_id": "chlorine_cal_hypo",
    "readings": { "fc": 2, "ph": 7.5 },
    "pool": { "gallons": 20000 },
    "target_levels": [
      { "id": "fc", "min": 3, "max": 5 }
    ]
  }'

Error Responses

400 — Bad Request

Returned when the formula runner encounters an error (e.g. invalid formula_id).

{ "error": "Calculation failed: Unknown formula_id \"invalid\". Valid IDs: chlorine_cal_hypo, salt, bromine, minerals" }

422 — Validation Error

Returned when the request body fails schema validation (e.g. missing required fields).

{
  "error": "Validation error",
  "detail": "...",
  "field_errors": [...]
}

504 — Timeout

Returned if the calculation takes longer than 10 seconds.

{ "error": "Calculation timed out" }

Home How Formulas Work