Skip to main content

Rotations

Introduction​

Rotations or Crop Organiser is a functionality within the management module that allows to assign crops per field in a quick and easy way without the need to generate a sowing record. Through this functionality, users have the possibility to register detailed information about the crop, such as the variety sown, the number of hectares to be sown, the estimated yield and other relevant details.

To make use of the endpoints detailed below, the developer must activate in the extension's claimset the permissions found under the name 'Campaign'.

APIs​

GET​

List of all rotations for fields that the user has permissions for, across all campaigns.

GET /api/rotations

Query params​

In the query string you can send the following parameters, which apply an AND condition for filtering:

  • yeargroup: number, receive the year in which you want to look for rotations (2022, 2023, etc.)
  • fields_id: integer, receive one or more field IDs separated by comma.
  • fields_uuid: string, receive one or more field UUIDs separated by comma.
  • farms_id: integer, receive one or more comma separated farm IDs.
  • farms_uuid: string, receive one or more farm UUIDs separated by comma.

As for the parameters passed by query, the following order of priority must be taken into account:

  • 1st: first priority is given to the fields_id parameter; if it was sent the remaining id or uuid parameters are not considered.
  • 2nd: if fields_id was not sent, check if fields_uuid was sent.
  • 3rd: if fields_uuid was not sent, check if farms_id was sent.
  • 4th: finally, if the previous conditions are not met, check if farms_uuid was sent.

If none of these four parameters are sent, the endpoint will return the information corresponding to all the fields over which the user has read permissions.

This endpoint has no paging implemented, so all existing records within an array (under the key data) are returned in a single response.

Response example:

