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.

In addition to this transactional API, Layers exposes a read-only analytical API — the Data API — from which the already processed and aggregated data can be consumed: spectral statistics, forecasts, weather and global map layers. It is documented in section 8.

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.

Samples

Method	Call	Description
GET	/api/fields/{field}/plantsHistoric	Get all the active samples of a field.
GET	/api/plantsHistoric	Get samples by date range. Requires both from and to query params in yyyy-mm-dd format.
POST	/api/plantsHistoric	Create a new sample. The type and the metadata keys must reference ids from the Samples tables.
PATCH	/api/plantsHistoric/{sample}	Update a sample. Samples are versioned: editing creates a new sample with a new id and deactivates the previous one. Send {"toDelete": true} to deactivate it.

Postman collection

Download Postman Collection

Forecasting

Layers ofrece una API dedicada a la obtención de predicciones de productividad y calidad de cultivos, generadas por los modelos de Crop Predictor.

• Swagger UI: https://agropred.layers.hemav.com/docs

• Documentación completa: API de Crop Predictor — endpoints, autenticación, esquemas de request/response y ejemplos de uso.

Data API

Read-only analytical API served from the data warehouse. Its end points, conventions and response schemas are described in section 8. Data API.

Method	Call	Description
GET/POST	/statistics	Spectral and radar statistics per field and date.
GET/POST	/forecast	Productivity and quality forecasts.
GET/POST	/weather	Daily temperature series of a field.
GET/POST	/global_maps	Geometries, properties and legends of the global map layers.

2. HEMAV DB Organization

3. Workflows

3.1. Customer & field creation

3.2. Update season information and creating new season

3.3. Extracting HEMAV DB information

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

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

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:

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:

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:

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
79	customer_comment
80	avg_bunch_weight	kg	Kilograms
81	harvest_moisture	%	Percentage
82	male_plants_per_hectare
83	female_plants_per_hectare
85	female_flowering_50
86	female
87	male
88	female_planting
89	male_1_planting
90	male_2_planting
91	plants_density
92	date_flowering
93	cycle_number
94	field_use
95	field_cost	sol/Ha	peruvian soles per hectare
96	brix_real
97	purity_real
98	reducers_real
99	humidity_real
100	company
101	real_age
102	irrigation_real_applied_volume	m3/ha	Meters3/Hectar

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.

5.2. Authorize

Login and authorize yourself with your ApiKey.

5.3. Get information of all your customers

Obtain your customer’s information.

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.

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.

This information can also be checked from the API.

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.

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. Samples

6.1. Sample types

type_id	Name
1	Disease *
2	Generic
3	Leaf
4	Production
5	Quality
6	Soil
7	Plague
8	Weeds
9	Plant Density
10	Safety
11	Plant
12	Irrigation
13	Nitrogen

* Only available by request.

6.2. Sample parameters

