CEOS COVE Help: API User's Guide: Acquisition Forecaster

Help: COVE API User's Guide: Acquisition Forecaster

Acquisition Forecaster is tool that provides users with the ability to predict when a satellite has the ability to image a region of interest. Users may send requests for a task history, submit a new task, get a task status, retrieve a CSV with scene metadata, and retrieve a PNG map image of the task results.

Acquisition Forecaster throttle limits:

POST: 15 requests per hour
GET: 120 requests per hour

Retrieve task history

Lists all Acquisition Forecaster tasks in COVE for the user. The results include task ids which will allow users to retrieve results for existing tasks.

Request Method: GET

Request URL:
https://ceos-cove.org/en/api/v1_2/acquisition_forecaster/

URL Parameters: None

Response Example:

[

{

"task_id": "<TASK ID>",

"missions": [

{

"mission": "Sentinel-1A",

"instrument": "C-SAR",

"mode": "IWS"

}, {

"mission": "Sentinel-2A",

"instrument": "MSI",

"mode": ""

}

],

"custom_missions": [{

"mission": "MissionA",

"instrument": "BeamA"

}],

"start_date": "2019-01-01",

"end_date": "2019-01-08",

"region": "Ghana"

}

]

Submit a task

Task Input Parameters for Acquisition Forecaster:

Parameter Name	Data Type	Required	Description
start_date	DateString	Yes	Range: mission launch date to three months from the latest TLE date. Valid dates may be found by submitting a COVE API request for the forecasted missions list. Refer to Special Data Types for more information on DateString.
end_date	DateString	Yes	Range: mission launch date to three months from the latest TLE date. Valid dates may be found by submitting a COVE API request for the forecasted missions list. Refer to Special Data Types for more information on DateString.
region_folder	String	Yes	Valid folder names may be found by requesting the regions list.
region	String	Yes	Valid region names may be found by submitting a COVE API request for the regions list.
custom_missions	CustomMissionsFilter [ ]	No	Available custom missions may be found by submitting a COVE API request for the Custom Missions list. Refer to Special Data Types for more information on CustomMissionsFilter.
missions	MissionsFilter [ ]	No	Valid missions may be found by submitting a COVE API request for the forecasted missions list. Refer to Special Data Types for more information on MissionsFilter.
calculate_solor_angles	Boolean	No	If true, solar elevation, solar azimuth, and solar zenith will be calculated for each forecasted scene. If false, some forecasted scenes may have solar angles calculated if the scenes were cached by COVE in another task.

Request Data Example::

{

"start_date": "2020-01-01",

"end_date": "2020-01-31",

"region_folder": "Africa",

"region": "Kenya",

"custom_missions": [{

"mission": "MissionA",

"instrument": "BeamA"

}],

"missions": [{

"mission": "Sentinel-1A",

"instrument": "C-SAR",

"mode": "IWS"

}]

}

Request Method: POST

Request URL:


            https://ceos-cove.org/en/api/v1_2/acquisition_forecaster/

URL Parameters: None

Response Examples:

Example successful response from request where the results are not ready to retrieve:

{

"status": 202,

"message": "Acquisition Forecaster task as been submitted. Please wait for the results.",

"id": "<TASK ID>"

}

Example successful response from a request where the results are ready to retrieve:

{

"status": 200,

"message": "Acquisition Forecaster results are ready",

"id": "<TASK ID>"

}

Failed Response Examples:

{"status": 400, "message": "<Error Message>"}

{"status": 417, "message": "<Error Message>"}

Retrieve task status

Once a task has been submitted, users should periodically check the task status.

Status codes:

200: task has completed
202: task is still running
417: task has terminated in an error

If the status code is 200 and success is true, it indicates the task has predicted scenes.

If a status code 200 is received, users may send a request for CSV or PNG results.

Request Method: GET

Request URL:

https://ceos-cove.org/en/api/v1_2/acquisition_forecaster/<TASK ID>/

URL Parameters: None

Response Example:

{

"execution_start": "2020-09-16 18:19:19",

"execution_time": "00:01:34",

"start_date": "2017-01-01",

"end_date": "2017-01-08",

"modes": "MSI - Sentinel-2A,IWS - C-SAR - Sentinel-1A,BeamA – MissionA",

"region": "Ghana",

"complete": true,

"status": 200,

"message": "Task successfully completed.",

"success": true

}

Retrieve CSV file

The CSV file (binary) will contain the predicted scene metadata generated for the task. The CSV file contains the columns: mission, acquisition_time, tle_epoch, center_latitude, center_longitude, and orbit_direction. For extended, CSV file also contains the columns: sun_elevation, sun_zenith, sun_azimuth, and scene_coords.

Request Method: GET

Request URL:


            https://ceos-cove.org/en/api/v1_2/acquisition_forecaster/csv/<TASK ID>/

URL Parameters:

Parameter Name	Data Type	Required	Description
extended	Boolean	No	Values: true or false. If true, full extended CSV is returned. If false, abbreviated CSV is returned. Default value is false.

Failed Response Example:

{'status': 404, 'message': 'File not found.'}

Retrieve PNG results

