Daily calories for a pet

Owners rarely know how much their dog should eat, and pack feeding guides are a starting point rather than a target. The energy requirement calculator gives a daily calorie range for one pet, and turns it into cups, cans or grams of the food it actually eats.

Before you start

You need a pet to use pet_id. See Create a pet. A weight or a breed on its own works without one.

Every number is calculated from published veterinary guidelines, and every response says which formulas were used and cites them, so you can show your users where the figure comes from.

Enabled per account

The calculators are in testing and are switched on per account. calculators appears in GET /accounts/features once it's enabled for you. Without it, these endpoints return 403.

1. From a weight

The smallest call is a species and a weight in kg:

curl -X POST -H "x-api-key: YOUR-API-KEY" -H "Content-Type: application/json" \
  -d '{"species": "dog", "weight_kg": 20, "neuter_status": "neutered", "exercise_band": "30_60", "kcal_per_cup": 350}' \
  https://api.thedogapi.com/v1/calculators/energy-requirement

{
  "weight_basis": "current",
  "rer_kcal_per_day": 662,
  "mer": {
    "factor": { "min": 1.4, "mid": 1.5, "max": 1.6 },
    "category": "exercise_30_60",
    "kcal_per_day": { "min": 927, "mid": 993, "max": 1059 },
    "selected_kcal_per_day": 993,
    "portions_per_day": { "cups": { "min": 2.65, "mid": 2.84, "max": 3.03 } }
  },
  "input_quality": "measured",
  "messages": [
    { "code": "provisional_factor", "text": "Part of this estimate uses a factor that is still being reviewed and may change." },
    { "code": "vet_review_diet", "text": "Talk to your vet about adjusting the diet." }
  ],
  "formulas": [
    { "id": "rer", "version": "1.0.0", "provisional": false },
    { "id": "mer-exercise-band", "version": "0.1.0", "provisional": true }
  ],
  "provisional": true,
  "citations": [
    { "id": "aaha-2021-nwm", "short": "AAHA 2021 Nutrition and Weight Management Guidelines", "url": "https://www.aaha.org/resources/2021-aaha-nutrition-and-weight-management-guidelines/weight-reduction-in-the-obese-pet/" }
  ]
}

• rer_kcal_per_day is the resting energy requirement, 70 × weight in kg to the power 0.75.
• mer.kcal_per_day is the maintenance requirement: RER multiplied by a life stage factor. It's a range because the guidelines give a range. Show mid as the target and the range alongside it.
• portions_per_day appears when you send the food's energy: kcal_per_cup, kcal_per_can or kcal_per_kg (grams). Values that can't be right, such as 3 kcal per cup, are rejected; unusual ones are accepted with a food_energy_unusual message.
• factor_choice (low, mid or high) picks which end of the range selected_kcal_per_day uses. The default is mid.

Calories are always per day.

2. Exercise, neuter status and life stage

The factor depends on the pet:

• Adult dogs use their actual daily exercise, not what they should get: lt_30 (under 30 minutes), 30_60 or gt_60 (over an hour). Leave it out and you get mer_by_exercise_band with a result for each band, so you can show all three or ask the owner.
• The exercise factors are the one part of the calculation that is still provisional. Responses that use them say so with provisional: true and a provisional_factor message.

• Neuter status (neutered, intact or unknown) picks the neutered or intact factor. When it's unknown, the range covers both.
• Growing animals use the growth factor. Send life_stage: "growth" with age_months, or just age_months: under 12 months counts as growth.
• Pregnancy and nursing: send reproductive as gestation or lactation.

3. From a breed or a saved pet

With a breed_id and no weight, the calculator uses the top of the breed's standard weight range and says so with a plan_from_breed_band message. It's a sensible default for a new owner who hasn't weighed their pet yet.

With a pet_id, it uses what you've already recorded for that pet: its latest weight, body condition score and exercise, its age, sex and neuter status, and its breed. Anything you send in the request wins over the stored value.

curl -X POST -H "x-api-key: YOUR-API-KEY" -H "Content-Type: application/json" \
  -d '{"pet_id": "{pet_id}"}' \
  https://api.thedogapi.com/v1/calculators/energy-requirement

inputs_assumed lists every value the calculator used and where it came from (request, measured, owner_reported, estimated_photo, pet_record, breed_band), with its date. Use it to tell the owner what the number is based on. See Track weight and exercise for recording those values.

Estimates from photos

If a pet's weight or body condition only comes from a photo, the result is marked input_quality: "estimated" and given as a wider range. improvements lists what would make it more precise, for example a weight from scales:

"improvements": [
  { "input": "weight_kg", "wanted": "measured", "effect": "narrows_range" }
]

Clinician tools that should only use measured values can send "input_policy": "measured_only". Estimated inputs are then skipped, and inputs_assumed.skipped says why.

What it doesn't claim

The result is an estimate for a healthy dog, not a prescription. Every response carries a vet_review_diet message: show it. For a dog that needs to lose weight, use the weight-loss plan instead.

Messages come as a code and an English text. Show the text, or map the code to your own wording.