Skip to main content

API Fields

Fields​

APIs​

POST​

To create a field, assigning it to an existing or new farm.

In order to use this API, the Create Fields feature is required.

Content-Type: application/x-www-form-urlencoded
POST /api/agregarlote

On the form include:

  • nombre: String, name of the new field.
  • shape: String, WKT of the polygon. It must be projected in EPSG 4326 (WGS84). For example "POLYGON((-62.31584534415723908 -33.12230490954907935, -62.31855704936425155 -33.12061682816192842, ...))"
  • idcampo: Int, ID of the Farm to which the new field belongs. In case you want to assign it to a new Farm, use the property namefarm
  • nombrecampo: String, Field name whose length must not exceed 50 characters. In case of sending idfarm, this property is ignored. If a Farm with the name farmname exists, the field will be assigned to it. Otherwise, a new Farm shall be created.

If the polygon is not available in WKT format but in KML, KMZ or Shapefile format, it is possible to use this API to perform the conversion

Response example:

{
  "res": "ok", 
  "info": "New field id 16548",
  "id_lote": "16548",
  "id_campo": 12555
}
Specific errors​
codedescription
1General error
2The shape geometry is invalid
3N/A
4The name of the field is repeated in the farm
5N/A
6Length of farm name exceeds 50 characters or does not exceed 1 character
7The user does not have permissions. Verify that the Extension Version has the feature in its [claimset].(/docs/intro/permissions)
8The user does not have the necessary quota in the space.
9Missing parameters
10Invalid polygon
11The field exceeds the ha admitted
12Incorrect user data
13The hectares consumed are greater than the user's availability
14Quota exceeded for desktop, unlimited user
15User with guaranteed quota, exceeds total available

GET​

It allows you to view the fields to which the user has access and information on each one, grouped by farms. In addition, the fields of the users supervised by the user making the request can be viewed, in the case of belonging to a space.

GET /api/getfields
  • user: Object, fields of the user making the query
    • uid: String, Auravant user ID
    • user_name: String, user name
    • farms: Object[], Array of Objects, being each Object a user farm. See farms-object
  • supervised: Object, object whose attributes are the IDs of users supervised by the querying user. The value of each attribute is an object with the following attributes:
    • uid: String, Auravant user ID.
    • user_name: String, user's name
    • farms: Object, user farms object. See farms-object
Farm object​

The farms object has as attributes the IDs of the farms, and the value of each farm is an object with the following attributes:

  • id: Int, farm ID
  • name: String, farm name
  • tags: Array int, array with farms tag IDs
  • tags_names: Array Int, array containing the farm labels names
  • permissions: Array Int, array containing the permissions codes that the user has over the farm permissions codes códigos de los permisos que el usuario tiene sibre el campo
  • role: Int, user role ID of the user on the farm
  • bbox: String, WKT (EPSG 4326) of the polygon of the rectangle containing all fields of the farm (Bounding Box).
  • fields: Object, user farms. See field-object
Field object​

The field object has as attributes the IDs of the fields, and the value of each is an object with the following attributes:

  • id: Int, field ID
  • name: String, field name
  • role: Int, User role ID of the user on the field
  • farm: String, farm name
  • country: String, country code
  • shapes: Object
    • current: Object
      • polygon: String, WKT (EPSG 4326) of the polygon of the field
      • centroid: String, WKT (EPSG 4326) of the centroid point of the field
      • area: Float, field area in hectares
      • start_date: String, date of field creation in format YYYYY-MM-DD
      • end_date: String, its value is "current", indicating that it is the current form of the field
      • bbox: String, WKT (EPSG 4326) of the polygon of the rectangle containing the field (Bounding Box)
Response Example

In this case, the user "Test User", whose ID is UID-72f1b3cedac245c009de03b7a7c9d5a8, has 2 farms (1975 and 1836). The first has one field (5911) and the second has two (7143 and 7145).

In addition, the user belongs to a space in which it supervises another user ("Test Supervised User", with ID UID-dbaefe8503fe6cdb7909611e8953e74f). This one has a farm (3566) with two fields (13254 y 13289).

