Coverage Analyzer is a tool that provides users with the ability to analyze the historical satellite coverage of 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, retrieve a PNG map image of the task results, retrieve a GeoTiff file, and retrieve a NetCDF file.
Lists all Coverage Analyzer 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/coverage_analyzer/
URL Parameters: None
[
{
"task_id": "<TASK ID>",
"missions": [
{
"mission": "Sentinel-2A",
"instrument": "MSI",
"mode": ""
}
],
"start_date": "2019-01-01",
"end_date": "2019-01-08",
"region": "Ghana"
"filter_options": {}
},
]
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 submitting a COVE API request for the regions list. |
region | String | Yes | Valid region names may be found by submitting a COVE API request for the regions list. |
missions | MissionsFilter [ ] | Yes |
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.
|
discretization | DiscretizationFilter | Yes | Refer to the Special Data Types for more information on DiscretizationFilter. |
filters | MetadataFilter | No | Refer to the Special Data Types for more information on MetadataFilter. |
{
"start_date": "2020-01-01",
"end_date": "2020-01-31",
"region_folder": "South America",
"region": "Argentina",
"missions": [{
"mission": "Sentinel-1A",
"instrument": "C-SAR",
"mode": "IWS"
}],
"discretization": {
"type": "",
"size": 1.0,
"unit": "deg",
"include_overlap": false
},
"filters": {
"cloud_cover": null,
"day_night": "",
"orbit_direction": "",
"processing_level": ""
}
}
POST
https://ceos-cove.org/en/api/v1_2/coverage_analyzer/
None
{
"status": 202,
"
message": "Coverage Analyzer task as been submitted. Please wait for
the results.",
"id": "<TASK ID>"
}
{
"status": 200,
"message": "Coverage Analyzer results are ready",
"id": "<TASK ID>"
}
{"status": 400, "message": "<Error Message>"}
{"status": 417, "message": "<Error Message>"}
GET
https://ceos-cove.org/en/api/v1_2/coverage_analyzer/<TASK ID>/
None
{
"execution_start": "2020-09-18 11:56:42",
"execution_time": "00:01:02",
"start_date": "2019-01-01",
"end_date": "2019-01-08",
"modes": "IWS - C-SAR – Sentinel-1A",
"region": "Africa: Ghana",
"discretization": "0.5 deg",
"filter_options": {},
"complete": true,
"status": 200,
"message": "Task successfully completed.",
"success": true
}
The JSON results will contain a list of coordinates for each discretized block in the region of interest. In each discretized block, it will show a title, and count of scenes in the block.
GET
https://ceos-cove.org/en/api/v1_2/coverage_analyzer/json/<TASK ID>/
{
"0.0,5.0,0.0,6.0,1.0,6.0,1.0,5.0,0.0,5.0": {
"title": "Region Discretization Longitude 0.0, Latitude 5.0",
"acquisition_count": 2
},
(JSON RESULTS TRUNCATED)
}
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, center_longitude, path, row, day_or_night, cloud_cover, sensor, sun_elevation, sun_azimuth, and scene_coords.
GET
https://ceos-cove.org/en/api/v1_2/coverage_analyzer/csv/<TASK ID>/
{'status': 404, 'message': 'File not found.'}
The PNG image file shows the discretized region of interest on a map where the color of each block in the discretized region reflects the number of scenes intersecting the block for the start date and end date and for the missions requested in the task.
GET
https://ceos-cove.org/en/api/v1_2/coverage_analyzer/png/<TASK ID>/
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.
|
transparency | Float | No |
Values should be between 0 and 1.
Transparency defines the opacity of the coincidence results. Transparency
does not apply to the region outline.
Default transparency is 0.65.
|
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.
|
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_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.
The number range on the left side of the map legend represents the number
of scenes in the block.
|
{
"status": 200,
"map_coordinates": [
[-8.661654877310252, -0.16135473389262667],
[-8.661654877310252, 14.838645266107374],
[6.3383451226897485, 14.838645266107374],
[6.3383451226897485, -0.16135473389262667],
[-8.661654877310252, -0.16135473389262667]
]
}
{
"status": 200,
"map_legend": {
"0 - 0": "#d73027",
"1 - 1": "#f46d43",
"2 - 2": "#fdae61",
"3 - 3": "#fee08b",
"4 - 4": "#ffffbf",
"5 - 5": "#d9ef8b",
"6 - 6": "#a6d96a",
"7 - 7": "#66bd63",
"8 - 9": "#1a9850"
}
}
{'status': 404, 'message': 'File not found.'}
The file exported will be in GeoTIFF format (file extension .tif).
GET
https://ceos-cove.org/en/api/v1_2/coverage_analyzer/geotiff/<TASK ID>/
{'status': 404, 'message': 'File not found.'}
The file exported will be in NetCDF format (file extension .nc).
GET
https://ceos-cove.org/en/api/v1_2/coverage_analyzer/netcdf/<TASK ID>/
{'status': 404, 'message': 'File not found.'}
curl -H "Accept: application/json; indent=4" -u
username:password https://ceos-cove.org/en/api/coverage_analyzer/
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"}], "discretization": {"type": "",
"size": 1.0, "unit": "deg"}, "filters": {"cloud_cover": null, "day_night": "",
"orbit_direction": "", "processing_level": ""}}'
https://ceos-cove.org/en/api/coverage_analyzer/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/coverage_analyzer/<TASK ID>/
curl -u username:password https://ceos-cove.org/en/api/coverage_analyzer/json/<TASK
ID>/ -o filename.csv
curl -u username:password https://ceos-cove.org/en/api/coverage_analyzer/csv/<TASK
ID>/ -o filename.csv
curl -u username:password https://ceos-cove.org/en/api/coverage_analyzer/png/<TASK
ID>/ -o filename.png
curl -u username:password https://ceos-cove.org/en/api/coverage_analyzer/png/<TASK
ID>/?transparent=true -o filename.png
curl -u username:password https://ceos-cove.org/en/api/coverage_analyzer/png/<TASK
ID>/?transparency=0.65 -o filename.png
curl -u username:password https://ceos-cove.org/en/api/coverage_analyzer/png/<TASK
ID>/?resolution=200 -o filename.png
curl -u username:password https://ceos-cove.org/en/api/coverage_analyzer/png/<TASK
ID>/?show_region_outline=false -o filename.png
curl -u username:password https://ceos-cove.org/en/api/coverage_analyzer/png/<TASK
ID>/?map_coordinates=true -o filename.png
curl -u username:password https://ceos-cove.org/en/api/coverage_analyzer/png/<TASK
ID>/?map_legend=true -o filename.png
curl -u username:password https://ceos-cove.org/en/api/coverage_analyzer/png/<TASK
ID>/?map_coordinates=true&map_legend -o filename.png
curl -u username:password https://ceos-cove.org/en/api/coverage_analyzer/geotiff/<TASK
ID>/ -o filename.tif
curl -u username:password
https://ceos-cove.org/en/api/coverage_analyzer/netcdf/<TASK ID>/ -o filename.nc