Skip to main content

Spots

The spots (or managements zones), allow the user specify zones within a field and associate information about that specific section of it. It's based on an REST API, and to identify each resource it uses UUIDs instead of common IDs so that the spots can be created offline.

APIs​

SPOTS​

POST​

Creates a new spot. It requires the Management zones functionality enabled to be used.

Content-Type: application/json
POST /spots/spot

The body includes:

  • uuid: string, UUID v1 that identifies the spot (if not sent, it will be autogenerated)
  • field_id: integer, field ID where the spot is created (required)
  • name: string, spot name (optional)
  • shape: string, WKT Point or Polygon which defines the shape of the spot (required)
  • tags: array, Array of Objects with tags UUIDs/names (optional)
    • items: object with the following properties
      • uuid, string, tag identifier UUID (if not specified a new tag is created with an autogenerated UUID)
      • tag, string, tag name
  • group_uuid: string, spots group identifier UUID (optional)
  • texts: array, Array of Objects that define messages for a spot (optional)
    • items: object,
      • uuid: string, message identifier UUID
      • text: string, text that appears in the text field
      • timestamp_usr: string/date-time, Timestamp defined by the user when the message was created. Must be at local time and follow the format YYYY-MM-DDTHH:MM:SSZ
      • imgs: array,Array of objects with coordinates and UUIDs of the images (each image must be upload using the especific API IMAGES, by PUT method) (optional)
        • items: object,
          • coordinate: string, WKT format POINT which indicates the coordinates of the image
          • uuid: string, image identifier UUID needed to be used by the API IMAGES
  • sample_set: object, (optional)
    • sample_set_uuid: string, sample identifier UUID
    • sample_set_type: string, sample type to be associated with the spot
  • data: object, (optional)
    • variables: array
      • items: object, Only takes the following properties
        • name: string, name of the variable
        • unit_id: integer, minimum: 0, (see unit_id list: VARIABLES)
        • value: number, value of the variable

Javascript use example

fetch("https://api.auravant.com/api/spots/spot", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    field_id: 123456,
    shape: "POINT(-66 -33)",
  }),
})
  .then((res) => res.json())
  .then((res) => console.log(res));

Response:

{
  "code": "12AZ-1AZ-12AZ",
  "spot_uuid": "1234abyz-12az-12az-12az-123456abcxyz"
}

GET​

List of the user spots.

GET /spots/spot

The 9 parameters are optional, applying AND condition to every user spot. If not parameters are sent, all spots are returned.

  • uuid: spot UUID, or many separated by comma
  • group_uuid
  • farm_id
  • field_id
  • sample_set_type
  • sample_set_uuid
  • date_from YYYY-MM-DDTHH:MM:SSZ format
  • date_to YYYY-MM-DDTHH:MM:SSZ format
  • tag_uuid tag UUID, spots with that tag associated will be returned

If not "sample_set" condition is applied, only spots that aren't related to samples are returned (eg. yield estimation).

  • The spots are listed by creation date, in descendent order
  • page_size and page allow to apply *LIMIT page_size OFFSET page* to all spots. The response includes a bool parameter continues which indicates if there's more than one page to get.
  • page_size: default 50 - set to -1 to get all
  • page: default 0

Javascript use example:

fetch("https://api.auravant.com/api/spots/spot", {
  method: "GET",
  headers: {
    Authorization: "Bearer " + token,
  },
})
  .then((res) => res.json())
  .then((res) => console.log(res));

Response:

{
  "continues": false,
  "data": [
    {
      "code": "12AZ-1AZ-12AZ",
      "uuid": "1234abyz-12az-12az-12az-123456abcxyz",
      "area": 0,
      "farm_id": 12345,
      "field_id": 123456,
      "sample_set_type": null,
      "spot_data": null,
      "group_uuid": null,
      "sample_set_type_id": null,
      "group_shape": null,
      "sample_set_id": null,
      "total_imgs": 0,
      "spot_shape": "POINT(-60.3002626493765 -33.3878546388025)",
      "creation_ts": "2021-10-26T19:28:05Z",
      "spot_name": null,
      "sample_set_uuid": null,
      "total_msgs": 0,
      "tags": null
    },
    {
      "code": "12AZ-1AZ-12AZ",
      "uuid": "1234abyz-12az-12az-12az-123456abcxyz",
      "area": 0.454111,
      "farm_id": 12345,
      "field_id": 123456,
      "sample_set_type": null,
      "spot_data": {
        "variables": []
      },
      "group_uuid": null,
      "sample_set_type_id": null,
      "group_shape": null,
      "sample_set_id": null,
      "total_imgs": 0,
      "spot_shape": "POLYGON((-60.2964477531204 -33.3866388782719,-60.2969512933341 -33.3862662114604,-60.2975234983605 -33.3867631002786,-60.2969055163558 -33.387078432604,-60.2964477531204 -33.3866388782719))",
      "creation_ts": "2021-10-19T12:58:23Z",
      "spot_name": null,
      "sample_set_uuid": null,
      "total_msgs": 0,
      "tags": [
        {
          "tag": "Malezas",
          "uuid": "42848a6b-e19e-11ea-932a-4b6dfef550c7",
          "translatable": true
        }
      ]
    }
  ],
  "page": 50,
  "page_size": 50
}