{
  "user": {
    "user_name": "Usuario Prueba",
    "uid": "UID-72f1b3cedac245c009de03b7a7c9d5a8",
    "farms": {
      "1975": {
        "name": "Campo Prueba",
        "role": 1,
        "bbox": "POLYGON ((-59.9799656867981 -35.8329711461622, -59.9799656867981 -35.8241463744063, -59.9682283401489 -35.8241463744063, -59.9682283401489 -35.8329711461622, -59.9799656867981 -35.8329711461622))",
        "id": 1975,
        "tags": null,
        "fields": {
          "5911": {
            "name": "Lote 1",
            "role": 1,
            "id": 5911,
            "farm": "Campo Prueba",
            "shapes": {
              "current": {
                "polygon": "POLYGON ((-59.9798798561096 -35.8263037281096, -59.9799656867981 -35.8269822385233, -59.9760818481445 -35.8299919711895, -59.9746897816658 -35.8329711461622, -59.9682283401489 -35.8274867681474, -59.9727773666382 -35.8241463744063, -59.9798798561096 -35.8263037281096))",
                "end_date": "current",
                "area": 5.3809314,
                "centroid": "POINT (-59.974097013473504 -35.82855876028425)",
                "bbox": "POLYGON ((-59.9799656867981 -35.8329711461622, -59.9799656867981 -35.8241463744063, -59.9682283401489 -35.8241463744063, -59.9682283401489 -35.8329711461622, -59.9799656867981 -35.8329711461622))",
                "start_date": "2016-01-01"
              }
            }
          }
        }
      },
      "1836": {
        "name": "Campo Prueba 2",
        "role": 5,
        "bbox": "POLYGON ((-63.4189217537641 -36.89400693295, -63.4189217537641 -36.8893543594351, -63.407678604126 -36.8893543594351, -63.407678604126 -36.89400693295, -63.4189217537641 -36.89400693295))",
        "id": 1836,
        "tags": null,
        "fields": {
          "7143": {
            "name": "Lote Prueba 1",
            "role": 5,
            "id": 7143,
            "farm": "Campo Prueba 2",
            "shapes": {
              "current": {
                "polygon": "POLYGON ((-63.4189217537641 -36.8936626452543, -63.4189082092408 -36.8900518014372, -63.4189195744693 -36.8893543594351, -63.4131949022412 -36.889363476622, -63.4131769760736 -36.8921857020239, -63.4149205684662 -36.8921664236779, -63.4158003330231 -36.8923122931648, -63.4162938594818 -36.8925010650283, -63.4167015552521 -36.8928013829398, -63.4169483184814 -36.8931875042328, -63.4170985221863 -36.893702329585, -63.4189217537641 -36.8936626452543))",
                "end_date": "current",
                "area": 1.4015214,
                "centroid": "POINT (-63.41604936491885 -36.89152834451005)",
                "bbox": "POLYGON ((-63.4189217537641 -36.893702329585, -63.4189217537641 -36.8893543594351, -63.4131769760736 -36.8893543594351, -63.4131769760736 -36.893702329585, -63.4189217537641 -36.893702329585))",
                "start_date": "2016-01-01"
              }
            }
          },
          "7145": {
            "name": "Lote Prueba 2",
            "role": 5,
            "id": 7145,
            "farm": "Campo Prueba 2",
            "shapes": {
              "current": {
                "polygon": "POLYGON ((-63.4077215194702 -36.89400693295, -63.4131650626659 -36.8938535588724, -63.4131938964129 -36.8893632084695, -63.4076980501413 -36.8893752753329, -63.407678604126 -36.8910509419143, -63.4082338213921 -36.8912826202372, -63.4086012840271 -36.8916322815596, -63.4086012840271 -36.8920141184749, -63.4083867073059 -36.8924066791549, -63.407678604126 -36.8928357049116, -63.4077215194702 -36.89400693295))",
                "end_date": "current",
                "area": 22.190903,
                "centroid": "POINT (-63.410436250269456 -36.89168507070975)",
                "bbox": "POLYGON ((-63.4131938964129 -36.89400693295, -63.4131938964129 -36.8893632084695, -63.407678604126 -36.8893632084695, -63.407678604126 -36.89400693295, -63.4131938964129 -36.89400693295))",
                "start_date": "2016-01-01"
              }
            }
          }
        }
      }
    }
  },
  "supervised": {
    "UID-dbaefe8503fe6cdb7909611e8953e74f": {
      "user_name": "Usuario Supervisado de Prueba",
      "uid": "UID-dbaefe8503fe6cdb7909611e8953e74f",
      "farms": {
        "3566": {
          "name": "Campo Ensayo 1",
          "role": 1,
          "bbox": "POLYGON ((-62.6232734075912 -32.8926110237142, -62.6232734075912 -32.8709990515346, -62.5776329389938 -32.8709990515346, -62.5776329389938 -32.8926110237142, -62.6232734075912 -32.8926110237142))",
          "id": 3566,
          "tags": [10, 23],
          "fields": {
            "13254": {
              "role": 1,
              "id": 13254,
              "name": "Lote Ensayo 1",
              "farm": "Campo Ensayo 1",
              "shapes": {
                "current": {
                  "polygon": "POLYGON ((-62.5972237936386 -32.8749998863106, -62.6188531271347 -32.8709990515346, -62.6232734075912 -32.8886830582691, -62.601429497374 -32.8926110237142, -62.5972237936386 -32.8749998863106))",
                  "end_date": "current",
                  "area": 415.523,
                  "centroid": "POINT (-62.61024860061489 -32.8818050376244)",
                  "bbox": "POLYGON ((-62.6232734075912 -32.8926110237142, -62.6232734075912 -32.8709990515346, -62.5972237936386 -32.8709990515346, -62.5972237936386 -32.8926110237142, -62.6232734075912 -32.8926110237142))",
                  "start_date": "2016-01-01"
                }
              }
            },
            "13398": {
              "role": 1,
              "id": 13398,
              "name": "Lote Ensayo 2",
              "farm": "Campo Ensayo 1",
              "shapes": {
                "current": {
                  "polygon": "POLYGON ((-62.5992622724899 -32.8837157945315, -62.5798216215499 -32.8871394523206, -62.5776329389938 -32.8784178739015, -62.5971594206222 -32.8749217936657, -62.5992622724899 -32.8837157945315))",
                  "end_date": "current",
                  "area": 184.64764,
                  "centroid": "POINT (-62.58844760574184 -32.88103062299315)",
                  "bbox": "POLYGON ((-62.5992622724899 -32.8871394523206, -62.5992622724899 -32.8749217936657, -62.5776329389938 -32.8749217936657, -62.5776329389938 -32.8871394523206, -62.5992622724899 -32.8871394523206))",
                  "start_date": "2016-01-01"
                }
              }
            }
          }
        }
      }
    }
  }
}