The PNG image file is a map image which outlines scenes on a map of the requested region of interest within the start date and end date for the task.

Request Method: GET

Request URL:


            https://ceos-cove.org/en/api/v1_2/acquisition_forecaster/png/<TASK ID>/

URL Parameters:

Parameter Name	Data Type	Required	Description
orbit_direction	String	No	Values: ascending or descending. No value for orbit_direction will return results for both ascending and descending.
transparent	Boolean	No	Values: true or false. If transparent is true, the map background will be omitted and the background will instead be transparent. If transparent is false, image resolution is 200dpi.
resolution	Integer	No	Values should be in dots per inch (dpi). If transparent is false, resolution must be less than or equal to the default resolution. Default resolution is 200dpi.
line_width	Float	No	Values should be greater than 0. Allows users to define the line width of scene footprint outlines. This parameter does not apply to region outlines. Default value is 0.5.
show_region_outline	Boolean	No	Values: true or false. Allows users to show or hide the region outline.
map_coordinates	Boolean	No	Values: true or false. Allows users to fetch the map coordinates used to generate a PNG image. If value is true, the map coordinates will be returned instead of a PNG image. If an orbit_direction parameter is used to generate an image, it should be included in requests for map coordinates.
map_legend	Boolean	No	Values: true or false. Allows users to fetch the map legend used to generate a PNG image. If value is true, the map legend will be returned instead of a PNG image.

Map Coordinates Response Example:

{

"status": 200,

"map_coordinates": [

[-8.661654877310252, -0.16135473389262667],

[-8.661654877310252, 14.838645266107374],

[6.3383451226897485, 14.838645266107374],

[6.3383451226897485, -0.16135473389262667],

[-8.661654877310252, -0.16135473389262667]

]

}

Map Legend Response Example:

{

"status": 200,

"map_legend": {

"ALOS-2 – PALSAR-2 – Full Accessible": "#fc8d59"

}

Failed Response Example:

{'status': 404, 'message': 'File not found.'}

Example API requests using curl

Request user history:


            curl -H "Accept: application/json; indent=4" -u
            username:password https://ceos-cove.org/en/api/acquisition_forecaster/

Request for Acquisition Forecaster task:


            curl -H "Content-Type: application/json" -X POST -u username:password -d
            '{"start_date": "2017-01-01", "end_date": "2017-01-08", "region_folder": "Africa",
            "region": "Ghana", "custom_missions": [{"mission": "MissionA", "instrument": "InstA"}],
            "missions": [{"mission": "Sentinel-1A", "instrument": "C-SAR", "mode": "IWS"},
            {"mission": "Sentinel-2A", "instrument": "MSI"}]}'
            https://ceos-cove.org/en/api/acquisition_forecaster/

Request task status:


            curl -H "Accept: application/json; indent=4" -u username:password
            https://ceos-cove.org/en/api/acquisition_forecaster/<TASK ID>/

Request CSV results:


            curl -u username:password
            https://ceos-cove.org/en/api/acquisition_forecaster/csv/<TASK ID>/
            -o filename.csv

Request CSV results (extended):


            curl -u username:password
            https://ceos-cove.org/en/api/acquisition_forecaster/csv/<TASK
            ID>/?extended=true -o filename.csv

Request PNG map image (orbit direction: all):


            curl -u username:password
            https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK ID>/
            -o filename.png

Request PNG map image (orbit direction: ascending):


            curl -u username:password
            https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK
            ID>/?orbit_direction=ascending -o filename.png

Request PNG map image (orbit direction: descending):


            curl -u username:password
            https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK
            ID>/?orbit_direction=descending -o filename.png

Request PNG map image (transparent):


            curl -u username:password https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK
            ID>/?transparent=true -o filename.png

Request PNG map image (resolution):


            curl -u username:password
            https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK ID>/?resolution=200
            -o filename.png

Request PNG map image (line_width):


            curl -u username:password
            https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK ID>/?line_width=0.5
            -o filename.png

Request PNG map image (show_region_outline):


            curl -u username:password
            https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK
            ID>/?show_region_outline=false -o filename.png

Request PNG map image (map_coordinates):


            curl -u username:password https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK
            ID>/?map_coordinates=true -o filename.png

Request PNG map image (map_coordinates with orbit_direction):


            curl -u username:password https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK
            ID>/?map_coordinates=true&orbit_direction=ascending -o filename.png

Request PNG map image (map_legend):


            curl -u username:password https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK
            ID>/?map_legend=true -o filename.png

Request PNG map image (map_legend with orbit_direction):


            curl -u username:password https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK
            ID>/?map_legend=true&orbit_direction=ascending -o filename.png

Request PNG map image (map_coordinates with map_legend):


            curl -u username:password https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK
            ID>/?map_coordinates=true&map_legend=true -o filename.png

Request PNG map image (map_coordinates with map_legend and orbit_direction):


            curl -u username:password https://ceos-cove.org/en/api/acquisition_forecaster/png/<TASK
            ID>/?map_coordinates=true&map_legend=true&orbit_direction=ascending -o filename.png

<< Back to Help: API User's Guide