parameter_id	Parameter	Data type	Unit	Sample type(s)
306	ag_accesses_the_viewer	string		13
14	aluminum	float	%	3, 6
30	aluminum	float	cmol/dm3	6
51	aluminum	float	ppm	3, 6
74	aluminum	float	ppm (mgL)	6
319	aluminum_saturation	float	%	6
117	aphid_controller	string		7
203	aphid_infested	int	%	7
116	aphid_infested_leafs	int		7
115	aphid_mite_total_leafs	int		7
40	apparent_density	float	kg/m3	5, 6
270	assesor_name	string		10
257	atr	float		4
312	avg_bunch_weight	float		4
45	base_saturation	float	me/100g	6
1	beans_10_plants	int		4, 5
196	billaea_healthy_pupe	int		7
195	billaea_larva	int		7
194	billaea_parasitized_larva	int		7
197	billaea_residual_pupe	int		7
147	bipolaris_sacchari_G1	int		7
148	bipolaris_sacchari_G2	int		7
149	bipolaris_sacchari_G3	int		7
150	bipolaris_sacchari_G4	int		7
151	bipolaris_sacchari_G5	int		7
207	bipolaris_sacchari_incidence	int	%	7
146	bipolaris_sacchari_severity	int		7
145	bipolaris_sacchari_total_infected_leafs	int		7
191	blastobasis_healthy_chrysalis	int		7
190	blastobasis_larva_number	int		7
192	blastobasis_residual_chrysalis	int		7
52	boron	float	ppm	3, 6
75	boron	float	ppm (mgL)	6
263	bouquet10roots_2_8cm	int		5
262	bouquet10roots_2cm	int		5
264	bouquet10roots_8cm	int		5
28	break_point_height	float	cm	4, 5
69	brix	float	ºBx	4, 5
101	bud_blastobasis_drilled	int		7
104	bud_dehydrated	int		7
100	bud_diatrea_drilled	int		7
103	bud_mechanical_damage	int		7
102	bud_sprout	int		7
98	bud_total	int		7
99	bud_turgid	int		7
46	ca_k	float	me/100g	3, 6
47	ca_mg	float	me/100g	3, 6
48	ca_mg_k	float	me/100g	6
15	calcium	float	%	3, 4, 6
31	calcium	float	cmol/dm3	6
53	calcium	float	ppm	3, 4, 6
76	calcium	float	ppm (mgL)	6
321	calcium_saturation	float	%	6
54	carbon	float	ppm	3, 6
222	casida_afa_perc	int	%	7
218	casida_n_of_adults_in_50_plants	int		7
219	casida_n_of_eggs_in_50_plants	int		7
221	casida_n_of_large_larvae_in_50_plants	int		7
220	casida_n_of_small_larvae_in_50_plants	int		7
258	casida_treatment	string		7
230	cercospora_20_100_spots_leaf	string		1
236	cercospora_50_afa	string		1
235	cercospora_50_perc_leaves_ext_with_80_100_severity	string		1
237	cercospora_75_afa	string		1
238	cercospora_90_100_afa	string		1
225	cercospora_healthy_plant	string		1
228	cercospora_isolated_spots_on_some_leaves_10_15_sl_100_leaves	string		1
227	cercospora_isolated_spots_on_some_leaves_5_10_sl_100_leaves	string		1
226	cercospora_isolated_spots_on_some_leaves_minus_5_sl_100_leaves	string		1
232	cercospora_leaf_necrosis_ext	string		1
234	cercospora_leaves_ext_almost_total_necrosis	string		1
231	cercospora_leaves_with_major_100_sports	string		1
229	cercospora_minus_20_spots_leaf	string		1
233	cercospora_necrosis_on_most_leaves_int	string		1
286	cercospora_treatment	string		1
326	chromium	float	µg/kg	6
2	cic	float		6
16	clay	float	%	6
3	cluster	int		4, 5
67	cnd_elec	float	mS/cm	3, 6
55	copper	float	ppm	3, 6
77	copper	float	ppm (mgL)	6
216	cotyledon	string		8
4	ctc	float		3, 6
301	current_ndre_status	string		13
311	date_of_first_informative_email_sent	date		13
309	date_of_hemav_ndre_layer_screenshot	date		13
124	defoliator_leaf_evaluated	int		7
131	defoliator_marasmia_sp_larva_alive	int		7
132	defoliator_marasmia_sp_larva_death	int		7
133	defoliator_marasmia_sp_larva_per_stem	int		7
125	defoliator_mythimna_sp_larva_alive	int		7
126	defoliator_mythimna_sp_larva_death	int		7
127	defoliator_mythimna_sp_larva_per_stem	int		7
128	defoliator_spodoptera_sp_larva_alive	int		7
129	defoliator_spodoptera_sp_larva_death	int		7
130	defoliator_spodoptera_sp_larva_per_stem	int		7
123	defoliator_stem_total	int		7
41	depth	float	m	6
29	diameter	float	cm	4, 5
186	diatraea_saccharalis_larva_big	int		7
188	diatraea_saccharalis_larva_healthy_chrysalis	int		7
185	diatraea_saccharalis_larva_medium	int		7
189	diatraea_saccharalis_larva_residual_chrysalis	int		7
184	diatraea_saccharalis_larva_small	int		7
187	diatraea_saccharalis_larva_total	int		7
5	disease	string		1, 3, 4, 5, 6, 7
298	disease_level	string		4
300	distance_between_rows	int	m	4
305	does_it_follow_the_recommendation	string		13
17	dry_matter	float	%	3, 4
276	dry_weight	float	g	4
314	effective_cation_exchange_capacity	float	me/100g	6
6	evaluator	string		1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 13
316	exchangeable_acidity	float	me/100g	6
331	fire	string		10
335	flowering	string		11
291	forecast_yield_sampling_1	float	kg/ha	4
292	forecast_yield_sampling_2	float	kg/ha	4
293	forecast_yield_sampling_3	float	kg/ha	4
294	forecast_yield_sampling_4	float	kg/ha	4
277	fresh_weight	float	g	4
7	fruits_count	int		4, 5
215	green_dots	string		8
49	h_al	float	me/100g	6
338	hanger_installation	int		7
278	height	float	cm	4
271	herb_residual_field_without_symptoms	string		11
273	herb_residual_mid_field_5_10_affected_surf	string		11
274	herb_residual_severe_field_10_25_affected_surf	string		11
272	herb_residual_slight_field_below_5_affected_surf	string		11
275	herb_residual_very_severe_field_above_25_affected_surf	string		11
303	high_n_from_irrigation_water	string		13
304	high_n_from_nitrogen_input	string		13
302	high_n_from_previous_years	string		13
18	humidity	float	%	4, 5, 6
19	humidity_100_beans	float	%	4, 5
202	internodes_blastobasis_damage_longitude	int	m	7
95	internodes_blastobasis_drilled	int		7
201	internodes_diatraea_damage_longitude	int	m	7
94	internodes_diatraea_drilled	int		7
92	internodes_evaluated	int		7
93	internodes_healthy	int		7
96	internodes_mechanical_damage	int		7
8	internodes_number	int		4, 5
97	internodes_physiological_damage	int		7
56	iron	float	ppm	3, 6
78	iron	float	ppm (mgL)	6
282	irrigation_dosage	string		12
281	irrigation_uniformity	string		12
295	label	string		4
181	larva_number_big	int		7
180	larva_number_medium	int		7
179	larva_number_small	int		7
307	last_fertilizer_app_date	date		13
283	last_irrigation	string		12
57	lead	float	ppm	3, 6
324	lead	float	µg/kg	6
280	leaf_moisture_status	string		12
154	leptosphaeria_sacchari_G1	int		7
155	leptosphaeria_sacchari_G2	int		7
156	leptosphaeria_sacchari_G3	int		7
157	leptosphaeria_sacchari_G4	int		7
158	leptosphaeria_sacchari_G5	int		7
208	leptosphaeria_sacchari_incidence	int	%	7
153	leptosphaeria_sacchari_severity	int		7
152	leptosphaeria_sacchari_total_infected_leafs	int		7
42	linear_meters	float	m	1, 2, 3, 4, 5, 6, 7
332	loss_of_vigor	string		11
268	lowered_unload	int		10
32	magnesium	float	cmol/dm3	6
58	magnesium	float	ppm	3, 4, 6
79	magnesium	float	ppm (mgL)	6
317	magnesium_saturation	float	%	6
59	manganese	float	ppm	3, 6
80	manganese	float	ppm (mgL)	6
313	medium_moisture_saturation	float	%	6
323	mercury	float	µg/kg	6
50	mg_k	float	me/100g	3, 6
200	microorganisms_larva	int		7
119	mite_grade	string		7
204	mite_infested	int	%	7
118	mite_infested_leafs	int		7
297	moisture_status	string		4
60	molybdenum	float	ppm	3
211	n_bunches	int		4
81	n_no3	float	ppm (mgL)	6
325	nickel	float	µg/kg	6
89	nitrogen	float	%	3, 6
61	nitrogen	float	ppm	3, 6
308	notification_to_the_farmer_high_n_index	date		13
9	num_plants	int		4, 5
114	Observations	string		7
193	opogona_larva_number	int		7
88	organic_material	float	%	3, 6
315	organic_oxidizable_carbon	float	%	6
342	percent_diatraea_infestation	float	%	7
13	percent_disease	float	%	1, 3, 4
90	percentage_maturation	float	%	5
105	perkinsiella_345_instar_nymph	int		7
106	perkinsiella_adult	int		7
111	perkinsiella_controller_coccinelidos	int		7
112	perkinsiella_controller_crysopas	int		7
113	perkinsiella_controller_spiders	int		7
109	perkinsiella_controller_tytthus_parviceps	int		7
110	perkinsiella_controller_zelus	int		7
108	perkinsiella_death_adult	int		7
107	perkinsiella_death_nymph	int		7
310	petiole_sampling	date		13
27	ph	float	CaCi2	3, 6
35	ph	float	h2o	3, 6
86	ph	float	smp	3, 6
160	pheromone_trap_diatraea_adults_number	int		7
163	pheromone_trap_installation_date	date		7
159	pheromone_trap_number	int		7
161	pheromone_trap_other_butterfly	int		7
162	pheromone_trap_pheromone_change	string		7
20	phosphorus	float	%	3, 4, 6
62	phosphorus	float	ppm	3, 4, 6
70	phosphorus	float	ppm (mgL) Bray	6
71	phosphorus	float	ppm (mgL) Mehlich	6
72	phosphorus	float	ppm (mgL) Olsen	6
73	phosphorus	float	ppm (mgL) Res	6
299	plague_level	string		4
214	plant_density_range	string		9
43	plant_length	float	m	4, 5
213	plants_per_surface_unit	float	unit/ha	9
68	pol	float	º	4, 5
21	potassium	float	%	3, 4, 6
33	potassium	float	cmol/dm3	6
63	potassium	float	ppm	3, 4, 6
82	potassium	float	ppm (mgL)	6
320	potassium_saturation	float	%	6
224	powdery_mildew_afa_perc	float	%	1
223	powdery_mildew_perc_of_affected_plants	float	%	1
287	powdery_mildew_treatment	string		1
120	pseudomonas_rubrilineans_stem_number	int		7
122	pseudomonas_rubrilineans_stem_number_affected	int		7
121	pseudomonas_rubrilineans_stem_number_with_symptoms	int		7
209	puccinia_melanocephala_accumulated_scale	int	%	7
210	puccinia_melanocephala_infestation	int	%	7
176	puccinia_melanocephala_infested_leafs	int		7
174	puccinia_melanocephala_points	int		7
175	puccinia_melanocephala_total_leafs	int		7
140	puccinia_sp_G1	int		7
141	puccinia_sp_G2	int		7
142	puccinia_sp_G3	int		7
143	puccinia_sp_G4	int		7
144	puccinia_sp_G5	int		7
206	puccinia_sp_incidence	int	%	7
139	puccinia_sp_severity	int		7
138	puccinia_sp_total_infected_leafs	int		7
339	purity	float	%	5
217	real_leaves	int		8
340	reducers	float	%	5
337	reform	string		4, 11
212	resowing_surface	float	ha	2
330	rodents_infestation_percent	float	%	7
261	rot10roots_complete	int		5
259	rot10roots_nothing	int		5
260	rot10roots_partial	int		5
254	rust_100_afa	string		1
249	rust_10_25_afa	string		1
250	rust_25_35_afa	string		1
251	rust_35_50_afa	string		1
248	rust_3_10_afa	string		1
252	rust_50_75_afa	string		1
253	rust_75_90_afa	string		1
240	rust_healthy_plant	string		1
242	rust_isolated_spots_on_some_leaves_10_19_perc	string		1
241	rust_isolated_spots_on_some_leaves_1_9_perc	string		1
243	rust_isolated_spots_on_some_leaves_20_29_perc	string		1
244	rust_isolated_spots_on_some_leaves_30_50_perc	string		1
255	rust_regrowth_restart	string		1
247	rust_spots_leaves_100_300	string		1
246	rust_spots_leaves_20_100	string		1
245	rust_spots_leaves_50	string		1
285	rust_treatment	string		1
87	sac	float	tn/ha	4, 5
296	sample_color	string		4
22	sand	float	%	6
23	severity	float	%	1, 3, 7
10	shoot_number_1m	int		4, 5
24	silt	float	%	6
44	soca_width	float	m	4
34	sodium	float	cmol/dm3	6
64	sodium	float	ppm	3, 6
83	sodium	float	ppm (mgL)	6
318	sodium_saturation	float	%	6
279	soil_moisture_status	string		12
333	sowing_failure	string		4, 11
178	sprout_dead	int		7
177	sprout_total	int		7
25	starch	float	%	3, 4, 5
11	stem_number	int		4, 5
91	stems_evaluated	int		7
65	sulfur	float	ppm	3, 6
84	sulfur	float	ppm (mgL)	6
336	tombing	string		11
322	total_arsenic	float	µg/kg	6
327	total_cadmium	float	µg/kg	6
36	total_recoverable_sugar	float	kg	4, 5
12	type_disease	string		1, 3, 4
334	uneven_budding	string		11
205	ustilago_scitaminea_infection	int	%	7
137	ustilago_scitaminea_stem_affected	int		7
135	ustilago_scitaminea_stem_symptoms	int		7
134	ustilago_scitaminea_stem_total	int		7
136	ustilago_scitaminea_stem_whip	int		7
170	virgin_female_georeferenced_trap_diatraea_adult_total	int		7
172	virgin_female_georeferenced_trap_female_change	string		7
171	virgin_female_georeferenced_trap_other_butterfly	int		7
169	virgin_female_georeferenced_trap_point	int		7
165	virgin_female_trap_diatraea_adult_number	int		7
167	virgin_female_trap_female_change	string		7
168	virgin_female_trap_installation_date	date		7
164	virgin_female_trap_number	int		7
166	virgin_female_trap_other_butterfly	int		7
265	weed_unload	int		5
37	weight	float	tn/ha	4, 5
38	weight_100_beans	float	kg	4, 5
39	weight_5_canes	float	kg	4, 5
329	weight_kg	float	kg	4
26	whey	float	%	4, 5
266	without_footwear	int		10
269	without_gloves	int		10
267	without_vest	int		10
288	yellowness_mild	string		1
289	yellowness_moderate	string		1
290	yellowness_strong	string		1
328	yellowness_without_symptoms	string		1
66	zinc	float	ppm	3, 6
85	zinc	float	ppm (mgL)	6

