NutraPlanner nutrition calculator API

Free, read-only nutrition calculators over HTTP: the same formulas as our web calculators, returned as JSON. No sign-up and no API key.

The NutraPlanner calculator API is free and read-only: no API key and no sign-up. It runs 9 calculators (BMI, BMR, TDEE, calorie target, macros, protein, body fat, water and ideal weight). Send GET /api/public/v1/calculators/{name} and get JSON back, up to 120 requests per minute per IP address. The OpenAPI 3.1 description is at /openapi.json.

Overview

The public API runs the formulas behind the free calculators (BMI, BMR, TDEE, calorie and macro targets, protein, body fat, water and ideal body weight) and returns each result as JSON.

No account, no API key, no sign-up.
Stateless: each request is computed and answered. The application does not store request inputs.
Inputs are metric: kilograms and centimetres.
Results are general estimates for healthy adults. They are not medical advice.
There is no API for practitioner or client account data. Client records, notes, meal plans and appointments are only available in the signed-in app.

Quick start

Send a GET request with query parameters. For example, total daily energy expenditure:

Request

curl -G 'https://nutraplanner.com/api/public/v1/calculators/tdee' \
  -d 'sex=female' \
  -d 'age=35' \
  -d 'weight_kg=68' \
  -d 'height_cm=165' \
  -d 'activity=moderate'

Response

{
  "bmr_kcal": 1375,
  "tdee_kcal": 2132,
  "activity_multiplier": 1.55,
  "formula": "mifflin_st_jeor"
}

Authentication

None. Every endpoint is anonymous and CORS is open, so you can call it from a server, a script or a browser. Send no credentials.

Rate limits

120 requests per minute per client IP address, shared across all endpoints. Over the limit, the API answers 429 with a Retry-After header giving the seconds to wait.

Results are deterministic and sent with a Cache-Control header: cache them rather than repeating the same call.

Discovery

Machine-readable descriptions for agents and code generators:

OpenAPI 3.1 description: /openapi.json
API catalog (RFC 9727): /.well-known/api-catalog

Endpoint reference

Every endpoint is a GET under https://nutraplanner.com/api/public/v1. This reference is generated from the same definition the API runs on.

Endpoint, parameter and field descriptions come straight from the API definition, in English.

Body Mass Index

GET /api/public/v1/calculators/bmi

operationId: calculateBmi
Web calculator: BMI calculator

Body Mass Index (kg/m²) with the WHO adult category.

Query parameters: Body Mass Index
Parameter	Type	Description
`weight_kg`required	number, ≥ 20 and ≤ 500	Body weight in kilograms.
`height_cm`required	number, ≥ 100 and ≤ 250	Height in centimetres.

Response fields: Body Mass Index
Field	Type	Description
`bmi`	number	Body Mass Index, kg/m², two decimals. The category is taken from this rounded value, so the two never disagree at a cut-off.
`category`	string: `underweight`, `normal`, `overweight` or `obese`	WHO adult category.

Example request: Body Mass Index

curl -G 'https://nutraplanner.com/api/public/v1/calculators/bmi' \
  -d 'weight_kg=68' \
  -d 'height_cm=165'

Example response: Body Mass Index

{
  "bmi": 24.98,
  "category": "normal"
}

Basal metabolic rate

GET /api/public/v1/calculators/bmr

operationId: calculateBmr
Web calculator: TDEE calculator
Method: How Mifflin-St Jeor, Harris-Benedict and Katch-McArdle compare

Basal metabolic rate (kcal/day) by Mifflin-St Jeor (default), revised Harris-Benedict, or Katch-McArdle.

Query parameters: Basal metabolic rate
Parameter	Type	Description
`sex`required	one of `female` or `male`	Sex used by the equation.
`age`required	number, ≥ 18 and ≤ 120	Age in years (adults).
`weight_kg`required	number, ≥ 20 and ≤ 500	Body weight in kilograms.
`height_cm`required	number, ≥ 100 and ≤ 250	Height in centimetres.
`formula`optional	one of `mifflin_st_jeor`, `harris_benedict` or `katch_mcardle` (default: `mifflin_st_jeor`)	BMR equation. `katch_mcardle` requires `body_fat_pct`.
`body_fat_pct`optional	number, ≥ 2 and ≤ 70	Body-fat percentage. Required only for `formula=katch_mcardle`.Estimate it with the body-fat endpoint

