Calculate Minimum Power

Overview

Calculates the minimum power required to operate an agricultural implement on specific terrain, and classifies available tractors by compatibility using an intelligent recommendation system. The endpoint evaluates all available tractors and categorizes them into three suitability levels: OPTIMAL, OVERPOWERED, or INSUFFICIENT.

Tractor Classification System

Tractors are classified based on their power utilization efficiency:

OPTIMAL (Green): Power between 100-125% of required (perfect fit)
OVERPOWERED (Yellow): Power >125% of required (oversized but compatible)
INSUFFICIENT (Red): Power below required (not compatible)

Factors Considered

The calculation considers:

Base power requirement of the implement (HP)
Working depth
Soil type
Terrain slope percentage

Authentication

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

Authorization: Bearer <your_token>

Request Body

implement_id

integer

required

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

terrain_id

integer

required

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

working_depth_m

number

Override for working depth in meters. If not provided, uses the implement’s default working depth.Validation: 0 < working_depth_m <= 1.0Default: Uses implement’s working_depth_cm converted to meters, or 0.25m if not specified

Response

success

boolean

Indicates whether the calculation was successful.

message

string

Human-readable message describing the result.

data

object

Container for calculation results and recommendations.

Show data properties

queryId

integer

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

implement

object

Information about the evaluated implement.

Show implement properties

integer

Implement ID.

name

string

Implement name.

brand

string

Implement brand.

type

string

Type of implement (e.g., plow, harrow, seeder).

power_requirement_hp

number

Base power requirement in horsepower.

terrain

object

Information about the terrain conditions.

Show terrain properties

integer

Terrain ID.

name

string

Terrain name or location.

soil_type

string

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

slope_percentage

number

Terrain slope percentage.

powerRequirement

object

Power requirement calculation results.

Show powerRequirement properties

minimum_power_hp

number

Minimum power required to operate the implement, in horsepower (HP).

calculated_power_hp

number

Calculated power considering all factors, in horsepower (HP).

factors

object

Breakdown of factors that contributed to the power requirement.

Show factors properties

base_power_hp

number

Base implement power requirement.

depth_factor

number

Multiplier based on working depth.

soil_factor

number

Multiplier based on soil type resistance.

slope_factor

number

Multiplier based on terrain slope.

tractorAnalysis

object

Summary of tractor evaluation results.

Show tractorAnalysis properties

total_evaluated

integer

Total number of tractors evaluated.

summary

object

Count of tractors by suitability category.

Show summary properties

optimal

integer

Number of tractors in the OPTIMAL category (100-125% power).

overpowered

integer

Number of tractors in the OVERPOWERED category (>125% power).

insufficient

integer

Number of tractors with INSUFFICIENT power.

recommendations

object

Tractor recommendations ranked by suitability.

Show recommendations properties

top_5

array

Top 5 recommended tractors, prioritizing OPTIMAL then OVERPOWERED by efficiency.

Show tractor item properties

rank

integer

Recommendation rank (1-5).

tractor_id

integer

Tractor ID.

name

string

Tractor name.

brand

string

Tractor brand.

model

string

Tractor model.

engine_power_hp

number

Tractor engine power in horsepower.

suitability

object

Suitability classification details.

Show suitability properties

score

string

Classification score: “OPTIMAL”, “OVERPOWERED”, or “INSUFFICIENT”.

label

string

Human-readable label (e.g., “Óptimo”, “Sobredimensionado”).

color

string

Color indicator: “green”, “yellow”, or “red”.

utilizationPercent

integer

Power utilization percentage: (required_power / tractor_power) × 100.

isCompatible

boolean

Whether the tractor is compatible (OPTIMAL or OVERPOWERED).

best_match

object

The best matching tractor (same structure as top_5 items), or null if no compatible tractors.

Request Example

curl -X POST https://api.maqagr.com/api/calculations/minimum-power \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "implement_id": 1,
    "terrain_id": 1,
    "working_depth_m": 0.3
  }'

Response Example