The Sample type(s) column lists the type_ids (see Sample types) for which each parameter is valid. A parameter can only be created in a sample whose type is one of those listed — sending a parameter in a metadata object for a non-matching type will be rejected.

6.3. Request examples

6.3.1. Create a sample

A sample is created against the plantsHistoric endpoint. The type and the keys of metadata must reference ids from the tables above.

The minimum required fields to create a sample are: lat, lon, field, seasonId, source and type. Any other field (such as notes or metadata) is optional.

curl --location --globoff 'https://processing.hemav.com/api/plantsHistoric/?api_key={{apikey}}' \
--header 'Content-Type: application/json' \
--header 'Cookie: hl=es' \
--data '{
    "lat": 41.3851,
    "lon": 2.1734,
    "field": 28218,
    "seasonId": 18085,
    "type": 2,
    "source": 8,
    "notes": "sample notes",
    "metadata": {
        "3": 1,
        "7": 42,
        "12": "example"
    }
}'

Notes on the payload:

• type — must be a type_id from the Sample types table (e.g. 2 = Generic). Remember that type 1 (Disease) is only available by request.

• source - must be always 8.

• metadata — an object whose keys are parameter_ids from the Sample parameters table, and whose values must match the data type of that parameter. A parameter defined as float/int must receive a number, and a string parameter a text value; sending a value of the wrong type will be rejected.