Response fields: Basal metabolic rate
Field	Type	Description
`bmr_kcal`	integer	Basal metabolic rate, kcal/day.
`formula`	string: `mifflin_st_jeor`, `harris_benedict` or `katch_mcardle`	Equation used.

Example request: Basal metabolic rate

curl -G 'https://nutraplanner.com/api/public/v1/calculators/bmr' \
  -d 'sex=female' \
  -d 'age=35' \
  -d 'weight_kg=68' \
  -d 'height_cm=165'

Example response: Basal metabolic rate

{
  "bmr_kcal": 1375,
  "formula": "mifflin_st_jeor"
}

Total daily energy expenditure

GET /api/public/v1/calculators/tdee

operationId: calculateTdee
Web calculator: TDEE calculator
Method: How Mifflin-St Jeor, Harris-Benedict and Katch-McArdle compare

Total daily energy expenditure (kcal/day): BMR multiplied by an activity factor.

Query parameters: Total daily energy expenditure
Parameter	Type	Description
`sex`required	one of `female` or `male`	Sex used by the equation.
`age`required	number, ≥ 18 and ≤ 120	Age in years (adults).
`weight_kg`required	number, ≥ 20 and ≤ 500	Body weight in kilograms.
`height_cm`required	number, ≥ 100 and ≤ 250	Height in centimetres.
`activity`required	one of `sedentary`, `light`, `moderate`, `active` or `very_active`	Activity level; multiplier applied to BMR (sedentary ×1.2, light ×1.375, moderate ×1.55, active ×1.725, very_active ×1.9).
`formula`optional	one of `mifflin_st_jeor`, `harris_benedict` or `katch_mcardle` (default: `mifflin_st_jeor`)	BMR equation. `katch_mcardle` requires `body_fat_pct`.
`body_fat_pct`optional	number, ≥ 2 and ≤ 70	Body-fat percentage. Required only for `formula=katch_mcardle`.Estimate it with the body-fat endpoint

Response fields: Total daily energy expenditure
Field	Type	Description
`bmr_kcal`	integer	Basal metabolic rate, kcal/day.
`tdee_kcal`	integer	Total daily energy expenditure, kcal/day.
`activity_multiplier`	number	Multiplier applied to BMR.
`formula`	string: `mifflin_st_jeor`, `harris_benedict` or `katch_mcardle`	BMR equation used.

Example request: Total daily energy expenditure

curl -G 'https://nutraplanner.com/api/public/v1/calculators/tdee' \
  -d 'sex=female' \
  -d 'age=35' \
  -d 'weight_kg=68' \
  -d 'height_cm=165' \
  -d 'activity=moderate'

Example response: Total daily energy expenditure

{
  "bmr_kcal": 1375,
  "tdee_kcal": 2132,
  "activity_multiplier": 1.55,
  "formula": "mifflin_st_jeor"
}

Daily calorie target

GET /api/public/v1/calculators/calorie-target

operationId: calculateCalorieTarget
Web calculator: Calorie calculator

Daily calorie target (kcal/day): TDEE adjusted for a weight goal (about ±250 or ±500 kcal/day).

Query parameters: Daily calorie target
Parameter	Type	Description
`sex`required	one of `female` or `male`	Sex used by the equation.
`age`required	number, ≥ 18 and ≤ 120	Age in years (adults).
`weight_kg`required	number, ≥ 20 and ≤ 500	Body weight in kilograms.
`height_cm`required	number, ≥ 100 and ≤ 250	Height in centimetres.
`activity`required	one of `sedentary`, `light`, `moderate`, `active` or `very_active`	Activity level; multiplier applied to BMR (sedentary ×1.2, light ×1.375, moderate ×1.55, active ×1.725, very_active ×1.9).
`goal`required	one of `lose`, `mild_lose`, `maintain`, `mild_gain` or `gain`	Weight goal (lose -500, mild_lose -250, maintain +0, mild_gain +250, gain +500 kcal/day).
`formula`optional	one of `mifflin_st_jeor` or `harris_benedict` (default: `mifflin_st_jeor`)	BMR equation.

