Saltar al contenido principal

Marcadores (Spots)

Los marcadores (también llamados zonas de gestión), permiten al usuario especificar zonas dentro de un lote y asociar información característica a ese sector marcado. El mismo se basa en una modalidad API REST y para identificar cada recurso se utilizan uuids en vez de ids para poder crearlos desde la app en modo offline.

APIs​

MARCADORES​

POST​

Creación de un nuevo marcador. Se requiere la funcionalidad Crear Zonas de Gestión para habilitar su uso.

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

En el body se incluye:

  • uuid: string, UUID v1 que sirve de identificador del marcador (si no se envía, se genera automáticamente)
  • field_id: integer, ID de lote donde se crea el marcador (requerido)
  • name: string, Nombre (título) del marcador (opcional)
  • shape: string, WKT del Punto o Polígono que define la figura del marcador (required)
  • tags: array, Array de objectos con uuids/nombres de los tags con los cuales será asociado el marcador. (opcional)
    • items: object
      • uuid, string, UUID v1 que sirve de identificador para el tag (si no se especifica UUID, se crea un nuevo tag y se le asocia un UUID)
      • tag, string, Nombre del tag
  • group_uuid: string, UUID v1 que sirve de identificador para un grupo de marcadores (opcional)
  • texts: array, Array de objetos que definen textos en el espacio de escritura de marcadores (opcional)
    • items: object,
      • uuid: string, UUID v1 que sirve de identificador del mensaje
      • text: string, Texto que aparecerá en el campo de texto
      • timestamp_usr: string/date-time, Timestamp, definido por el usuario, del texto. Debe estar en tiempo local y en formato YYYY-MM-DDTHH:MM:SSZ
      • imgs: array, Array de objetos que contienen los identificadores y coordenadas de las imágenes (cada imágen debe ser subida mediante la API IMAGES, utilizando el método PUT)
        • items: object,
          • coordinate: string, Punto en formato WKT que indica la coordenada de la imágen
          • uuid: string, UUID v1 que sirve de identificador de la imágen para luego ser usado en la API IMAGES
  • sample_set: object, (opcional)
    • sample_set_uuid: string, UUID v1 que sirve de identificador de la muestra asociada al marcador
    • sample_set_type: string, Tipo de muestra que será asociada al marcador
  • data: object, (opcional)
    • variables: array
      • items: object, Solo acepta las siguientes propiedades
        • name: string,
        • unit_id: integer, minimo: 0, (ver lista de unit_id en VARIABLES)
        • value: number

Ejemplo en JavaScript

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));

Respuesta:

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

GET​

Listado de todos los marcadores del usuario según los parámetros enviados.

GET /spots/spot

Los 9 parámetros son opcionales, aplicándose como condición AND a todos los marcadores del usuario. Si no se envía ningún parámetro, se buscan todos.

  • uuid: un uuid de marcador, o varios separados por coma
  • group_uuid
  • farm_id
  • field_id
  • sample_set_type
  • sample_set_uuid
  • date_from en formato YYYY-MM-DDTHH:MM:SSZ
  • date_to en formato YYYY-MM-DDTHH:MM:SSZ
  • tag_uuid uuid de un tag. Se buscarán los marcadores que tengan esta tag asociado

Si no se incluye ninguna condición de "sample_set", sólo se buscan los marcadores que no corresponden a muestras (Ej. monitoreos o rinde)

Se ordenan por fecha de creación, listando primero los más recientes.

Además, page_size y page permite aplicar un *LIMIT page_size OFFSET page* a todos los marcadores. La respuesta incluye un parámetro bool continues que indica si hay más páginas para buscar.

  • page_size: default 50 - seteandolo en -1, se traen todas
  • page: default 0

Ejemplo en JavaScript

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

Respuesta:

{
  "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​

Se actualizarán sólo los parámetros que se envíen, reemplazando los actuales.

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

Se requiere el envío del UUID del marcador para identificarlo.

Se pueden actualizar los mismos parámetros que en el POST de marcadores.

Ejemplo de uso en JavaScript

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"
}

Descripción: Borra todos los "tags" existentes y los reemplaza por uno nuevo llamado "OtherPatch". Como no se le envía un "uuid" al tag se generará uno nuevo.

DELETE​

En la query string se incluye el parámetro uuid correspondiente al marcador a eliminar.

Ejemplo de uso en JavaScript

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));

Respuesta:

{
  "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

Lista de spots desde la App.

Los 9 parámetros son opcionales, aplicándose como condición AND a todos los marcadores del usuario. Si no se envía ningún parámetro, se buscan todos.

  • uuid: array un uuid de marcador, o varios separados por coma
  • group_uuid: string
  • farm_id: integer
  • field_id: integer
  • sample_set_type: string
  • sample_set_uuid: string
  • date_from: string en formato YYYY-MM-DDTHH:MM:SSZ
  • date_to: string en formato YYYY-MM-DDTHH:MM:SSZ
  • tag_uuid: string uuid de un tag. Se buscarán los marcadores que tengan esta tag asociado

Si no se incluye ninguna condición de "sample_set", sólo se buscan los marcadores que no corresponden a muestras (Ej. monitoreos o rinde)

Se ordenan por fecha de creación, listando primero los más recientes.

Además, page_size y page permite aplicar un *LIMIT page_size OFFSET page* a todos los marcadores. La respuesta incluye un parámetro bool continues que indica si hay más páginas para buscar.

  • page_size: default 50 - seteandolo en -1, se traen todas
  • page: default 0
Content-Type: application/json
POST /api/spots/all

Este endpoint es exactamente igual al anterior, con la diferencia que en la respuesta, dentro de cada marcador, se incluyen los mensajes e imágenes de cada uno. La paginación aplica sólo a los marcadores.

MESSAGES​

API específica para manejar los textos, comentarios o mensajes que se asocian a un marcador.

POST​

Crea un nuevo mensaje para un determinado marcador.

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

El body incluye:

  • uuid: string, UUID v1 que sirve de identificador del marcador al cual pertenece el mensaje (required)
  • texts: array, Array de objetos que definen textos en el espacio de escritura de marcadores (required)
    • items: object,
      • uuid: string, UUID v1 que sirve de identificador del mensaje
      • text: string, Texto que aparecerá en el campo de texto
      • timestamp_usr: string/date-time, Timestamp, definido por el usuario, del texto. Debe estar en tiempo local y en formato YYYY-MM-DDTHH:MM:SSZ
      • imgs: array, Array de objetos que contienen los identificadores y coordenadas de las imágenes (cada imágen debe ser subida mediante la API IMAGES, utilizando el método PUT)
        • items: object,
          • coordinate: string, Punto en formato WKT que indica la coordenada de la imágen
          • uuid: string, UUID v1 que sirve de identificador de la imágen para luego ser usado en la API IMAGES

GET​

GET /api/spots/msgs

Se envía el UUID del zona marcador del cual se quieren obtener los mensajes.

page_size y page permiten paginar los mensajes. La respuesta incluye un parámetro bool continues que indica si hay más páginas para buscar.

Se ordenan por fecha de creación, listando primero las más recientes.

  • uuid: uuid del marcador correspondiente
  • page_size: default 20 - seteandolo en -1, se traen todos
  • page: default 0

DELETE​

DELETE /api/spots/msgs

Borra un mensaje

En la query string se incluye el parámetro uuid correspondiente al mensaje a eliminar.

También se eliminan las imagenes asociadas, en caso de haberlas.

IMAGES​

Esta API es específica para el manejo de las imágenes.

PUT​

PUT /api/spots/msgs/imgs

Subida de una imagen que haya sido previamente declarada.

Se debe incluir uuid en la query string con el UUID de la imagen a subir.

NOTA: El archivo debe ir adjunto en la request bajo el nombre img.

Errores​

  • Si hubo un error al guardar la imagen. {'code': 51, 'info': 'image could not be stored'}

GET​

GET /api/spots/msgs/imgs

Descargar una imagen que haya sido previamente subida.

Se debe incluir uuid en la query string con el UUID de la imagen a descargar. Alternativamente, se puede incluir el UUID en el path. Ej: /api/spots/msgs/imgs/<uuid>

Errores​

  • Si la imagen no se encuentra. {'code': 404, 'info': 'File not found'}

TAGS​

Esta API se utiliza para manejar el campo de TAGs

POST​

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

Cada tag se representa con un objeto que puede tener 2 keys: tag y uuid. Se pueden crear TAGs de 2 maneras:

  • Enviando objetos con sólo la key tag: Se creará la tag, generando su correspondiente uuid

  • Enviando objetos con la key tag y uuid: Se creará la tag utilizando tag como nombre y el uuid enviado

Si el UUID ya existe, se ignora la tag enviada, independientemente si la tag fue previamente borrada o no.

En el body se incluye:

  • uuid: string, UUID v1 que sirve de identificador del TAG.
  • tag: string, Nombre del TAG (required)

GET​

GET /api/spots/msgs/imgs

Busca tanto los TAGs generales como los creados por el usuario que hace el pedido.

Se pueden incluir parámetros en la query string para evitar algún tipo. Cualquier valor distinto de false, se defaultea a true

  • general = false: no se buscan las generales
  • user = false: no se buscan las creadas por el usuario

PATCH​

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

Solo se pueden editar los TAGs creados por el usuario que hace el pedido.

En el body se incluye:

  • uuid: string, UUID v1 que sirve de identificador del TAG. (required)
  • tag: string, Nombre del TAG (required)

DELETE​

DELETE /api/spots/msgs/imgs

Borra un TAG

Se incluye el parámetro uuid en la query string correspondiente al TAG a eliminar.

Solo se puede eliminar un TAG creado por el usuario que hace el pedido.

Errores​

  • Si el TAG esta siendo utilizado por algún marcador, no podrá eliminarse. {'code': 51, 'info':'It is not possible to delete a Tag that is in use'}

VARIABLES​

Esta API sirve para modificar o agregar variables a un marcador.

PATCH​

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

Las unidades se definen por un objeto con las keys name, unit_id y value, donde unit_id es el id de la unidad, los cuales se pueden consultar en:

GET api/utils/units

El array enviado reemplaza el que esté guardado.

En el body se incluye:

  • uuid: string , UUID v1 que sirve de identificador del marcador (required)
  • variables: array, Array de objetos que contiene las variables (required)
    • items: object, solo permite las siguientes propiedades
      • name: string,
      • unit_id: integer, mínimo 0
      • value: number

SHEETS​

Esta API permite descargar los marcadores de un usuario, o cargar un archivo xls, xlsx o csv con información sobre marcadores.

GET​

GET /api/spots/sheet

Descarga los marcadores de un usuario como una planilla de excel.

Opcionalmente, se pueden incluir filtros para aplicar como AND sobre las zonas de gestión a incluir en el excel.

  • farm_id
  • field_id
  • date_from: fecha desde la cual se quieren obtener los marcadores. Formato: YYYY-MM-DDTHH:MM:SSZ
  • date_to: fecha hasta la cual se quieren obtener los marcadores . Formato: YYYY-MM-DDTHH:MM:SSZ
  • tag_uuid: UUID de un tag. Solo se puede incluir uno.

date_from y date_to tiene en cuenta la fecha de creación de cada marcador.

POST​

Se debe incluir el archivo en formato xls, xlsx o csv en el formulario bajo la key sheet.

Dentro de la planilla se debe incluir la columna Auravant_Spot_ID, que contiene los UUID de los marcadores

Errores​

  • Si el tipo de archivo enviado no es de uno de los formatos indicados: {'code': 51, 'info': 'file format not supported. It must be one of .csv, .xls, .xlsx'}
  • Si no se puede abrir el archivo. Puede deberse a algún problema de incompatibilidad o archivo corrupto: {'code': 52, 'info': 'error loading sheet'}
  • Si el archivo no tiene la columna "Auravant_Spot_ID". Esta columna tiene los UUIDs de los marcadores. {'code': 53, 'info': 'missing column: Auravant_Spot_ID'}
  • Si ninguno de los UUIDs de la columna "Auravant_Spot_ID" es válido o si no se corresponden a marcadores vigentes: {'code': 54, 'info': 'No valid record was found'}
  • Si no se encuentran variables válidas para cargar: {'code': 55, 'info': 'No valid variables were found'}
  • Si la API responde con el error code: 12, significa que el usuario no tiene permisos sobre al menos 1 de los marcadores definidos en la planilla.

Respuesta​

El json de una respuesta exitosa tiene los siguientes campos:

  • variables : un objecto con las variables que se encontraron en la planilla. Cada key de ese objeto es la variable, tal como figura en el excel, y su valor es null si no se pudo cargar (es decir que por algún motivo es inválida) o un objeto si es una variable válida. Ese objeto tiene las keys name con el nombre de la variable y unit_id con el id de la unidad que se identificó
  • loaded_spots: cantidad de spots (filas de la planilla) que se encontraron
  • ignored_spots: cantidad de spots (filas de la planilla) que se ignoraron

Ejemplo de respuesta:

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