Versioning — Samples are never deleted, they are versioned. Every time a sample is created or modified, a new sample with a different id is generated and the previous one is deactivated. The value that stays constant across versions is the external_id.

6.3.2. Update a sample

Updating is done with the PATCH method. The body is the same as in the create request except for field and seasonId, which cannot be modified.

curl --location --globoff --request PATCH 'https://processing.hemav.com/api/plantsHistoric/{sample}?api_key={{apikey}}' \
--header 'Content-Type: application/json' \
--header 'Cookie: hl=es' \
--data '{
    "lat": 41.3851,
    "lon": 2.1734,
    "type": 2,
    "notes": "sample notes",
    "metadata": {
        "3": 1,
        "7": 42,
        "12": "example"
    }
}'

As noted above, this does not edit the existing record in place: it creates a new versioned sample (new id) and deactivates the previous one, keeping the same external_id.

To deactivate a sample without creating a new version, send:

{
    "toDelete": true
}

6.3.3. Get the samples of a field

Use the GET method to retrieve all the samples of a given field.

curl --location --globoff 'https://processing.hemav.com/api/fields/{{field_id}}/plantsHistoric?api_key={{apikey}}'

Only the active samples are returned: deactivated versions (replaced by a newer version or removed with {"toDelete": true}) are not included in the response.