{
  "data": [
    {
      "farm_uuid": "9238b494-a535-4357-851f-074346ee520a",
      "map_id": null,
      "varieties": [
        {
          "crop_variety_id": 62529,
          "id": 16526,
          "crop_variety_name": "N25"
        }
      ],
      "end_date": "2024-07-01T02:59:59Z",
      "yeargroup": 2024,
      "start_date": "2024-01-01T03:00:00Z",
      "farm_id": 149561,
      "field_id": 497297,
      "crop_id": 1,
      "field_uuid": "778fd10e-e2a8-4884-9c63-19cb69511297",
      "crop_name": "Algodón",
      "cicle_id": 335685,
      "rotation_uuid": "caff5a90-5b73-4a6c-a2e8-b60ac9db4e8c",
      "yield_crop": null,
      "ha": 1.0201288,
      "field_name": "616500771116",
      "crop_order": 1,
      "metadata": {
        "DGC": 0,
        "cover_type": 0,
        "utilization": [],
        "agricultural_activity_details": [],
        "plant_spacing_unit": "m",
        "crown_projection_free_width_unit": "m",
        "cover_width": 0,
        "row_spacing_value": 0,
        "crown_projection_free_width": 0,
        "row_spacing_unit": "m",
        "activity_on_cover": 0,
        "flooding_date": null,
        "production_type": 1,
        "cover_width_unit": "m"
      }
    }
  ]
}
  • farm_uuid: uuid of the farm in which the rotation was saved.
  • map_id: id of the map associated to the rotation. Only one map can be associated per rotation.
  • varieties: can return a null value or can return an array with the following properties:
    • crop_variety_id: id of the crop variety.
    • id: id of the variety.
    • crop_variety_name: name of the crop variety.
  • end_date: end date of rotation.
  • yeargroup: year of the season to which the rotation belongs.
  • start_date: rotation start date.
  • farm_id: id of the farm in which the rotation was saved.
  • field_id: id of the field in which the rotation was saved.
  • crop_id: id of the crop associated to the rotation.
  • field_uuid: uuid of the field in which the rotation was saved.
  • crop_name: name of the crop associated to the rotation.
  • cycle_id: id of the cycle where the rotation was saved. The cycle represents the set of rotation records that were saved within a given campaign.
  • rotation_uuid: uuid of the rotation.
  • yield_crop: estimated yield, always measured in tons per hectare.
  • ha: number of hectares assigned to the rotation.
  • field_name: name of the field where the rotation was saved.
  • crop_order: id of the order in which the rotation is located within the campaign where it was registered. For example, if the rotation is located in the first place in the campaign, the crop_order will be equal to 1 and so on.
  • metadata: it can return a null value or it can return an array with the following properties:
    • DGC: value corresponding to the internal identifier of the geographical delimitation of AER cultivation. Format: 16-digit number. This value must only be added in fields located in Spain.
    • cover_type: id of the type of cover chosen in the rotation, which can be 1 (“Bare soil”), 2 (“Sown plant cover”), 3 (“Spontaneous plant cover”), 4 (“Inert cover of pruning remains”) or 5 (“Inert cover of other materials (nut shells, stones, other plant remains, etc.)”).
    • utilization: list of ids (numerical) representing the utilization.
    • agricultural_activity_details: list of ids (numerical) representing the agricultural activity details.
    • plant_spacing_value: distance between plants.
    • plant_spacing_unit: unit of distance between plants, always in meters.
    • crown_projection_projection_free_width_unit: unit of the free width of the crown projection.
    • cover_width: width of the cover.
    • crown_projection_projection_free_width: free width of the crown projection.
    • row_spacing_unit: unit of distance between rows, always in meters.
    • row_spacing_value: distance between rows.
    • activity_on_cover: id representing the activity on the cover.
    • production_type: id of the type of production chosen in the rotation, which can be 1 ("Dry") or 2 ("Irrigation”),
    • cover_width_unit: unit of the cover width.
    • cover_date: date of cover establishment.

Path params​

On the other hand, besides making a query through parameters in the query string, you can make another type of query but filtering by rotation UUID as follows:

GET /api/rotations/rotation_uuid

When querying in this way, all the query params mentioned above cease to have any effect on the query filtering.

Response example:

{
  "data": {
    "map_id": null,
    "end_date": "2023-12-01T02:59:59Z",
    "surface_unit": null,
    "field_id": 217000,
    "field_uuid": "313204-0458731-4asf-bfee-fas4ceda54321",
    "yield_crop": null,
    "ha": 100,
    "crop_order": 1,
    "varieties": null,
    "yeargroup": 2023,
    "crop_id": 8,
    "crop_name": "Colza",
    "cicle_id": 110876,
    "rotation_uuid": "183005c4-94eb-169d-7a19-rt27a2e180a6",
    "start_date": "2023-11-20T03:00:00Z",
    "metadata": null
  }
}

When returning a single record, the data key no longer returns an array but a single object with the information corresponding to the consulted rotation.

POST​

Content-Type: application/json
POST /rotations

In the request body, include an array of objects representing each rotation to be created. Each object must include:

  • field_id: number (required), the field's ID to associate the rotation with.
  • crop_id: number(required), the crop's ID.
  • yeargroup: number(required), the year in which the rotation is to be defined.
  • ha: number, hectares over which the rotation is to be defined.
  • start_date: datetime(required), the rotation's start date [format YYYY-MM-DDTHH:mm:ssZ].
  • end_date: datetime(required), the rotation's end date [format YYYY-MM-DDTHH:mm:ssZ].

Response:

The API responds with two lists: one for the rotations created and another for those that couldn't be created.

Response example:

{
	"data": {
        "created_ones": [
            {
                "end_date": null,
                "yeargroup": 2022,
                "field_id": 258388,
                "crop_id": 6,
                "crop_name": null,
                "cicle_id": 65805,
                "start_date": null,
                "ha": null,
                "crop_order": 4,
                "rotation_uuid": "b11f12b1-3265-4756-b18b-45de101da547"
            }
        ],

		"unabled_to_be_created": [
			{
				"varieties": null,
				"end_date": "2024-02-01T00:00:00Z",
				"yeargroup": 2023,
				"start_date": "2023-11-01T00:00:00Z",
				"field_id": 321961,
				"reason": {
					"error_code": -11,
					"error_msg": "User is not allowed to perform this action"
				},
				"crop_id": 2,
				"field_uuid": null,
				"crop_name": null,
				"cicle_id": null,
				"rotation_uuid": null,
				"yield_crop": null,
				"ha": null,
				"crop_order": null,
				"metadata": null
			}
		]
	}
}

PATCH​

Content-Type: application/json
PATCH: /rotations/{rotation_uuid}

Certain aspects of a rotation can be modified:

  • ha
  • crop_id
  • start_date
  • end_date

Example request body:

PATCH /rotations/898430ea-fc6f-4a46-a7c6-9890ea702a41
{
    "ha": 140,
    "start_date":"2022-08-09 21:00:00.000",
    "end_date": "2023-01-09 21:00:00.000",
    "crop_id": 6
}

Response example:

Status: 200 OK
{
  "crop_variety_id": 37582,
  "crop_order": 1,
  "end_date": "2023-01-09 21:00:00.000",
  "yeargroup": 2022,
  "crop_variety_name": "Colorado Chino",
  "field_id": 258482,
  "crop_id": 6,
  "crop_name": "Cebada",
  "cicle_id": 65847,
  "rotation_uuid": "898430ea-fc6f-4a46-a7c6-9890ea702a41",
  "ha": 140,
  "start_date": "2022-08-09 21:00:00.000"
}

VARIETIES IN ROTATIONS​

/rotations/variety/{rotation_uuid}

GET​

Returns a list of available varieties for the crop associated with the rotation.

Response example:

{
  "varieties": [
    {
      "variety_id": 37634,
      "variety_name": "Variety 1"
    },
    {
      "variety_id": 40138,
      "variety_name": "Variety 2"
    }
  ]
}

POST​

This method is used to add one or more varieties to a rotation.

In the request body, include a list of the varieties to be added.

Example request body:

{
    "varieties": [37634, 33305]
}
  • varieties: array of variety ids

DELETE​

This method is used to remove a variety from a rotation.

/rotations/variety/{rotation_uuid}?variety_id={variety_id}
  • variety_id: ID of the variety to be removed.