PATCH​

Will update only the sent parameters, overwriting the current data

Content-Type: application/json
PATCH /spots/spot

Ir requires the spot UUID to identify.

Can be updated the same parameters as POST

Javascript use example:

fetch("https://api.auravant.com/api/spots/spot", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer " + token,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    tags: [
      {
        tag: "TagExample",
      },
      {
        tag: "Malezas",
        uuid: "42848a6b-e19e-11ea-932a-4b6dfef550c7",
      },
    ],
  }),
})
  .then((res) => res.json())
  .then((res) => console.log(res));

Respuesta:

{
  "spot_uuid:": "1234abyz-12az-12az-12az-123456abcxyz"
}

Description: Overwrite all existing "tags" with a new tag custom called "OtherPatch".

DELETE​

The UUID of the spot to be deleted is sent into the query string.

Javascript use example:

fetch(
  "https://api.auravant.com/api/spots/spot?uuid=1234abyz-12az-12az-12az-123456abcxyz",
  {
    method: "DELETE",
    headers: {
      Authorization: "Bearer " + token,
    },
  }
)
  .then((res) => res.json())
  .then((res) => console.log(res));

Response:

{
  "spot_uuid": {
    "f_ini": "2021-10-26T19:28:05Z",
    "id_tipo_zona_gestion": null,
    "code": "12AZ-1AZ-12AZ",
    "uuid": "1234abyz-12az-12az-12az-123456abcxyz",
    "fecha_alta": "2021-10-26T19:28:05Z",
    "area": 0,
    "id_muestra": null,
    "fecha_fin": "2021-10-26T19:44:46Z",
    "group_uuid": null,
    "shape": "0101000020E610000025A4A9016F264EC01BA18638A5B140C0",
    "datos": null,
    "id_lote": 123456,
    "nombre": null,
    "id": 123456
  }
}

GET SPOTS​

POST​

Content-Type: application/json
POST /api/spots/getspot

Spot list from the mobile APP.

The 9 parameters are optional, applying AND condition to every user spot. If not parameters are sent, all spots are returned.

  • uuid: spot UUID, or many separated by comma
  • group_uuid: string
  • farm_id: integer
  • field_id: integer
  • sample_set_type: string
  • sample_set_uuid: string
  • date_from: string YYYY-MM-DDTHH:MM:SSZ format
  • date_to: string YYYY-MM-DDTHH:MM:SSZ format
  • tag_uuid: string tag UUID, spots with that tag associated will be returned

If not "sample_set" condition is applied, only spots that aren't related to samples are returned (eg. yield estimation).

  • The spots are listed by creation date, in descendent order
  • page_size and page allow to apply *LIMIT page_size OFFSET page* to all spots. The response includes a bool parameter continues which indicates if there's more than one page to get.
  • page_size: default 50 - set to -1 to get all
  • page: default 0
Content-Type: application/json
POST /api/spots/all

This endpoint is exactly the same to the on abover, but inside the payload of each spot are included the messages and the images of each one. The pagination applies only to spots.

MESSAGES​

Especific API to manage messages of a spot.

POST​

Creates a new message

Content-Type: application/json
POST /api/spots/msgs

The body includes:

  • uuid: string, message UUID as identifier (required)
  • texts: array, Array of objects that determine the texts to be seen on the spot text field (required)
    • items: object,
      • uuid: string, text UUID as identifier
      • text: string, text that will appear in the text field
      • timestamp_usr: string/date-time, Timestamp. Local time and YYYY-MM-DDTHH:MM:SSZ format
      • imgs: array,Array of objects with coordinates and UUIDs of the images (each image must be upload using the especific API IMAGES, by PUT method) (optional)
        • items: object,
          • coordinate: string, WKT format POINT which indicates the coordinates of the image
          • uuid: string, image identifier UUID needed to be used by the API IMAGES

GET​

Returns the messages of a spot

GET /api/spots/msgs

Requires the spot UUID into the query string.

page_size and page allows pagination. The response includes a bool parameter continues which indicates if there's more than one page to get.

The messages are listed by creation date, in descendent order

  • uuid: spot UUID
  • page_size: default 20 - seteandolo en -1, se traen todos
  • page: default 0

DELETE​

DELETE /api/spots/msgs

Deletes a message