6.3.4. Get samples by date range

The samples can also be requested without scoping to a field, filtering by a date range with the from and to query parameters:

curl --location --globoff 'https://processing.hemav.com/api/plantsHistoric?api_key={{apikey}}&from=2024-01-01&to=2024-12-31'

• Dates must use the yyyy-mm-dd format.

• Both from and to are required together — providing only one of them will not work.

As with the field-scoped GET, only the active samples are returned.

7. Extracting information

7.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

7.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

8. Data API

Besides the transactional API described in the previous sections (/publicapi, /api), Layers exposes a second, read-only analytical API: the Data API.

While the transactional API is the entry point to create and update customers, fields and seasons, the Data API is the entry point to consume the information that Layers has already processed and aggregated: per-field spectral statistics, productivity and quality forecasts, weather series and the layers of the global map. All of it is served from the data warehouse (AWS Athena) over tables that are materialized daily, so queries that would be too heavy against the transactional database are resolved in seconds.

• Swagger UI in PROD environment: https://data.layers.hemav.com/docs

• Swagger UI in DEV environment: https://data.layersdev.hemav.com/docs

8.1. Data API end points

Method	Call	Description
GET/POST	/statistics	Spectral and radar statistics per field and date, from satellite or drone snapshots.
GET/POST	/forecast	Productivity and quality forecasts (weekly curve, ideal curve, season maximum and the full prediction log).
GET/POST	/weather	Daily temperature series of a field.
GET/POST	/global_maps	Geometries, properties and legends of the global map layers.
GET	/healthy	Service health check. Also available at the root path (/).

