API

Layers has a REST API from which it is possible to access the data stored in the system as well as updating customer, and fields information.

  • Check the available resources in PROD environment here.

  • Check the available resources in DEV environment here.

1. API end points

Users

Method

Call

Description

POST

/publicapi/customer

Create customer request. Response will return the basic parameters of customer(farmer) to set other entites like fields or seasons.

PUT

/publicapi/customers/{customer}

Update customer name.

GET

/publicapi/customers

Get all customers. Provides a list of all user’s customers.

GET

/publicapi/cooperatives

Get all cooperatives. Provides a list of all user’s cooperatives.

POST

/publicapi/getApiKey

Get API key. Given an user/customer username and password provides an API key.

GET

/publicapi/user

Get user profile information.

Fields

Method

Call

Description

GET

/publicapi/fieldTypes

Get all field types and subtypes. Provides a list of all the types (crops) available and sub_types (sub_crop). If a different crop is required contact via support@hemav.com

GET

/publicapi/irrigationType

Get all irrigation types. Provides a list available. If a different irrigation is required contact via support@hemav.com

GET

/publicapi/fields

Get all fields. Provides a list of all user’s fields.

POST

/publicapi/field

Create new field. Requires at, least a customer_id and a name.

PATCH

/publicapi/field/{field}

Edit a field. Given a field_id, modifies the passed parameters (i.e. name, external_reference_id, customer_id).

Seasons

Method

Call

Description

GET

/publicapi/seasonParameters

Get season available parameters. Provides a list of all season parameters and its units.

GET

/publicapi/seasonLogTypes

Get available season log types.

GET

/publicapi/seasons/{season}/seasonLogs

Get logs by season.

GET

/ publicapi/seasons/{season}/snapshots

Get snapshots by season.

GET

/publicapi/seasons/{season}/parameters

Get a single season parameter. Given a season, return its parameters.

POST

/publicapi/seasons/{season}/parameters/{parameter}

Post a single season parameter value. Given a season and a parameter, creates it with a value.

PATCH

/publicapi/seasons/{season}/parameters/{parameter}

Patch a single season parameter value. Given a season and a parameter, edits its value.

DELETE

/publicapi/seasons/{season}/parameters/{parameter}

Delete a single season parameter value. Given a season and a parameter, deletes it.

GET

/publicapi/fields/{field}/seasons

Get all field associated seasons. Given a field, returns all its seasons.

POST

/publicapi/fields/{field}/season

Create new season. Given a field, creates a new season, requires startDate and endDate.

PATCH

/publicapi/seasons/{season}

Update field season. Given a season, updates its values.

Snapshots

Method

Call

Description

GET

/publicapi/snapshots/sources

Get snapshots available sources.

GET

/publicapi/seasons/{season}/snapshots

Get snapshots and delivery metadata by season.

Reports

Method

Call

Description

GET

/publicapi/reportTypes

Get available report types.

GET

/publicapi/reportStatuses

Get report statuses.

GET

/publicapi/reports

Get user reports by date range.

Postman collection

Download Postman Collection

2. HEMAV DB Organization

db_org

complete_season

3. Workflows

3.1. Customer & field creation

customer_field_creation

3.2. Update season information and creating new season

update_create_season

3.3. Extracting HEMAV DB information

3.3.1. Sat-tech, Planet, Landsat9 and drone-tech. Snapshot sources.

extract_delivery_info

3.3.2. Weather, Irrigation and Pred-tech. SeasonLog types.

seasonlog_type

all_seasonlog

4. Season requirements and limitations

4.1. Fields

All fields must be unique in our DB. For this reason, besides our internal field identification (field_id) it is highly recommended that external_reference_id is used to create a unique value in our DB. Some recommendations to create this parameter are:

  • ‘external_reference_id’ = ‘customer_id’ + ‘_’ + ‘field_id’

  • ‘external_reference_id’ = ‘customer_id’ + ‘_’ + ‘name’

  • ‘external_reference_id’ = ‘customer_id’ + ‘_’ + ‘id’

4.2. Seasons

  • There must always be a season opened in the current date.

  • Base season is opened when a field is created with start_date -4 years and end_date is set to end of current year + 2 years.

  • Type_id (crop) is set to 78 (no crop)

  • Time gaps between seasons are not allowed. Start_date new season must be end_date previous season + 1 day. For this purpose, no crop seasons are created by our system if seasons are not consecutive.

  • It is important to use the same season label located in the same area with the same start_date and end_date. This will help in Layers visualization but also in data processing.

