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