8.2. Conventions

The Data API follows the same conventions on every end point:

Authentication. Every request requires the api_key parameter in the query string — it is the only parameter that never travels in the body. It is the same key returned by POST /publicapi/getApiKey (see section 5.1). If the key is missing the API answers 401, and if it does not exist 403.

Request. All end points accept both GET and POST, and in both cases the parameters other than api_key are sent in the JSON body with the header Content-Type: application/json. Using POST is recommended.

Response. The payload is always an object with a single data key containing the list of rows:

{
  "data": [ ... ]
}

Scope. The api_key determines what is visible: only the fields the user can access as customer, agro-user or cooperative are returned. Any field_id outside that scope is simply not present in the response — it does not raise an error.

Freshness. The underlying tables are refreshed daily by the materialization processes, so the most recent data available is normally the previous day’s.

Pagination. It is handled internally by the service: the full result set is returned in a single response, without any cursor to follow. Take that into account when requesting wide date ranges or long lists of fields.

Compression. Responses larger than 1 MB are returned gzip-compressed. Send Accept-Encoding: gzip and make sure your HTTP client decompresses transparently (most of them do).

Errors.

Code	Meaning
401	Not authenticated. The api_key query parameter was not provided.
403	API key not found. The provided key does not correspond to any user.
400	Invalid log_type. Only raised by /forecast when log_type is not one of the accepted values.
404	The end point does not exist.
422	Validation error in the body. The detail key describes which field failed and which values are accepted.

8.3. /statistics

Returns the statistics computed for each field and each snapshot in a date range. The source determines both the sensor and the shape of the response.

Parameter	Type	Required	Description
api_key	string	Yes	User api key. Query string.
from	date	Yes	Start of the range, yyyy-mm-dd format (e.g. 2024-05-26).
to	date	Yes	End of the range, yyyy-mm-dd format.
source	int	Yes	Snapshot source. Accepted values: 1, 3, 6, 7, 8, 9, 10, 11 (see section 7.1).
field_ids	list of int	Yes	Fields to query. They must be within the scope of the api_key.
cloud_coverage	int	No	Maximum cloud coverage percentage. Defaults to 80. Only applies to optical satellite sources (3, 10, 11).
latest	bool	No	If true, returns only the statistics of the latest snapshot available in the range. Defaults to false.

The sources are grouped into three families, and each one returns a different set of columns:

Family	source	Sensor
Optical satellite	3, 10, 11	Sentinel 2, Planet and Landsat 9.
Radar satellite	7, 8, 9	Sentinel 1 SAR (combined, ascending and descending orbit).
Drone	1, 6	Multispectral camera and RGB camera.

Sending a source that does not exist returns 422 indicating the accepted values for that family (e.g. Input should be 3, 10 or 11).

Response for optical satellite sources (3, 10, 11):

{
  "data": [
    {
      "field_id": 1,
      "source": 3,
      "field_name": "string",
      "customer_name": "string",
      "flight_date": "2024-05-26",
      "cloud_coverage": 0,
      "ndvi_mean": 0,
      "ndvi_std": 0,
      "ndre_mean": 0,
      "moisture_mean": 0,
      "nitrogen_relative_mean": 0,
      "potassium_relative_mean": 0,
      "phosphorus_relative_mean": 0
    }
  ]
}

Response for radar sources (7, 8, 9):

{
  "data": [
    {
      "field_id": 1,
      "source": 8,
      "field_name": "string",
      "customer_name": "string",
      "flight_date": "2024-05-26",
      "std_sigma0": 0,
      "mean_sigma0": 0
    }
  ]
}

Response for drone sources (1, 6):

{
  "data": [
    {
      "field_id": 1,
      "source": 1,
      "field_name": "string",
      "customer_name": "string",
      "flight_date": "2024-05-26",
      "ndvi_mean": 0,
      "ndvi_std": 0,
      "ndre_mean": 0,
      "nitrogen_relative_mean": 0,
      "potassium_relative_mean": 0,
      "phosphorus_relative_mean": 0,
      "moisture_mean": 0,
      "count": 0,
      "overs_pl": 0,
      "overs_perc": 0,
      "lines_l": 0,
      "plant_counts": 0,
      "perc_alerts": 0,
      "perc_weeds": 0
    }
  ]
}

Not every field is populated for every delivery: the available columns depend on the contracted products, as described in section 7.1.

8.4. /forecast

Returns the predictions generated by the Layers models. The mode selects which of the four views of the forecast is returned.

