FAQ
Welcome to the FAQ page of our API documentation!
Here, we address common questions and provide clarifications to help you navigate and implement our APIs seamlessly. Explore the frequently asked questions below for quick insights into key aspects of our APIs, troubleshooting tips, and best practices.
For any inquiries or assistance, please feel free to reach out to our support team at api.support@gmail.com. We're here to help you with any API-related questions or issues you may encounter, and our team is dedicated to providing prompt and helpful responses.
What is EOSDA API Connect?
EOSDA API Connect is a RESTful API, seamlessly integrating satellite data into your applications or existing GIS tools. Offering fast and easy access to raw, processed, and analyzed data, it brings high-quality analytics to users. Backed by EOS Data Analytics' extensive expertise in geospatial data analytics, the API is designed for businesses and environmental challenges, delivering years of proven satellite-driven solutions.
Data Types
Could you explain the different types of agricultural data that the APIs provide? This will assist us in tailoring our app's features to align with the specific needs and interests of our user base.
Agricultural data we provide:
- Vegetation indices, like (NDVI, NDSI, NDWI, RECI, NDMI, SAVI, ARVI, EVI, GCI, SIPI, NBR, MSI, ISTACK, FIDET, NDRE, CCCI, MSAVI) + custom indices (for example
(NIR-BLUE)/(NIR-RED), 2.5*((B5-B4)/(B5+6*B4-7.5*B2+1)), based on different satellite imagery, the most popular one is Sentinel2 (+ Landsat8-9, Sentinel1 radar data). We provide this data in two ways: imagery and statistics/analytics data. - Zoning data - Vegetation maps, Productivity maps
- Weather data (Meteomatics)
- Soil moisture - from 2015 for the following countries: Argentina, Australia, Brazil, Canada, Russia, Ukraine, Kazakhstan, Nigeria, USA, Indonesia. Based on SMAP SCA data, 250x250meters + MSAVI (2NIR+1-sqrt((2NIR+1)^2-8*(NIR-RED)))/2 calculation available for S2
Data formats: json, tiff, jpeg, png, html/csv - meteomatics data
Integration Possibilities
Are there any additional features or functionalities within the APIs?
Callback parameter- you may utilize callbacks for asynchronous operations. When making a request, instead of waiting for an immediate response, a callback function can be provided.Rate per minute- to enhance the rate per minute (RPM) for your service, we can increase it as per your requirements. If you need a higher RPM limit, please let us know, and we'll accommodate your request to meet your specific needs. api.support@gmail.com with your requestExample of render function on real maps with google map / with mapbox.
List of all features of EOS Connect API
Weather
Meteomatics weather advantages:
- historical weather data from 1979
- forecast data, ensemble and trend forecasts, forecasts up to 7 months
- 90 meter resolution worldwide
- huge list of different weather parameters (up to 1500)
In 1 request you can process:
- up to 10 coordinates
- up to 10 parameters
- Forecast/historical data/current data with different time_step (we can cover both history and forecast in one query)
Imagery & Analytics/Statistics tricks
- The best and fastest practice in this case is to request 1 index (max up to 3 indices), up to 365 days :
"bm_type":["NDVI"],
"date_start":"2023-01-01",
"date_end":"2023-06-01",
- Use cloudmask options in order to control cloud thresholds in the data you get:
| params.max_cloud_cover_in_aoi | (optional) filter scenes by upper threshold for cloud coverage percentage; by default 0 |
|---|---|
| params.exclude_cover_pixels | (optional, only for S2) boolean, enable/disable cloud masking using MSK_CLOUDS_B00.gml for statistics calculation; by default - true |
| params.cloud_masking_level | (optional, integer, only for S2) enable advanced cloud masking for Sentinel-2 using SCL band of product L2A.Valid values:1. (high probability clouds),2. (medium + high probability clouds),3. (medium + high probability + thin cirrus clouds)By default - null (advanced cloud masking is disabled) |
- Use callback_url parameter.
When making a request to an API, you might include a callback URL as part of the request parameters. This URL is where the API server will send results when they become available. Once the API server processes the request or completes a specific task, it sends the result to the callback URL via an HTTP request.
- Create and use custom colormaps in case of imagery
Comparing EOSDA API Connect Data with Crop-Monitoring
If you use Crop Monitoring app and want to retrieve the same images as you get there, we have some recommendations for you:
- pay attention to the colormaps: you should use the same colormaps as CM
- pay attention to the bands, aliases and formulas you use
- use S2L2A sentinel image level processing instead of S2L1C
sentinel2l2a - add parameter “calibrate”: 1
Here you can find more information and example of request
Image retrieved from API VS Image retrieved from CM:
Requests description and calculation for field_id flow
One request is one call to the server using any of our endpoints. The processes described below require a field ID which is obtained after creating a field. Creating a field consumes only one request.
Download a vegetation index
| Step | Process | Endpoint | Description | N of requests |
|---|---|---|---|---|
| 1 | Search for satellite images | https://api-connect.eos.com/scene-search/for-field/ <field_id> | The search is made for a timelapse indicating a start and end date | 1 |
| 2 | Get results of satellite image search | https://api-connect.eos.com/scene-search/for-field/ <field_id>/ <request_id> | All the satellite images available within the timelapse specified in the previous step, will be returned | 1 |
| 3 | Create a task to download 1 index image | https://api-connect.eos.com/field-imagery/indicies/ <field_id> | Choose one satellite image from the previous step to calculate a specific vegetation index | 1 |
| 4 | Download 1 inddex image image | https://api-connect.eos.com/field-imagery/ <field_id>/ <task_id> | Download the vegetation index image specified in the previous step | 1 |
Total request for the whole process - 4
Download weather forecast
| Step | Process | Endpoint | Description | N of requests |
|---|---|---|---|---|
| 1 | Retrieve weather forecast for a field | https://api-connect.eos.com/weather/forecast-high-accuracy/ <field_id> | Data provided for a time lapse defined in the request including temperature, precipitation, cloudiness, wind, humidity and more | 1 |
Total request for the whole process - 1
Download vegetation map
| Step | Process | Endpoint | Description | N of requests |
|---|---|---|---|---|
| 1 | Task to create vegetation map | https://api-connect.eos.com/zoning/vegetation-map | Segmentate your field based on a vegetation index indicateed in the request | 1 |
| 2 | Download vegetation map | https://api-connect.eos.com/zoning/maps/ <field_id>/ <zoning_map_id> | The result comprises a geojson object with the different zones grouping parts of the field with similar vegetation index | 1 |
Total request for the whole process - 2
Cloud Masking Options
There is an option to exclude cloud pixels during statistics calculation for Sentinel-2 via parameters exclude_cover_pixels and cloud_masking_level.
When exclude_cover_pixels option is enabled, then cloud masks are used, which are provided along with Sentinel-2 L1C product hosted on AWS S3.
These GML masks feature two types of clouds: "OPAQUE" and "CIRRUS". Only "OPAQUE" clouds are masked in statistics calculation.
When cloud_masking_level option is enabled, then cloud masks are built from SCL band of Sentinel-2 L2A if L2A product is available. For documentation on SCL band please refer to Classification Mask Generation. Possible values of cloud_masking_level:
1 - mask high probability clouds
2 - mask medium + high probability clouds
3 - mask medium + high probability + thin cirrus clouds
The best results are achieved when combining both SCL and GML cloud masks during statistics calculation.
The Scene Classification (SCL) algorithm allows the detection of clouds, snow and cloud shadows and generation of a classification map, which consists of three different classes for clouds (including cirrus), together with six different classifications for shadows, cloud shadows, vegetation, not vegetated, water and snow. Cloud screening is applied to the data in order to retrieve accurate atmospheric and surface parameters during the atmospheric correction step. The L2A SCL map can also be a valuable input for further processing steps or data analysis.
The SCL algorithm uses the reflective properties of scene features to establish the presence or absence of clouds in a scene. It is based on a series of threshold tests that use as input: TOA reflectance of several SENTINEL-2 spectral bands, band ratios and indexes like Normalised Difference Vegetation Index (NDVI) and Normalised Difference Snow and Ice Index (NDSI). For each of these threshold tests, a level of confidence is associated. It produces at the end of the processing chain a probabilistic cloud mask quality indicator and a snow mask quality indicator. The most recent version of the SCL algorithm includes also morphological operations, usage of auxiliary data like Digital Elevation Model and Land Cover information and exploit the parallax characteristics of SentinelSENTINEL-2 MSI instrument to improve its overall classification accuracy.