DELETE​

It allows to delete a field, using its ID as a URL parameter.

GET /api/borrarlotes?lote=XXXXXX

NDVI​

APIs​

GET​

It allows to obtain the average NDVI of a field, for a range of dates. The index is calculated from Sentinel 2 imagery. Only images that have been classified as cloud-free are included.

GET /api/fields/ndvi
  • Parameters in the URL:
    • field_id: Required. This is the ID of the field for which you want to query.
    • date_from: Optional. Date from which to query. Format YYYYY-MM-DD
    • date_to: Optional. Date up to which to query. Format YYYYY-MM-DD

Response Example:

{
    "ndvi": [
        {"date": "2020-06-13", "ndvi_mean": 0.246348}, 
        {"date": "2020-06-10", "ndvi_mean": 0.215531}, 
        {"date": "2020-06-08", "ndvi_mean": 0.235166}, 
        {"date": "2020-06-03", "ndvi_mean": 0.228176},
    ], 
    "code": 0,
    "field_id": 1500
}

Season shapes​

The georeferenced polygon of a plot can be modified for a season. Once modified, subsequent campaigns will have the same shape.

Season polygon demo

APIS​

New season shape​

This endpoint allows creating a polygon for a campaign or modifying the one that already exists for a campaign.

The user must have permission 220 (modify plot shape) for the plot. The options to create plot (C) and modify (U) campaign must also be enabled.

The endpoint validates that the new polygon is within a permitted boundary and that no images are being processed.

POST /api/fields/v2/shapes
Headers:
  Content-Type: application/json
Body:
  {
    'type': 'object',
    'properties': {
        'field_id': {"type": "integer", "min": 1},
        'campaign': {"type": "integer", "min": 1},
        'shape': {'type': 'string', 'description': 'WKT en EPSG 4326'},
    },
    'required': ['field_id', 'campaign', 'shape'],
  }
Respuesta:​
{
  "info": "shape was created", 
  "data":  {
        "images_reprocessing": true
    }
}

The images_reprocessing parameter indicates whether the images had to be reprocessed. If true, the polygon cannot be modified until reprocessing is complete.

Check if images are still being processed​

This endpoint allows checking if the images of a plot are still being processed. If the images are still being processed, it will return the REPROCESSING error.

GET /api/fields/v2/shape/lock?field_id=`field_id`
Respuesta:​
{
    "info": "allowed",
    "data": {
        "images_reprocessing": false
    }
}

Obtain expansion limits​

When a polygon is modified, it must be within this boundary.

GET /api/fields/v2/shape/limits?field_id=`field_id`
Respuesta:​
{
  "info": "shape expansion limits retrieved", 
  "data": {
    "limits_4326": "MULTIPOLYGON(.....)",
    "limits_3857": "MULTIPOLYGON(.....)"
    }
}

The limits are returned in EPSG:4326 and EPSG:3857, use the appropriate one for your case. For more information on these projections, refer to this article.

Specific errors​

  • ReprocessLockError: En caso que las imágenes aún se estén procesando

    • code = 'REPROCESSING'
    • msg = 'The previous shape is still being processed'

  • InvalidGeometryError:

    • code = 'INVALID_GEOMETRY'
    • msg = 'The provided geometry is invalid'

  • NotEnoughQuotaError:

    • code = 'NOT_ENOUGH_QUOTA'
    • msg = 'User has exceeded the assigned quota'

  • NotEnoughWorkspaceQuotaError:

    • code = 'NOT_ENOUGH_QUOTA_WORKSPACE'
    • msg = 'Workspace has exceeded the assigned quota'

  • MaxShapeAreaExceededError:

    • code = 'MAX_SHAPE_AREA_EXCEEDED'
    • msg = 'The requested Shape exceeds area limits'

  • ShapeExpansionLimitError:

    • code = 'SHAPE_EXPANSION_LIMIT'
    • msg = 'The provided shape exceeds the defined expansion limits'