Parameter	Type	Required	Description
api_key	string	Yes	User api key. Query string.
mode	string	No	weekly, ideal_season, season_max or pred_tech_layers_log. Defaults to weekly.
log_type	int	Yes1	Type of prediction. Accepted values: 1, 2, 16, 17, 23.
field_ids	list of int	Yes2	Fields to query. They must be within the scope of the api_key.

¹ Required in the weekly, ideal_season and season_max modes. It is not used in pred_tech_layers_log. ² Required in the weekly and pred_tech_layers_log modes. The ideal_season and season_max modes aggregate over all the user’s fields and ignore it.

The accepted log_type values are a subset of the season log types listed in section 7.2:

log_type	Name	Prediction
1	SAC_ha	Sucrose per hectare.
2	PROD_ha	Productivity per hectare.
16	ATR_pred	Total recoverable sugar.
17	NITRO	Nitrogen.
23	POL_pred	Polarization.

Any other value returns 400 with Invalid log_type.

Mode weekly — weekly evolution of the prediction for each requested field:

{
  "data": [
    {
      "customer_name": "string",
      "field_id": 1234,
      "field_name": "string",
      "week_from_plantation_date": 1,
      "week_avg": 12.5,
      "log_date": "2024-02-18"
    },
    {
      "customer_name": "string",
      "field_id": 1234,
      "field_name": "string",
      "week_from_plantation_date": 2,
      "week_avg": 12.2,
      "log_date": "2024-02-25"
    }
  ]
}

Mode ideal_season — reference curve of the user, averaged per week from the plantation date:

{
  "data": [
    { "week_from_plantation_date": 1, "avg": 12.3 },
    { "week_from_plantation_date": 2, "avg": 12.5 }
  ]
}

This mode may legitimately return an empty list when there is no reference curve available for that log_type.

Mode season_max — maximum value of the season for that log_type:

{
  "data": [
    { "value": 13.3 }
  ]
}

Mode pred_tech_layers_log — full prediction log per field and season. It is the most detailed view: it returns one row per field with the season metadata, the estimation of every magnitude with its deviation, the real values once they are known, and the aggregates of the user for that forecast execution date.

Group	Columns
Field and season	field_id, field_name, type, subtype, surface, season_id, season_label, life_cycle, start_date, end_date, plantation_date, harvest_date, estimated_harvest_date, cut_number
Estimations	hemav_estimation_date, hemav_prodph_estimation, hemav_atr_estimation, hemav_pol_estimation, hemav_sac_estimation, hemav_n_bunches_estimation, hemav_nitrogen_estimation
Deviations	hemav_prodph_deviation, hemav_atr_deviation, hemav_pol_deviation, hemav_sac_deviation
Real values	real_prodph, real_atr, real_pol, real_sac
Quality of the data	all_fields_updated, faulty_data, season_creation_date, season_update_date, forecast_execution_date
Aggregates per user	For each magnitude (prodph, atr, pol, sac, n_bunches, nitrogen), the columns hemav_<magnitude>_count, hemav_<magnitude>_estimation_avg, hemav_<magnitude>_estimation_min and hemav_<magnitude>_estimation_max.

Rows flagged with faulty_data are excluded from the aggregates, but they are still returned so the client can decide what to do with them.

8.5. /weather

Returns the daily temperature series of a single field.

Parameter	Type	Required	Description
api_key	string	Yes	User api key. Query string.
from	date	Yes	Start of the range, yyyy-mm-dd format.
to	date	Yes	End of the range, yyyy-mm-dd format.
field_id	int	Yes	Field to query. Note it is a single field, not a list.

{
  "data": [
    {
      "customer_name": "string",
      "field_id": 1,
      "field_name": "string",
      "temp": 25,
      "date": "2023-01-01"
    },
    {
      "customer_name": "string",
      "field_id": 1,
      "field_name": "string",
      "temp": 26,
      "date": "2023-01-02"
    }
  ]
}

The range may cover both past and future dates: the series combines the observed history with the computed forecast.

8.6. /global_maps

Returns the layers of the global map — the view that renders all the user’s fields on a single map — and the legends needed to colour them.

Parameter	Type	Required	Description
api_key	string	Yes	User api key. Query string.
mode	string	No	global_map, centroid, legend or deliverable_legend. Defaults to global_map.

Modes global_map and centroid — one row per field with its geometry and its properties. Both modes return the same payload:

{
  "data": [
    {
      "geojson": {
        "geometry": "{\"type\":\"Point\",\"coordinates\":[-64.16187851,-31.57441483],\"crs\":{\"type\":\"name\",\"properties\":{\"name\":\"EPSG:0\"}}}",
        "properties": "{\"gm_field_id\":3524,\"gm_name\":\"TEST\",\"gm_type_name\":\"NO CULTIVO\",\"gm_avg_ndvi\":null,\"gm_cut_number\":null,\"gm_harvest_estimated_date\":null,\"gm_hemav_atr_estimation\":null,\"gm_hemav_estimation_date\":null,\"gm_hemav_pol_estimation\":null,\"gm_hemav_prodph_estimation\":null,\"gm_hemav_realprodph_lastseason\":null,\"gm_hemav_sac_estimation\":null,\"gm_luvi_ndvi_mean\":null,\"gm_lws_mean\":null,\"gm_ndmi_mean\":null,\"gm_ndre_mean\":null,\"gm_perc_overseeding\":null,\"gm_perc_weeds\":null,\"gm_season_label\":null,\"gm_sub_type_name\":null}"
      }
    }
  ]
}

Note that geometry and properties arrive as strings containing JSON, so they need a second parse on the client side. The properties are prefixed with gm_ and cover the field identification, the current season, the last delivery of each index (NDVI, NDRE, NDMI, LUVI, LWS), the weeds and overseeding percentages and the estimations of the season.

Mode legend — for each property of the map, the range of values present in the user’s data, used to build the colour scales:

{
  "data": [
    {
      "geojson": {
        "gm_hemav_prodph_estimation": { "min": null, "max": null },
        "gm_hemav_atr_estimation": { "min": null, "max": null },
        "gm_hemav_pol_estimation": { "min": null, "max": null },
        "gm_hemav_sac_estimation": { "min": null, "max": null },
        "gm_hemav_realprodph_lastseason": { "min": null, "max": null },
        "gm_cut_number": { "min": null, "max": null },
        "gm_lws_mean": { "min": null, "max": null },
        "gm_harvest_estimated_date": { "min": null, "max": null },
        "gm_season_label": "",
        "gm_sub_type_name": "",
        "gm_type_name": "NO CULTIVO,DESCONOCIDO"
      }
    }
  ]
}

Numeric properties are returned as a min/max object, while categorical ones are returned as a comma-separated list of the values present.

Mode deliverable_legend — the fixed legend of each deliverable: the intervals and their colours. Unlike the previous modes, it is not scoped to the api key, it is the shared catalogue of legends:

{
  "data": [
    {
      "deliverable_id": "333",
      "basefilename": "gm_avg_ndvi",
      "deliverable_name": "Vigor Vegetativo (NDVI-Drone)",
      "legend_name": "0.45",
      "color": "#0000fe"
    },
    {
      "deliverable_id": "333",
      "basefilename": "gm_avg_ndvi",
      "deliverable_name": "Vigor Vegetativo (NDVI-Drone)",
      "legend_name": "0.25",
      "color": "#b6fe8f"
    }
  ]
}

8.7. Request examples

Satellite statistics of three fields over a date range, keeping only snapshots with less than 30% clouds:

curl --location --globoff 'https://data.layers.hemav.com/statistics?api_key={{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "from": "2024-01-01",
    "to": "2024-12-31",
    "source": 3,
    "field_ids": [48567, 45255, 45256],
    "cloud_coverage": 30
}'

Latest available snapshot only, for the same fields:

curl --location --globoff 'https://data.layers.hemav.com/statistics?api_key={{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "from": "2024-01-01",
    "to": "2024-12-31",
    "source": 3,
    "field_ids": [48567, 45255, 45256],
    "latest": true
}'

Weekly productivity forecast of two fields:

curl --location --globoff 'https://data.layers.hemav.com/forecast?api_key={{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "mode": "weekly",
    "log_type": 2,
    "field_ids": [455016, 455018]
}'

Reference curve of the user for the same prediction:

curl --location --globoff 'https://data.layers.hemav.com/forecast?api_key={{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "mode": "ideal_season",
    "log_type": 2
}'

Full prediction log of a field:

curl --location --globoff 'https://data.layers.hemav.com/forecast?api_key={{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "mode": "pred_tech_layers_log",
    "field_ids": [455016]
}'

Temperature series of a field:

curl --location --globoff 'https://data.layers.hemav.com/weather?api_key={{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "from": "2025-04-01",
    "to": "2025-12-31",
    "field_id": 32001
}'

Layers of the global map and their legend:

curl --location --globoff 'https://data.layers.hemav.com/global_maps?api_key={{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "mode": "global_map"
}'

curl --location --globoff 'https://data.layers.hemav.com/global_maps?api_key={{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "mode": "legend"
}'