Skip to main content
POST
/
api
/
recommendations
/
generate
curl -X POST https://api.maqagr.com/api/recommendations/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "terrain_id": 1,
    "implement_id": 2,
    "working_depth_m": 0.25,
    "work_type": "tillage"
  }'

{
  "success": true,
  "message": "Recomendaciones generadas exitosamente",
  "data": {
    "queryId": 10,
    "implement": {
      "id": 2,
      "name": "Arado de discos",
      "brand": "Baldan",
      "type": "plow"
    },
    "terrain": {
      "id": 1,
      "name": "Parcela Norte",
      "soil_type": "clay",
      "slope_percentage": 15
    },
    "powerRequirement": {
      "minimum_power_hp": 95.5
    },
    "recommendations": [
      {
        "rank": 1,
        "tractor": {
          "id": 3,
          "name": "John Deere 6130M",
          "brand": "John Deere",
          "model": "6130M",
          "engine_power_hp": 130,
          "traction_type": "4x4"
        },
        "score": {
          "total": 87.5
        },
        "classification": {
          "label": "OPTIMAL"
        },
        "explanation": "Alta eficiencia energética (85% utilización). Ajuste óptimo de potencia."
      }
    ]
  }
}

​
Overview

Generates smart tractor recommendations by analyzing terrain characteristics, implement requirements, and available tractors. The algorithm evaluates each tractor using a multi-criteria scoring system and returns the top 5 ranked recommendations.
This endpoint validates that the terrain belongs to the authenticated user.

​
Authentication

Requires JWT authentication token in the Authorization header. 
Authorization: Bearer <token>

​
Request Body

​
terrain_id
number
required
ID of the terrain where the work will be performed. Must belong to the authenticated user.
​
implement_id
number
required
ID of the implement to be used.
​
working_depth_m
number
default:"0.25"
Working depth in meters. If not provided, uses the implement’s default working depth.
​
work_type
string
default:"general"
Type of work to be performed.Options: tillage, planting, harvesting, transport, general

​
Response

​
success
boolean
Indicates if the request was successful.
​
message
string
Success message.
​
data
object

​
Algorithm Details

The recommendation engine follows this workflow:
  1. Validates terrain ownership (must belong to authenticated user)
  2. Calculates minimum power required for the implement on the terrain
  3. Analyzes terrain characteristics (slope, soil type)
  4. Evaluates each available tractor with multi-criteria scoring:
    • Efficiency: Optimal power utilization
    • Traction: Compatibility with slope and soil
    • Soil: Adequacy for terrain type
    • Economic: Cost-benefit ratio
    • Availability: Tractor status
  5. Returns top 5 ranked tractors with detailed explanations
  6. Persists top 3 recommendations to database

​
Classification Labels

  • OPTIMAL: Perfect power fit for the task
  • GOOD: Good balance between power and need
  • ACCEPTABLE: Functional but not ideal
  • OVERPOWERED: Oversized for the task
curl -X POST https://api.maqagr.com/api/recommendations/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "terrain_id": 1,
    "implement_id": 2,
    "working_depth_m": 0.25,
    "work_type": "tillage"
  }'

{
  "success": true,
  "message": "Recomendaciones generadas exitosamente",
  "data": {
    "queryId": 10,
    "implement": {
      "id": 2,
      "name": "Arado de discos",
      "brand": "Baldan",
      "type": "plow"
    },
    "terrain": {
      "id": 1,
      "name": "Parcela Norte",
      "soil_type": "clay",
      "slope_percentage": 15
    },
    "powerRequirement": {
      "minimum_power_hp": 95.5
    },
    "recommendations": [
      {
        "rank": 1,
        "tractor": {
          "id": 3,
          "name": "John Deere 6130M",
          "brand": "John Deere",
          "model": "6130M",
          "engine_power_hp": 130,
          "traction_type": "4x4"
        },
        "score": {
          "total": 87.5
        },
        "classification": {
          "label": "OPTIMAL"
        },
        "explanation": "Alta eficiencia energética (85% utilización). Ajuste óptimo de potencia."
      }
    ]
  }
}

​
Source Code Reference

  • Route: src/routes/recommendation.routes.js:139
  • Controller: src/controllers/recommendationController.js:141
  • Service: src/services/recommendationService.js

Build docs developers (and LLMs) love

Get started for freeTalk to us