Calculate Power Loss

Overview

Calculates the power losses of a tractor operating on specific terrain conditions. The calculation considers multiple loss factors including slope, altitude, rolling resistance, and wheel slippage. The result is persisted in the database with audit logging for historical tracking and analysis.

Loss Factors Calculated

The endpoint computes four primary loss factors:

Slope Loss: Power loss due to terrain inclination
Altitude Loss: Power loss due to altitude above sea level (air density reduction)
Rolling Resistance: Loss according to soil type (based on ASABE D497.7 Cone Index)
Slippage Loss: Power loss due to wheel slip

Authentication

This endpoint requires authentication via Bearer token in the Authorization header.

Authorization: Bearer <your_token>

Request Body

tractor_id

integer

required

ID of the tractor to evaluate. Must be a positive integer greater than 0.

terrain_id

integer

required

ID of the terrain where the tractor will operate. Must be a positive integer greater than 0.

working_speed_kmh

number

required

Working speed in kilometers per hour. Must be greater than 0 and less than 40 km/h.Validation: 0 < working_speed_kmh < 40

carried_objects_weight_kg

number

default:"0"

Weight of carried objects/implements in kilograms. Must be non-negative.Default: 0Validation: carried_objects_weight_kg >= 0

slippage_percent

number

default:"10"

Wheel slippage percentage. Typical values range from 5% to 20%.Default: 10

Response

success

boolean

Indicates whether the calculation was successful.

message

string

Human-readable message describing the result.

data

object

Container for calculation results.

Show data properties

queryId

integer

Unique identifier for this calculation query, used for audit and history tracking.

tractor

object

Information about the evaluated tractor.

Show tractor properties

brand

string

Tractor brand name.

model

string

Tractor model name.

terrain

object

Information about the terrain conditions.

Show terrain properties

name

string

Terrain name or location.

soil_type

string

Type of soil (e.g., clay, loam, sand, firm, soft).

losses

object

Breakdown of power losses by factor.

Show losses properties

slope_loss_hp

number

Power loss due to terrain slope, in horsepower (HP).

altitude_loss_hp

number

Power loss due to altitude (air density), in horsepower (HP).

rolling_resistance_loss_hp

number

Power loss due to rolling resistance based on soil type, in horsepower (HP).

slippage_loss_hp

number

Power loss due to wheel slippage, in horsepower (HP).

total_loss_hp

number

Total combined power loss, in horsepower (HP).

net_power_hp

number

Available net power after all losses, in horsepower (HP).

engine_power_hp

number

Gross engine power of the tractor, in horsepower (HP).

efficiency_percentage

number

Overall efficiency percentage: (net_power / engine_power) × 100.

Request Example

curl -X POST https://api.maqagr.com/api/calculations/power-loss \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tractor_id": 1,
    "terrain_id": 1,
    "working_speed_kmh": 7.5,
    "carried_objects_weight_kg": 500,
    "slippage_percent": 10
  }'

Response Example

{
  "success": true,
  "message": "Cálculo realizado con éxito",
  "data": {
    "queryId": 123,
    "tractor": {
      "brand": "John Deere",
      "model": "7230R"
    },
    "terrain": {
      "name": "Campo Norte",
      "soil_type": "loam"
    },
    "losses": {
      "slope_loss_hp": 12.5,
      "altitude_loss_hp": 8.3,
      "rolling_resistance_loss_hp": 15.7,
      "slippage_loss_hp": 9.2,
      "total_loss_hp": 45.7
    },
    "net_power_hp": 184.3,
    "engine_power_hp": 230,
    "efficiency_percentage": 80.13
  }
}

Error Responses

400 Bad Request

object

Returned when required fields are missing or validation fails.

{
  "success": false,
  "message": "Faltan campos requeridos: tractor_id, terrain_id, working_speed_kmh"
}

Or for validation errors:

{
  "error": "working_speed_kmh debe ser menor a 40 km/h (velocidad agrícola razonable)"
}

401 Unauthorized

object

Returned when the authentication token is missing or invalid.

{
  "success": false,
  "message": "Token no proporcionado o inválido"
}

404 Not Found

object

Returned when the specified tractor or terrain is not found.

{
  "success": false,
  "message": "Tractor no encontrado"
}

Or:

{
  "success": false,
  "message": "Terreno no encontrado"
}

500 Internal Server Error

object

Returned when an unexpected error occurs during processing.

{
  "success": false,
  "message": "Error interno del servidor"
}

Validation Rules

Parameter	Type	Required	Validation
`tractor_id`	integer	Yes	Must be > 0
`terrain_id`	integer	Yes	Must be > 0
`working_speed_kmh`	number	Yes	0 < value < 40
`carried_objects_weight_kg`	number	Yes	Must be >= 0
`slippage_percent`	number	No	Defaults to 10

Soil Type Cone Index (Cn) Mapping

The rolling resistance calculation uses the ASABE D497.7 Cone Index standard:

Soil Type	Cone Index (Cn)
Clay / Arcilla	45
Loam / Franco	35 (default)
Sand / Arena	25
Firm / Firme	50
Soft / Suave	20

Notes

All calculations are persisted to the database with audit logging
The queryId can be used to retrieve calculation history via the /api/calculations/history endpoint
Default temperature of 15°C is used if not specified in terrain data
Results are logged for analytics and performance tracking (src/controllers/calculationController.js:144-152)

Authentication

Tractors

Implements

Terrains

Calculations

Recommendations

Roles

Calculate Power Loss

Overview

Loss Factors Calculated

Authentication

Request Body

Response

Request Example

Response Example

Error Responses

Validation Rules

Soil Type Cone Index (Cn) Mapping

Notes

Build docs developers (and LLMs) love

Authentication

Tractors

Implements

Terrains

Calculations

Recommendations

Roles

​Overview

​Loss Factors Calculated

​Authentication

​Request Body

​Response

​Request Example

​Response Example

​Error Responses

​Validation Rules

​Soil Type Cone Index (Cn) Mapping

​Notes

Build docs developers (and LLMs) love

Overview

Loss Factors Calculated

Authentication

Request Body

Response

Request Example

Response Example

Error Responses

Validation Rules

Soil Type Cone Index (Cn) Mapping

Notes