Requires the spot UUID into the query string of the spot to be deleted

Also deletes the associated images

IMAGES​

This endpoint is used to manage images

PUT​

PUT /api/spots/msgs/imgs

Uploads an image which has been previous declared

The query string requires the UUID of the image

NOTE: The file must be attached as value of the property img

Errors​

  • If an error ocurrs at image uploading: {'code': 51, 'info': 'image could not be stored'}

GET​

GET /api/spots/msgs/imgs

Downloads an image which has been previously uploaded

The query string requires the UUID of the image to be download

Errors​

  • If the image could not be found: {'code': 404, 'info': 'File not found'}

TAGS​

This endpoint allows TAGs management.

POST​

Content-Type: application/json
POST /api/spots/msgs/imgs

Each TAG is defined by an object with 2 keys: tag and uuid. There are 2 ways to create a TAG:

  • By sending and object with the tag key only. This will create the tag and the UUID will be autogenerated.
  • By sending the tag and uuid keys. The UUID sent will be used as the identifier (the UUID must be UUID v1)

If the UUID sent already exists, the TAG will be ignored, no matters if the TAG had been deleted or not.

The body includes:

  • uuid: string, UUID v1 as TAG identifier
  • tag: string, Name of the TAG (required)

GET​

GET /api/spots/msgs/imgs

Search for the common TAGs and the ones created by the user.

The following paramters could be sent into the query string to filter. Any value different from false will be defaulted to true

  • general=false: Do not search for common TAGs
  • user=false: Do not search for user TAGs

PATCH​

Content-Type: application/json
PATCH /api/spots/msgs/imgs

Only user TAGs could be updated

The body includes:

  • uuid: string, UUID v1 as TAG identifier. (required)
  • tag: string, TAG name (required)

DELETE​

DELETE /api/spots/msgs/imgs

Deletes a TAG.

The TAG UUID to be deleted is required into the query string

Only a user TAG can be deleted.

Errores​

  • If there's at least one spot using the TAG it cannot be deleted: {'code': 51, 'info':'It is not possible to delete a Tag that is in use'}

VARIABLES​

This endpoint is used to add or modify a variable associated to a spot

PATCH​

Content-Type: application/json
PATCH /api/spots/variables

The units are defined by an object with the keys name, unit_id and value The unit_id can be consulted at:

GET api/utils/units

The sent array overwrites the current array

The body includes:

  • uuid: string , UUID v1 as spot identifier (required)
  • variables: array, Array of objects that contains the variables (required)
    • items: object, Only following properties can be sent:
      • name: string,
      • unit_id: integer, mínimo 0
      • value: number

SHEETS​

This endpoint allows you to download the spots of the user, or uploads a xls, xlsx or csv file with information about spots.

GET​

GET /api/spots/sheet

Downloads the user spots as a sheet.

Optionally, the following filters can be used, applying an AND condition over the spots to be included into the sheet.

  • farm_id
  • field_id
  • date_from: Initial date, YYYY-MM-DDTHH:MM:SSZ format
  • date_to: End date, YYYY-MM-DDTHH:MM:SSZ format
  • tag_uuid: TAG UUID, only one can be specified

date_from and date_to take in account the created date of the spot.

POST​

Files with xls, xlsx o csv format must be included into the form under the key sheet.

Inside the sheet must be a column with the name Auravant_Spot_ID, whose values must be the UUIDs of the spots

Errors​

  • If the file format is not one of the supported: {'code': 51, 'info': 'file format not supported. It must be one of .csv, .xls, .xlsx'}
  • If the file cannot be opened. Could be a corrupt file or an incopatibility problem: {'code': 52, 'info': 'error loading sheet'}
  • If the column "Auravant_Spot_ID" does not exist. This column have the spot UUIDs. {'code': 53, 'info': 'missing column: Auravant_Spot_ID'}
  • If some UUID of the column "Auravant_Spot_ID" is invalid or not reffered to any active spot: {'code': 54, 'info': 'No valid record was found'}
  • If not valid variables are found: {'code': 55, 'info': 'No valid variables were found'}
  • If the API returns code: 12, it means that the user have no permission over at least 1 spot defined at the sheet.

Response​

A success response returns a json with the following properties:

  • variables : An object with the variables found at the sheet. Each key of that object is a variable, with the same name as the variable defined in the file. Its value will be null if could not be upload or an object if the variable is ok. That object have the keys name and unit_id that were found.
  • loaded_spots: how many spots were found (sheet rows)
  • ignored_spots: how many spots were ignored (sheet rows)

Response example:

{
  "loaded_spots": 5,
  "ignored_spots": 0,
  "variables": {
    "K (Kg/tornillos)": null,
    "K (Kg/ha)": {
      "name": "K",
      "unit_id": 49
    }
  }
}