{
  "success": true,
  "message": "Cálculo de potencia mínima realizado con éxito",
  "data": {
    "queryId": 456,
    "implement": {
      "id": 1,
      "name": "Arado de Discos",
      "brand": "Kuhn",
      "type": "plow",
      "power_requirement_hp": 80
    },
    "terrain": {
      "id": 1,
      "name": "Campo Norte",
      "soil_type": "loam",
      "slope_percentage": 5.2
    },
    "powerRequirement": {
      "minimum_power_hp": 95.5,
      "calculated_power_hp": 98.3,
      "factors": {
        "base_power_hp": 80,
        "depth_factor": 1.15,
        "soil_factor": 1.08,
        "slope_factor": 1.05
      }
    },
    "tractorAnalysis": {
      "total_evaluated": 15,
      "summary": {
        "optimal": 3,
        "overpowered": 8,
        "insufficient": 4
      }
    },
    "recommendations": {
      "top_5": [
        {
          "rank": 1,
          "tractor_id": 5,
          "name": "Case IH Magnum 180",
          "brand": "Case IH",
          "model": "Magnum 180",
          "engine_power_hp": 115,
          "suitability": {
            "score": "OPTIMAL",
            "label": "Óptimo",
            "color": "green",
            "utilizationPercent": 83,
            "isCompatible": true
          }
        },
        {
          "rank": 2,
          "tractor_id": 3,
          "name": "John Deere 6150R",
          "brand": "John Deere",
          "model": "6150R",
          "engine_power_hp": 120,
          "suitability": {
            "score": "OPTIMAL",
            "label": "Óptimo",
            "color": "green",
            "utilizationPercent": 80,
            "isCompatible": true
          }
        },
        {
          "rank": 3,
          "tractor_id": 8,
          "name": "New Holland T7.270",
          "brand": "New Holland",
          "model": "T7.270",
          "engine_power_hp": 150,
          "suitability": {
            "score": "OVERPOWERED",
            "label": "Sobredimensionado",
            "color": "yellow",
            "utilizationPercent": 64,
            "isCompatible": true
          }
        }
      ],
      "best_match": {
        "rank": 1,
        "tractor_id": 5,
        "name": "Case IH Magnum 180",
        "brand": "Case IH",
        "model": "Magnum 180",
        "engine_power_hp": 115,
        "suitability": {
          "score": "OPTIMAL",
          "label": "Óptimo",
          "color": "green",
          "utilizationPercent": 83,
          "isCompatible": true
        }
      }
    }
  }
}

Error Responses

400 Bad Request

object

Returned when required fields are missing or validation fails.

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

Or for validation errors:

{
  "success": false,
  "error": "working_depth_m no puede exceder 1.0 metros (profundidad agrícola máxima)"
}

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 implement or terrain is not found.

{
  "success": false,
  "message": "Implemento 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 procesando la solicitud de cálculo de potencia mínima"
}

Validation Rules

Parameter	Type	Required	Validation
`implement_id`	integer	Yes	Must be > 0
`terrain_id`	integer	Yes	Must be > 0
`working_depth_m`	number	No	0 < value <= 1.0

Suitability Thresholds

The classification system uses the following thresholds:

Classification	Power Range	Utilization %	Compatible
OPTIMAL	100% - 125% of required	80% - 100%	Yes
OVERPOWERED	> 125% of required	< 80%	Yes
INSUFFICIENT	< 100% of required	> 100%	No

Recommendation Priority

The top 5 recommendations are sorted by:

OPTIMAL tractors first, sorted by highest utilization percentage (most efficient)
OVERPOWERED tractors second, sorted by highest utilization percentage (least oversized)
INSUFFICIENT tractors are excluded from recommendations

Notes

Only tractors with status available are evaluated
If no compatible tractors exist, queryId will be null and the response includes only the power requirement calculation
The calculation is persisted to the database only when at least one compatible tractor is found
All calculations include audit logging in the query_history table
The best_match is always the first item in top_5 array, or null if no compatible tractors
Implementation reference: src/controllers/calculationController.js:244-476

Authentication

Tractors

Implements

Terrains

Calculations

Recommendations

Roles

Calculate Minimum Power

Overview

Tractor Classification System

Factors Considered

Authentication

Request Body

Response

Request Example

Response Example

Error Responses

Validation Rules

Suitability Thresholds

Recommendation Priority

Notes

Build docs developers (and LLMs) love

Authentication

Tractors

Implements

Terrains

Calculations

Recommendations

Roles

​Overview

​Tractor Classification System

​Factors Considered

​Authentication

​Request Body

​Response

​Request Example

​Response Example

​Error Responses

​Validation Rules

​Suitability Thresholds

​Recommendation Priority

​Notes

Build docs developers (and LLMs) love

Overview

Tractor Classification System

Factors Considered

Authentication

Request Body

Response

Request Example

Response Example

Error Responses

Validation Rules

Suitability Thresholds

Recommendation Priority

Notes