Skip to content

Downloading Satellite Data

Introduction

When you submit a request for any Vultus analysis, the Vultus Platform checks the availability of raw satellite data. The first check is to see if the raw satellite data has already been obtained from the satellite data provider. If the data is already downloaded into the Vultus Platform, the analysis request begins processing immediately. If the data is not already downloaded, a request is sent to the satellite data provider and the download processing begins.

The downloading of raw satellite data is often the slowest part of processing your request. If you send multiple requests for a single polygon for the same date range, and the raw satellite data has not already been downloaded, each of those requests will be placed into the download queue, potentially slowing down the overall processing of all your requests.

image

That is where our Satellite Download endpoints come in! The satellite download endpoints allow for preparing your analysis requests, by already downloading the raw satellite data in advance. So that when you request your analysis, it will not require any further checks or downloads for satellite data, but instead will already be available and process analysis quickly. It also allows you to get further insights on the satellite data such as available, cloudy, unavailable, and unknown dates.

Downloading Satellite Data

You can use processSatelliteDownload() mutation to download the raw satellite data in advance of submitting your analysis requests such as plant health or water stress. Just make sure the processSatelliteDownload() request is completed before submitting analysis requests for the same date range, otherwise, those requests may end up in the download processing queue afterall. You can fetch the status of ongoing requests, through our request details endpoints. For more information on monitoring requests, please refer to our monitoring documentation.

The feedback provided from your processSatelliteDownload() requests only relates to the status of that single request and provides no insight into the availability of raw satellite data for that request itself. The processSatelliteDownload() endpoint may return a False status stating no dates were available for download. This means that all the available raw satellite data has already been checked and downloaded for the requested date range, but this does not guarantee any satellite data, it means no further checking for the time range is needed. To obtain information if any images were actually available and downloaded, you can use the retrieveSatelliteDownload() endpoint described in the next section.

Classifications

A satellite data image for a given day, can be marked in four different classifications:

  1. Available: a satellite image is available for that day and has been downloaded.
  2. Cloud Detected: a satellite image is available for that day, but is covered with clouds and is therefore not usable for analysis.
  3. Unavailable: a satellite image is unavailable for that day, a satellite has not flown over the field.
  4. Unknown: a satellite image for that day has not been requested, therefore we do not know any further details on the availability of that day. To obtain information on the availability, a request for downloading has to be made.

Usage

The processSatelliteDownload() mutation is used to download satellite data. The endpoint requires four arguments:

  • polygonId: The polygonId is the unique ID generated when you register/create a polygon in the API. You use this unique identifier to specify the plot you want to analyse.
  • startDate: This date specifies the start of the date range that you want to process.
  • endDate: This date specifies the end of the date range that you want to process.
  • satelliteDataType: The satelliteDateType parameter tells the API to download a specific type of satellite data. Most of the analyses that Vultus offers use Optical satellite data, however services like Soil Moisture use Radar data.

The endpoint only returns the status of the request itself, with the requestId. The request can be tracked using the requestId using the retrieveRequestDetails() endpoint. For more information on monitoring requests, please refer to our monitoring documentation.

Example

mutation {
  processSatelliteDownload(
    polygonId:         "PolygonId"
    startDate:         "2024-01-01"
    endDate:           "2024-05-01"
    satelliteDataType: "Optical"
  )
  {
    IsSuccess
    Message
    Status
    Result {
      requestId
    }
  }
}

Retrieving Satellite Data Information

You can use retrieveSatelliteDownload() query to validate the results of the processSatelliteDownload() mutations. The feedback from this query accurately describes the availability of raw satellite data for a given date range. This information can then further be used to send requests for analysis, if that data was available.

Usage

The retrieveSatelliteDownload() query is used to retrieve information on the availability of satellite data. The endpoint requires the same four arguments as the processSatelliteDownload endpoint:

  • polygonId: The polygonId is the unique ID generated when you register/create a polygon in the API. You use this unique identifier to specify the plot you want to analyse.
  • startDate: This date specifies the start of the date range that you want to process.
  • endDate: This date specifies the end of the date range that you want to process.
  • satelliteDataType: The satelliteDateType parameter tells the API to download a specific type of satellite data. Most of the analyses that Vultus offers use Optical satellite data, however services like Soil Moisture use Radar data.

The retrieveSatelliteDownload() query returns the following information:

  • Amount of dates for the four different types of classifications: available, cloud detected, unavailable, and unknown.
  • Lists of dates for the four different types of classifications: available, cloud detected, unavailable, and unknown.
  • The frequencies for the three different types of result classifications: available, cloud detected, and unavailable.

Example

query {
  retrieveSatelliteDownload(
    polygonId:         "PolygonId"
    startDate:         "2024-01-01"
    endDate:           "2024-05-01"
    satelliteDataType: "Optical"
  )
  {
    IsSuccess
    Message
    Status
    Result {
      amountOfAvailableDates
      amountOfCloudDectedDates
      amountOfUnavailableDates
      amountOfUnknownDates
      availableDates
      cloudDetectedDates
      unavailableDates
      unknownDates
      frequencyAvailableDates
      frequencyCloudDetectedDates
      frequencySatelliteImages
    }
  }
}