Entities

Contents

Entities#

The operation of MRV API is managed by 3 core entities: Field, Request and Result.

Using this simple data schema, a user can register actual crop fields into the system and trigger a variety of available analyses for it.

Field#

A Field represents an actual individual crop field and its related data. The system will use this entity to refer to the given crop field, fulfilling its data or grabbing data from it when needed.

The data a single Field entity holds is:

  • id: unique identifier of the field in Agreena’s system, as an RFC-4122 UUID v4 number. It is assigned automatically and cannot be modified at all by the user.

  • client_field_id: identifier of the field in the user’s system. This is a string the user can choose freely.

  • client_id: unique identifier of the client in Agreena’s system, as an RFC-4122 UUID v4 number.

  • created_at: timestamp of the creation date of the field, in ISO-8601.

  • updated_at: timestamp of the last time when the field entity was updated, in ISO-8601.

  • area: area of the field in hectares. Can be submitted by the user on field creation, otherwise it will be automatically calculated by the system from the given user polygon.

  • boundary: geometry representing the geographic polygon of the field, in GeoJSON.

  • point: a geographical point, in GeoJSON, contained inside the field polygon. This can be given by the user to the API in a specific endpoint so the boundary will be calculated by the system automatically.

  • land_use: the type of land where the field polygon has been located. It might be one of these strings:

    • Water

    • Trees

    • Flooded vegetation

    • Crops

    • Built Area

    • Bare ground

    • Snow/Ice

    • Clouds

    • Rangeland

    • NoData

  • country_code: country code, in ISO Alpha-3.

  • climate_zone: the world climate zone where the field has been located. It can be one of these strings:

    • tropical_wet

    • tropical_dry

    • tropical_moist

    • boreal_moist

    • boreal_dry

    • polar_moist

    • polar_dry

    • warm_temperate_dry

    • cool_temperate_dry

    • cool_temperate_moist

    • tropical_montane

    • warm_temperate_moist

Warning

The client_field_id will not be considered unique by MRV API, meaning the user can have multiple fields registered with the same client_field_id and the difference between them will be their id’s (unique) and their created_at timestamps. This should make relatively easy to build a versioning system on the user side, in case is needed.

Request#

Represents a user petition to MRV API to perform a product analysis over a field or set of fields. The Request tracks the operation global status and relates the fields with their analysis results.

The data a Request holds is:

  • id: unique identifier of the request, as an RFC-4122 UUID v4 number. It is assigned automatically and cannot be modified at all by the user.

  • start_date: starting date of the timerange requested for the analysis, in ISO-8601 date format.

  • end_date: ending date of the timerange requested for the analysis, in ISO-8601 date format.

  • status: current global status of the request. It can be one of these statuses:

    • Pending: initial status. The request is queued or being currently processed.

    • Completed: finished status. The request has successfully been completed.

    • Failed: finished status. The request has failed. This may happen for a variety of reasons, which may or may not be the fault of the user.

  • client_id: unique identifier of the client in Agreena’s system, as an RFC-4122 UUID v4 number.

  • created_at: timestamp of the creation date of the request, in ISO-8601.

  • updated_at: timestamp of the last time when the request entity was updated, in ISO-8601.

Result#

Represents the result of a product analysis over a single field.

For example, if a user triggers a tillage verification analysis over 30 fields of a farm, that request will have 30 results, one for each field. In another case, if in the same request the user triggered both tillage and crop-type analyses for the 30 fields, that request will have 60 results, 30 for the tillage analysis and 30 for the crop-type.

The data a single Result can hold is:

  • id: unique identifier of the result, as an RFC-4122 UUID v4 number. It is assigned automatically and cannot be modified at all by the user.

  • capability: the actual MRV product analysis performed on this field for the current request. It can be one of these strings:

    • cover-crops

    • boundary-detection

    • tillage

    • crop-type

    • ndvi

  • request_id: unique identifier of the related request, as an RFC-4122 UUID v4 number. Assigned automatically and not editable by the user.

  • field_id: unique identifier of the field for which the given capability analysis is being performed. RFC-4122 UUID v4 number. Assigned automatically and not editable by the user.

  • status: current status of the analysis for the given field and MRV product. It can be one of these statuses:

    • Pending: starting status, the analysis for the field is queued or being currently processed.

    • Completed: ending status, the analysis for the field has successfully been completed.

    • Failed: ending status, the analysis for the field has failed - for a variety of reasons, might be the fault of the user or not.

  • updated_at: timestamp of the last time when the request entity was updated, in ISO-8601.

  • result: information about the analysis results, in JSON format. Full details of the different result types are described in MRV Products section.

Contents