Season format:

 {
  "startDate": "2023-01-01",
  "endDate": "2025-12-31",
  "geometry": "string",
  "surface": 0,
  "type": 0,
  "subType": 0,
  "irrigationType": 0,
  "label": "string",
  "parameterValues": [
    {
      "value": "string",
      "extraInfo": "string",
      "season": 0,
      "parameter": 0
    }
  ]
}

Mandatory keys for season creation are: startDate, endDate, type and label. Nevertheless, it is highly recommended to include as many as possible as they will help if any predictive product is contracted.

How do we set a desired season situation for a field?

Step 1 – Last season is processed first, as its start_date is greater than the start_date of the Base season – No crop. Base season no crop is closed with end_date equal to start_date of season 3 – 1 day.

Season 3 is created with its start and end date (which should be a future date).

Now we have the following situation:

load_season3

Step 2 – Now we process Season 2. As its start_date is greater than the start_date of the BASE No crop season, season no crop is closed with end_date equal to start_date of season 2 – 1 day.
On the other hand, as its end_date is equal to start_date of season 3 – 1 day, we do not need a NO CROP season between season 3 and season 2.

Season 2 is created with its start and end date.

Now we have the following situation:

load_season2

Step 3 - Season 3 is processed, as its start_date is greater than the start_date of the BASE No crop season, season no crop is closed with end_date equal to start_date of season 1 – 1 day.
If end_date of season 1 is smaller by more than one day than start_date of season 2, a no crop season is needed.

For this reason, season 1 with its start and end date is created. But also a new NO CROP season needs to be created which will have start_date equal to end_date of season 1 + 1 day and end_date equals to start_date of season 2 – 1 day.

Thus, we obtain the desired situation:

load_season1

4.3. Geometries

Geometries must be coordinates, in degrees, in WGS84 CRS. It is the only format accepted.

Geometry example:

{
	"geometry": "[[[[37.048924745685, -7.7634227285916], [37.049831149291, -7.7634268877869], [37.04982697993, -7.7643309260375],
    [37.048920574389, -7.7643267663521], [37.048924745685, -7.7634227285916]]]]"
}

4.4. Season parameters

id name measure_unit short_name measure_unit lond_name SAT TECH SAT PRED SOIL TECH
1 production kg/ha Kilograms/Hectar
2 plantation_date Soy, beetroot, corn
3 pattern m Meters
4 plantation_frame
5 plant_distance
6 street_distance
7 random_seedling
8 random_fertilization
9 auto_harvest
10 irrigation_emitters
11 irrigation_limit m3 Meters3
12 irrigation_level m3 Meters3
13 vulnerability
14 cut_number Sugar cane
15 estimated_harvest_date Sugar cane
16 harvest_date Sugar cane
17 agoste_date
18 backfertilization_estimated_date
19 backfertilization_estimated_dose kg/ha Kilograms/Hectar
20 backfertilization_estimated_N
21 backfertilization_estimated_P
22 backfertilization_estimated_K
23 backfertilization_date
24 backfertilization_dose kg/ha Kilograms/Hectar
25 backfertilization_N
26 backfertilization_P
27 backfertilization_K
28 coverfertilization_estimated_date
29 coverfertilization_estimated_dose kg/ha Kilograms/Hectar
30 coverfertilization_estimated_N
31 coverfertilization_estimated_P
32 coverfertilization_estimated_K
33 coverfertilization_date
34 coverfertilization_dose kg/ha Kilograms/Hectar
35 coverfertilization_N
36 coverfertilization_P
37 coverfertilization_K
40 irrigation_estimated_date
41 irrigation_date
42 ATR_target
43 ATR_real ATR model
44 ATR_per_hectare_target
45 ATR_per_hectare_real tn/ha Tones/Hectar
46 maturing_estimated_date
47 maturing_estimated_dose
48 maturing_estimated_product
49 maturing_date
50 maturing_dose
51 maturing_product
52 phytosanitary_date
53 phytosanitary_dose
54 phytosanitary_estimated_date
55 phytosanitary_estimated_dose
56 phytosanitary_estimated_product
57 phytosanitary_product
58 SAC_real SAC model
59 type_of_soil
60 harvest_surface ha Hectar
61 ATR_estimate
62 production_per_hectare_estimate tn/ha Tones/Hectar
63 POL_target
64 POL_real POL_model
66 customer_sub_type
67 irrigation_turn
69 irrigation_type
70 previous_crop
71 SAC_target
72 POL_estimate
73 SAC_estimate
74 production_target tn/ha Tones/Hectar
75 production_real tn/ha Tones/Hectar
76 production_estimate tn/ha Tones/Hectar
77 plants_per_hectare
78 n_bunches_real unit/ha unit/ha Bunches model


