# 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](https://processing.hemav.com/publicapi/doc).
- Check the available resources in **DEV environment** [here](https://processingdev.hemav.com/publicapi/doc).
## 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](mailto: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](mailto: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](downloads/PublicAPI_HEMAV.postman_collection.json)
## 2. HEMAV DB Organization
![db_org](img/Imagen1_db_org.png "HEMAV internal DB structure")
![complete_season](img/season1_org.png "HEMAV field seasons organization")
## 3. Workflows
### 3.1. Customer & field creation
![customer_field_creation](img/API_flows-Page-1.png "Customer and field creation")
### 3.2. Update season information and creating new season
![update_create_season](img/API_flows-Page-2.png "Update and create season")
### 3.3. Extracting HEMAV DB information
#### 3.3.1. Sat-tech, Planet, Landsat9 and drone-tech. Snapshot sources.
![extract_delivery_info](img/API_flows-Page-3.png "Extract deliveries metadata")
#### 3.3.2. Weather, Irrigation and Pred-tech. SeasonLog types.
![seasonlog_type](img/API_flows-Page-4.png "Extract logs by type and season")
![all_seasonlog](img/API_flows-Page-5.png "Extract all user logs")
## 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](img/5-2_loadseason1.PNG "Load season 3")
**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](img/5-2_loadseason2.PNG "Load season 2")
**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](img/5-2_loadseason3.PNG "Load season 1")
### 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](img/4-1_apikey.PNG "Get ApiKey")
### 5.2. Authorize
Login and authorize yourself with your ApiKey.
![login_ApiKey](img/4-2_authorize.PNG "Log in with api key")
### 5.3. Get information of all your customers
Obtain your customer's information.
![customer_info](img/4-3_customer.PNG "Customers 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.
![api_field](img/4-4_field.PNG "Create 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](img/4-4_DB_field.jpg "DB field season information")
This information can also be checked from the API.
![season_data](img/4-5_getseason.jpg "Get 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](img/4-6_updateseason.jpg "Update 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](#44-season-parameters) 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 |