Response fields: Daily calorie target
Field	Type	Description
`tdee_kcal`	integer	Total daily energy expenditure, kcal/day.
`adjustment_kcal`	integer	Goal adjustment applied to TDEE, kcal/day.
`target_kcal`	integer	Daily calorie target, kcal/day.

Example request: Daily calorie target

curl -G 'https://nutraplanner.com/api/public/v1/calculators/calorie-target' \
  -d 'sex=female' \
  -d 'age=35' \
  -d 'weight_kg=68' \
  -d 'height_cm=165' \
  -d 'activity=moderate' \
  -d 'goal=mild_lose'

Example response: Daily calorie target

{
  "tdee_kcal": 2132,
  "adjustment_kcal": -250,
  "target_kcal": 1882
}

Macronutrient grams from a calorie target

GET /api/public/v1/calculators/macros

operationId: calculateMacros
Web calculator: Macro calculator

Grams of protein, carbohydrate and fat for a calorie target and a split preset (4/4/9 kcal per gram). Every preset keeps protein within the 10–35% AMDR.

Query parameters: Macronutrient grams from a calorie target
Parameter	Type	Description
`calories`required	number, ≥ 500 and ≤ 10000	Daily calorie target, kcal.
`split`optional	one of `balanced`, `low_carb`, `high_protein` or `high_carb` (default: `balanced`)	Split preset as protein/carbs/fat shares (balanced 25/45/30, low_carb 25/35/40, high_protein 30/45/25, high_carb 20/60/20).

Response fields: Macronutrient grams from a calorie target
Field	Type	Description
`protein_g`	integer	Protein, grams/day.
`carbs_g`	integer	Carbohydrate, grams/day.
`fat_g`	integer	Fat, grams/day.
`split`	string: `balanced`, `low_carb`, `high_protein` or `high_carb`	Split preset used.

Example request: Macronutrient grams from a calorie target

curl -G 'https://nutraplanner.com/api/public/v1/calculators/macros' \
  -d 'calories=2000'

Example response: Macronutrient grams from a calorie target

{
  "protein_g": 125,
  "carbs_g": 225,
  "fat_g": 67,
  "split": "balanced"
}

Daily protein target

GET /api/public/v1/calculators/protein

operationId: calculateProteinTarget
Web calculator: Protein calculator
Method: The evidence behind the g/kg goal bands

Daily protein target (grams) from body weight and an activity goal, in g/kg.

Query parameters: Daily protein target
Parameter	Type	Description
`weight_kg`required	number, ≥ 20 and ≤ 500	Body weight in kilograms.
`goal`required	one of `sedentary`, `active`, `build_muscle` or `athlete`	Goal (sedentary 1 g/kg, active 1.2 g/kg, build_muscle 1.6 g/kg, athlete 2 g/kg).

Response fields: Daily protein target
Field	Type	Description
`protein_g`	integer	Protein, grams/day.
`g_per_kg`	number	Grams of protein per kilogram of body weight.

Example request: Daily protein target

curl -G 'https://nutraplanner.com/api/public/v1/calculators/protein' \
  -d 'weight_kg=68' \
  -d 'goal=active'

Example response: Daily protein target

{
  "protein_g": 82,
  "g_per_kg": 1.2
}

Body-fat percentage (U.S. Navy method)

GET /api/public/v1/calculators/body-fat

operationId: calculateBodyFatNavy
Web calculator: Body-fat calculator

Body-fat percentage from circumference measurements by the U.S. Navy method. hip_cm is required for sex=female.

Query parameters: Body-fat percentage (U.S. Navy method)
Parameter	Type	Description
`sex`required	one of `female` or `male`	Sex used by the equation.
`height_cm`required	number, ≥ 100 and ≤ 250	Height in centimetres.
`neck_cm`required	number, ≥ 20 and ≤ 100	Neck circumference, cm.
`waist_cm`required	number, ≥ 40 and ≤ 250	Waist circumference, cm.
`hip_cm`optional	number, ≥ 40 and ≤ 250	Hip circumference, cm. Required for `sex=female`.