Mandatory Desirable Recommended

5. Step by step - Creating and updating season information

5.1. Get ApiKey

First of all, get your user’s api key.
get api key

5.2. Authorize

Login and authorize yourself with your ApiKey.
login_ApiKey

5.3. Get information of all your customers

Obtain your customer’s information.
customer_info

From the obtained data, we need to keep the customer’s id from the customer that we need to create a field.

5.4. Create a field

Using the customer id obtained from the previous step, we create a new field. We keep this field_id.
api_field

5.5. Check field season information

As we can check in our DB, the field creation, also creates a BASE SEASON with type_id = 78 (no crop) with start_date set as minus four years from the creation date and end_date is set as the end of the current year plus two.

db_field_season
This information can also be checked from the API.
season_data

5.6. Update season

Whether we have a recently created field, which have a base season without information, or we want to update the season’s information of a field, the PATCH method /publicapi/seasons/{season} will be used.

Only parameters that need to be modified should be included.

{
	"geometry": "[[[[37.048924745685, -7.7634227285916], [37.049831149291, -7.7634268877869], [37.04982697993, -7.7643309260375], [37.048920574389, -7.7643267663521], [37.048924745685, -7.7634227285916]]]]",
	"type": 56,
	"label": "safra_2023",
	"parameterValues": [
		{
			"value": "2",
			"parameter": 14
		},
		{
			"value": "2020-01-01",
			"parameter": 2
		}
	]
}

In this example we will update the geometry, the crop (type 56 corresponds to sugar cane) and the season parameters 14 and 2, which corresponds to cut number and plantation date.

patch_season

Depending on the crop and the contracted products different parameters will be required. You can find more information regarding season parameters on section 4.4 of this documentation.

6. Extracting information

6.1. Sat-tech, Planet, Landsat9 and drone-tech. Snapshot sources.

source_id

Description

Exracted Parameters

1

Drone with multispectral camera

Depending on the contracted deliveries. lines_l, overs_l, ndre_std, ndvi_std, nrel_std, overs_pl, ndre_mean, ndvi_mean, nrel_mean, sector_id, alert_perc, overs_stats, overs_mean_length, sector_area, plants_count, weeds_perc_fe, weeds_perc_fl, resowing_count, nitrogen_relative_std, nitrogen_relative_mean.

3

Satellite Sentinel 2

Cloud coverage, kc, ndre_mad, ndre_max, ndre_min, ndre_std, ndvi_mad, ndvi_max, ndvi_min, ndvi_std, ndre_mean, ndvi_mean, sector_id, ndre_median, ndvi_median, sector_area, moisture_mad, moisture_max, moisture_min, moisture_std, moisture_mean, ndre_kurtosis, ndvi_kurtosis, moisture_median, scene_product_id, moisture_kurtosis, ndre_first_quartile, ndre_third_quartile, ndvi_first_quartile, ndvi_third_quartile, scene_classification, nitrogen_relative_mean, moisture_first_quartile, moisture_third_quartile, potassium_relative_mean, ndre_interquartile_range, ndre_outliers_percentage, ndvi_interquartile_range, ndvi_outliers_percentage, phosphorus_relative_mean, moisture_interquartile_range, moisture_outliers_percentage.

6

Drone with RGB camera

Depending on the contracted deliveries, usually weeds and failures data.

8

Satellite Sentinel 1 SAR ascending orbit

Cloud_coverage, sector_id, std_sigma0, mean_sigma0, sector_area, scene_product_id.

9

Satellite Sentinel 1 SAR descending orbit

Cloud_coverage, sector_id, std_sigma0, mean_sigma0, sector_area, scene_product_id.

10

Satellite Planet

Bands, ndre, ndvi, sector_id, quality_bands.

11

Satellite Landsat 9

Cloud_coverage, bands, ndmi, ndvi, termal, sector_id, quality_bands, name cloud, scene_product_id

6.2. SeasonLog types. Weather, Irrigation and Pred-tech.

type_id

Name

1

SAC_ha

2

PROD_ha

10

WEATHER_historic

11

WEATHER_forecast

12

WEATHER_alert

15

TCH_pred

16

ATR_pred

17

NITRO

21

IRR_needs_forecast

22

IRR_needs_historic

23

POL_pred

24

n_bunches_pred