Help: COVE API User's Guide: Data Browser

Data Browser is a tool that allows users to view the satellite image archives from multiple CEOS missions. Users may send requests for a task history, submit a new task, get a task status, retrieve a scene count for the task, retrieve CSV results of scene metadata, and retrieve a PNG map image of the task results.

Data Browser throttle limits:
  • POST: 15 requests per hour
  • GET: 120 requests per hour
 

Retrieve task history

Lists all Data Browser 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/data_browser/

URL Parameters: None

Response Example:
[
{
"task_id": "<TASK ID>",
"missions": [
{
"mission": "Sentinel-1A",
"instrument": "C-SAR",
"mode": "IWS"
}, {
"mission": "Sentinel-2A",
"instrument": "MSI",
"mode": ""
}
],
"start_date": "2019-01-01",
"end_date": "2019-01-08",
"region": "Ghana",
"filter_options": {}
}
]
 

Submit a task

Task Input Parameters for Data Browser:
Parameter Name Data Type Required Description
start_date DateString Yes
Range: mission launch date to the latest acquisition date.
 
Valid dates may be found by submitting a COVE API request for the archived missions list.
 
Refer to Special Data Types for more information on DateString.
end_date DateString Yes
Range: mission launch date to the latest acquisition date.
 
Valid dates may be found by submitting a COVE API request for the archived 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.
missions MissionsFilter [ ] No
Valid missions may be found by submitting a COVE API request for the archived missions list.
 
Refer to Special Data Types for more information on MissionsFilter.
filters MetadataFilter No Refer to Special Data Types for more information on MetadataFilter.
 
Request Data Example::
{
"start_date": "2020-01-01",
"end_date": "2020-01-31",
"region_folder": "Europe",
"region": "Spain",
"missions": [{
"mission": "Sentinel-1A",
"instrument": "C-SAR",
"mode": "IWS"
}],
"filters": {
"cloud_cover": null,
"day_night": "",
"orbit_direction": "",
"processing_level": ""
}
}
 
Request Method: POST
 
Request URL:
https://ceos-cove.org/en/api/v1_2/data_browser/
 
URL Parameters: None
 
Response Examples:
Example successful response from request where the results are not ready to retrieve:
{
"status": 202,
"message": "Data Browser 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": "Data Browser 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 scene count, CSV, or PNG results.
 
Request Method: GET
 
Request URL:
https://ceos-cove.org/en/api/v1_2/data_browser/<TASK ID>/
 
URL Parameters: None
 
Response Example:
{
"execution_start": "2020-09-14 12:31:41",
"execution_time": "02:38:58",
"start_date": "2019-01-01",
"end_date": "2019-01-08",
"modes": "OLI/TIRS - Landsat 8,IWS - C-SAR - Sentinel-1A,MSI – Sentinel-2A",
"region": "Ghana",
"filter_options": {},
"complete": true,
"status": 200,
"message": "Task successfully completed.",
"success": true
}
 

Retrieve scene count

Returns the number of scenes in the task results.
 
Request Method: GET
 
Request URL:
https://ceos-cove.org/en/api/v1_2/data_browser/count/<TASK ID>/
 
URL Parameters: None
 
Response Example:
{
"status": 200,
"count": 130
}
 

Retrieve CSV results

The CSV file (binary) will contain the scene metadata for the task. The CSV file contains the columns: mission, name, acquisition_date, browse_url, order_url, start_time, stop_time, center_latitude, and center_longitude. For extended CSV file also contains columns: path, row, day_or_night, cloud_cover, sensor, sun_elevation, sun_azimuth, and scene_coords.

Request Method: GET
 
Request URL:
https://ceos-cove.org/en/api/v1_2/data_browser/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/data_browser/png/<TASK ID>/
 
URL Parameters:
Parameter Name Data Type Required Description
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.
 
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]
]
}
 
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/data_browser/
 
Request for Data Browser task:
curl -H "Content-Type: application/json" -X POST -u username:password -d '{"start_date": "2019-01-01", "end_date": "2019-01-08", "region_folder": "Africa", "region": "Ghana", "missions": [{"mission": "Sentinel-1A", "instrument": "C-SAR", "mode": "IWS"}], "filters": {"cloud_cover": null, "day_night": "", "orbit_direction": "asc", "processing_level": ""}}' https://ceos-cove.org/en/api/data_browser/
 
Request task status:
curl -H "Accept: application/json; indent=4" -u username:password https://ceos-cove.org/en/api/data_browser/<TASK ID>/
 
Request scene count:
curl -H "Accept: application/json; indent=4" -u username:password https://ceos-cove.org/en/api/data_browser/count/<TASK ID>/
 
Request CSV File:
curl -u username:password https://ceos-cove.org/en/api/data_browser/csv/<TASK ID>/ -o filename.csv
 
Request CSV File (extended):
curl -u username:password https://ceos-cove.org/en/api/data_browser/csv/<TASK ID>/?extended=true -o filename.csv
 
Request PNG map image:
curl -u username:password https://ceos-cove.org/en/api/data_browser/png/<TASK ID>/ -o filename.png
 
Request PNG map image (transparent):
curl -u username:password https://ceos-cove.org/en/api/data_browser/png/<TASK ID>/?transparent=true -o filename.png
 
Request PNG map image (resolution):
curl -u username:password https://ceos-cove.org/en/api/data_browser/png/<TASK ID>/?resolution=200 -o filename.png
 
Request PNG map image (line_width):
curl -u username:password https://ceos-cove.org/en/api/data_browser/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/data_browser/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/data_browser/png/<TASK ID>/?map_coordinates=true -o filename.png