Response fields: Body-fat percentage (U.S. Navy method)
Field	Type	Description
`body_fat_pct`	number	Estimated body fat, percent, one decimal (always 2–70).

Example request: Body-fat percentage (U.S. Navy method)

curl -G 'https://nutraplanner.com/api/public/v1/calculators/body-fat' \
  -d 'sex=female' \
  -d 'height_cm=165' \
  -d 'neck_cm=33' \
  -d 'waist_cm=76' \
  -d 'hip_cm=98'

Example response: Body-fat percentage (U.S. Navy method)

{
  "body_fat_pct": 28.9
}

Daily water intake

GET /api/public/v1/calculators/water

operationId: calculateWaterIntake
Web calculator: Water intake calculator

Estimated daily fluid intake (mL) from body weight and activity, in mL per kg.

Query parameters: Daily water intake
Parameter	Type	Description
`weight_kg`required	number, ≥ 20 and ≤ 500	Body weight in kilograms.
`activity`required	one of `sedentary`, `active` or `athlete`	Activity (sedentary 30 mL/kg, active 35 mL/kg, athlete 40 mL/kg).

Response fields: Daily water intake
Field	Type	Description
`water_ml`	integer	Daily fluid, millilitres.
`ml_per_kg`	number	Millilitres per kilogram of body weight.

Example request: Daily water intake

curl -G 'https://nutraplanner.com/api/public/v1/calculators/water' \
  -d 'weight_kg=68' \
  -d 'activity=active'

Example response: Daily water intake

{
  "water_ml": 2380,
  "ml_per_kg": 35
}

Ideal and adjusted body weight (Devine)

GET /api/public/v1/calculators/ideal-weight

operationId: calculateIdealBodyWeight
Web calculator: Ideal weight calculator

Ideal body weight (kg) by the Devine formula. With weight_kg, also the adjusted body weight used clinically when actual weight exceeds ideal.

Query parameters: Ideal and adjusted body weight (Devine)
Parameter	Type	Description
`sex`required	one of `female` or `male`	Sex used by the equation.
`height_cm`required	number, ≥ 100 and ≤ 250	Height in centimetres.
`weight_kg`optional	number, ≥ 20 and ≤ 500	Actual body weight in kilograms, for adjusted body weight.

Response fields: Ideal and adjusted body weight (Devine)
Field	Type	Description
`ideal_weight_kg`	number	Ideal body weight, kg, one decimal.
`adjusted_weight_kg`	number \| null	Adjusted body weight, kg; null when weight_kg is not given.

Example request: Ideal and adjusted body weight (Devine)

curl -G 'https://nutraplanner.com/api/public/v1/calculators/ideal-weight' \
  -d 'sex=female' \
  -d 'height_cm=165' \
  -d 'weight_kg=68'

Example response: Ideal and adjusted body weight (Devine)

{
  "ideal_weight_kg": 56.9,
  "adjusted_weight_kg": 59.7
}

Errors

Errors use RFC 9457 problem details (Content-Type: application/problem+json) with type, title, status and, usually, detail. The type URI points to the matching entry below.

Problem titles are shown exactly as the API returns them, in English.

Invalid query parameters

HTTP 400 · invalid-parameters

A parameter is missing, unknown, repeated or out of range. The errors array names each parameter and what is wrong with it.

Inputs cannot be computed

HTTP 422 · not-computable

Each parameter is valid on its own, but together they cannot be computed, for example formula=katch_mcardle without body_fat_pct.

Unknown calculator

HTTP 404 · not-found

No calculator exists at that path. The endpoint reference lists every one.

Method not allowed

HTTP 405 · method-not-allowed

The API is read-only. Use GET (HEAD and OPTIONS are also answered).

Too many requests

HTTP 429 · rate-limited

The per-IP rate limit was exceeded. Wait the number of seconds in the Retry-After header, then try again.

Internal error

HTTP 500 · internal-error

The server failed while computing the result. The request itself may be fine: try again, and if it keeps failing, contact us.