Revisits Calculator is a tool which allows users to analyze estimated satellite coverage and revisits for a region of interest. Users may send requests for a task history, submit a new task, get a task status, retrieve JSON results, retrieve a CSV with scene metadata, and retrieve a PNG map image of the task results.
Lists all Revisits Calculator 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/revisits_calculator/
URL Parameters: None
[
{
"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"
}
]
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.
|
discretization | DiscretizationFilter | Yes | Refer to Special Data Types for more information on DiscretizationFilter. |
{
"start_date": "2020-01-01",
"end_date": "2020-01-31",
"region_folder": "Africa",
"region": "Botswana",
"custom_missions": [],
"missions": [{
"mission": "Sentinel-2A",
"instrument": "MSI",
"mode": ""
}],
"discretization": {
"type": "S2Tiling",
"size": null,
"unit": ""
}
}
POST
https://ceos-cove.org/en/api/v1_2/revisits_calculator/
None
{
"status": 202,
"message": "Revisits Calculator task as been submitted. Please wait for the results.",
"id": "<TASK ID>"
}
{
"status": 200,
"message": "Revisits Calculator 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/revisits_calculator/<TASK ID>/
None
{
"execution_start": "2020-09-17 22:27:20",
"execution_time": "00:00:07",
"start_date": "2019-01-02",
"end_date": "2019-01-03",
"modes": "IWS - C-SAR – Sentinel-1A",
"region": "Africa: Ghana",
"discretization": "1.0 deg",
"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, count of scenes in the block, mean time between revisits, median time between revisits, maximum time between revisits, and minimum time between revisits in the block for ascending orbit, descending orbit, or both.
GET
https://ceos-cove.org/en/api/v1_2/revisits_calculator/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",
"revisits": 2,
"minimum": "12:23:00",
"median": "12:23:00",
"mean": "12:23:00",
"maximum": "12:23:00",
"desc_revisits": 1,
"desc_minimum": "0:00:00",
"desc_median": "0:00:00",
"desc_mean": "0:00:00",
"desc_maximum": "0:00:00",
"count": 2,
"asc_revisits": 1,
"asc_minimum": "0:00:00",
"asc_median": "0:00:00",
"asc_mean": "0:00:00",
"asc_maximum": "0:00:00"
},
(JSON RESULTS TRUNCATED)
}
The CSV file (binary) will contain the scene metadata 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.
GET
https://ceos-cove.org/en/api/v1_2/revisits_calculator/csv/<TASK ID>/
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.
|
{'status': 400, 'message': '<Error Message>'}
{'status': 417, 'message': '<Error Message>'}
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 times missions/custom missions intersect the block within the start date and end date for the task.
GET
https://ceos-cove.org/en/api/v1_2/revisits_calculator/png/<TASK ID>/
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.
|
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 revisits 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 - 3": "#d73027",
"4 - 7": "#f46d43",
"8 - 11": "#fdae61",
"16 - 19": "#ffffbf",
"12 - 15": "#fee08b",
"20 - 23": "#d9ef8b",
"24 - 27": "#a6d96a",
"28 - 31": "#66bd63",
"32 - 36": "#1a9850"
}
}
{'status': 404, 'message': 'File not found.'}
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/revisits_calculator/
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", "custom_missions": [], "missions": [{"mission":
"Sentinel-1A", "instrument": "C-SAR", "mode": "IWS"}], "discretization":
{"type": "", "size": 1.0, "unit": "deg"}}'
https://ceos-cove.org/en/api/revisits_calculator/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/revisits_calculator/<TASK ID>/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/revisits_calculator/json/<TASK ID>/
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/csv/<TASK
ID>/ -o filename.csv
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/csv/<TASK
ID>/?extended=true -o filename.csv
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/png/<TASK
ID>/ -o filename.png
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/png/<TASK
ID>/?orbit_direction=ascending -o filename.png
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/png/<TASK
ID>/?orbit_direction=descending -o filename.png
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/png/<TASK
ID>/?transparent=true -o filename.png
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/png/<TASK
ID>/?transparency=0.65 -o filename.png
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/png/<TASK
ID>/?resolution=200 -o filename.png
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/png/<TASK
ID>/?show_region_outline=false -o filename.png
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/png/<TASK
ID>/?map_coordinates=true -o filename.png
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/png/<TASK
ID>/?map_legend=true -o filename.png
curl -u username:password https://ceos-cove.org/en/api/revisits_calculator/png/<TASK
ID>/?map_coordinates=true&map_legend=true -o filename.png