Coincident Calculator is a tool which allows users to determine the coincidence of satellite instrument modes and/or custom constellations observing a location in the same day within a region of interest using historical (archived) or predicted (forecasted) scene data. Users may send requests for a task history, submit a new task, get a task status, retrieve JSON results, and retrieve a PNG map image of the task results.
Lists all forecasted Coincident 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/coincident_calculator/forecasted/
URL Parameters: None
[
{
"task_id": "<TASK ID>",
"missions": [
{
"mission": "Sentinel-1A",
"instrument": "C-SAR",
"mode": "IWS"
}, {
"mission": "Sentinel-2A",
"instrument": "MSI",
"mode": ""
}
],
"custom_missions": [],
"constellations": [],
"start_date": "2019-01-01",
"end_date": "2019-01-08",
"region": "Ghana",
"coincidence_seconds": 86400
},
]
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
forecasted 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
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. |
constellations | ConstellationsFilter [ ] | No |
Available constellations may be found by submitting a COVE API request for the
forecasted constellations
list.
Refer to
Special Data Types
for more information on ConstellationsFilter.
|
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. |
coincidence_days | Integer | No |
Range: 0 to 5, defaults to -1.
Do not use coincidence_days if coincidence_seconds is specified.
If neither coincidence_days or coincidence_seconds are specified,
defaults to coincidence_days=0.
|
coincidence_seconds | Integer | No |
Range: 0 to 432000, defaults to -1.
Do not use coincidence_seconds if coincidence_days is specified.
If neither coincidence_days or coincidence_seconds are specified,
defaults to coincidence_days=0.
|
{
"start_date": "2020-01-01",
"end_date": "2020-01-31",
"region_folder": "North America",
"region": "Canada",
"constellations": [],
"custom_missions": [],
"missions": [
{
"mission": "Sentinel-1A",
"instrument": "C-SAR",
"mode": "IWS"
}, {
"mission": "Sentinel-2A",
"instrument": "MSI",
"mode": ""
}
],
"discretization": {
"size": 1.0,
"unit": "deg"
},
"coincidence_seconds": 86400
}
POST
https://ceos-cove.org/en/api/v1_2/coincident_calculator/forecasted/
None
{
"status": 202,
"message": "Coincident Calculator task as been submitted. Please wait
for the results.",
"id": "<TASK ID>"
}
{
"status": 200,
"message": "Coincident Calculator results are ready",
"id": "<TASK ID>"
}
{"status": 400, "message": ""}
{"status": 417, "message": ""}
GET
https://ceos-cove.org/en/api/v1_2/coincident_calculator/forecasted/<TASK ID>/
None
{
"execution_start": "2020-09-14 12:38:34",
"execution_time": "00:00:04",
"start_date": "2019-01-01",
"end_date": "2019-01-08",
"modes": "IWS - C-SAR - Sentinel-1A, MSI – Sentinel-2A",
"constellations": "",
"region": "Ghana",
"discretization": "1.0 deg",
"coincidence_seconds": 86400,
"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, coincidence dates, scene (acquisition) metadata, coincidence count, coincidence (dates and count) where scenes are ascending, coincidence where scenes are descending.
GET
https://ceos-cove.org/en/api/v1_2/coincident_calculator/forecasted/json/<TASK ID>/
{
"0.0,8.0,0.0,9.0,1.0,9.0,1.0,8.0,0.0,8.0": {
"title": "Region Discretization Longitude 0.0, Latitude 8.0",
"coincidence": "2019-01-06",
"acquisitions": [
{
"name": "Landsat 8 - TIRS",
"acquisition_time": "2019-01-06 10:20:30",
"tle_epoch": "2019-01-06 02:58:25",
"db_insert_date": "2020-09-18",
"final_prediction": false,
"center_latitude": 10.27,
"center_longitude": -0.57,
"orbit_direction": "Descending",
"scene_coords": "0.6660363424876055,11.962612495110209,-1.014522933011194,12.203808739278776,-1.7926181561449557,8.578126402975682,-0.13054000602536892,8.339640664025538,0.6660363424876055,11.962612495110209"
},
{
"name": "CBERS-4 - MUXCam",
"acquisition_time": "2019-01-06 22:05:30",
"tle_epoch": "2019-01-06 22:03:25",
"final_prediction": false,
"db_insert_date": "2020-09-18",
"center_latitude": 7.42,
"center_longitude": -0.39,
"orbit_direction": "Ascending",
"scene_coords": "-0.5336858426123086,5.553900730294913,0.5330482808132545,5.710459991383701,-0.24584157033903395,9.280660729314569,-1.320750071368642,9.12287381737216,-0.5336858426123086,5.553900730294913"
}
],
"coincidence_asc": "",
"coincidence_desc": "",
"coincidence_count": 1,
"coincidence_asc_count": 0,
"coincidence_desc_count": 0
},
(JSON RESULTS TRUNCATED)
}
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 pairs of missions/custom missions/constellations intersecting the block within the start date and end date for the task.
GET
https://ceos-cove.org/en/api/v1_2/coincident_calculator/forecasted/png/<TASK ID>/
Parameter Name | Data Type | Required | Description |
---|---|---|---|
orbit_direction | String | No |
Values: ascending or descending.
No 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 coincidences 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",
"4 - 4": "#ffffbf",
"3 - 3": "#fee08b",
"5 - 5": "#d9ef8b",
"6 - 6": "#a6d96a",
"7 - 7": "#66bd63",
"8 - 9": "#1a9850"
}
}
{'status': 404, 'message': 'File not found.'}
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/
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", "constellations": [], "custom_missions": [],
"missions": [{"mission": "Sentinel-1A", "instrument": "C-SAR", "mode": "IWS"},
{"mission": "Sentinel-2A", "instrument": "MSI"}], "discretization":
{"size": 1.0, "unit": "deg"}, "coincidence_seconds": 86400}'
https://ceos-cove.org/en/api/coincident_calculator/forecasted/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/constellations/
curl -H "Content-Type: application/json" -X POST -u username:password
-d '{"name": "SatGroup - F", "custom_missions": [], "missions": [{"mission":
"Sentinel-1A", "instrument": "C-SAR", "mode": "IWS"},{"mission": "Sentinel-2A",
"instrument": "MSI"}]'
https://ceos-cove.org/en/api/coincident_calculator/forecasted/constellations/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/<TASK ID>/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/json/<TASK ID>/
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/png/<TASK ID>/
-o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/png/<TASK
ID>/?orbit_direction=ascending -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/png/<TASK
ID>/?orbit_direction=descending -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/png/<TASK
ID>/?transparent=true -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/png/<TASK
ID>/?transparency=0.65 -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/png/<TASK
ID>/?resolution=200 -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/png/<TASK
ID>/?show_region_outline=false -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/png/<TASK
ID>/?map_coordinates=true -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/png/<TASK
ID>/?map_legend=true -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/forecasted/png/<TASK
ID>/?map_coordinates=true&map_legend=true -o filename.png
Lists all archived Coincident 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/coincident_calculator/archived/
URL Parameters: None
[
{
"task_id": "<TASK ID>",
"missions": [
{
"mission": "Sentinel-1A",
"instrument": "C-SAR",
"mode": "IWS"
}, {
"mission": "Landsat 8",
"instrument": "OLI/TIRS",
"mode": ""
}
],
"constellations": [],
"start_date": "2019-01-01",
"end_date": "2019-01-08",
"region": "Ghana",
"coincidence_seconds": 86400
}
]
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. |
constellations | ConstellationsFilter [ ] | No |
Valid constellations may be found by submitting a COVE API request
for the
archived constellations
list.
Refer to
Special Data Types
for more information on ConstellationsFilter.
|
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 Special Data Types for more information on DiscretizationFilter. |
coincidence_days | Integer | No |
Range: 0 to 5, defaults to -1.
Do not use coincidence_days if coincidence_seconds is specified.
If neither coincidence_days or coincidence_seconds are specified,
defaults to coincidence_days=0.
|
coincidence_seconds | Integer | No |
Range: 0 to 432000, defaults to -1.
Do not use coincidence_seconds if coincidence_days is specified.
If neither coincidence_days or coincidence_seconds are specified,
defaults to coincidence_days=0.
|
{
"start_date": "2020-01-01",
"end_date": "2020-01-31",
"region_folder": "Oceania",
"region": "Australia",
"constellations": [],
"missions": [],
"discretization": {
"size": 1.0,
"unit": "deg"
},
"coincidence_seconds": 172800
}
POST
https://ceos-cove.org/en/api/v1_2/coincident_calculator/archived/
None
{
"status": 202,
"message": "Coincident Calculator task as been submitted. Please wait for the results.",
"id": "<TASK ID>"
}
{
"status": 200,
"message": "Coincident Calculator results are ready", "id": "<TASK ID>",
"id": "<TASK ID>"
}
{"status": 400, "message": "<Error Message>"}
{"status": 417, "message": "<Error Message>"}
GET
https://ceos-cove.org/en/api/v1_2/coincident_calculator/archived/<TASK ID>/
None
{
"execution_start": "2020-09-14 12:31:41",
"execution_time": "00:01:02",
"start_date": "2019-01-01",
"end_date": "2019-01-08",
"modes": "IWS - C-SAR - Sentinel-1A, MSI - Sentinel-2A, OLI/TIRS - Landsat 8",
"constellations": "",
"region": "Africa: Ghana",
"discretization": "5.0 deg",
"coincidence_seconds": 0,
"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, coincidence dates, scene (acquisition) metadata, coincidence count, coincidence (dates and count) where scenes are ascending, coincidence where scenes are descending.
GET
https://ceos-cove.org/en/api/v1_2/coincident_calculator/archived/json/<TASK ID>/
[
"-4.0,11.0,-4.0,12.0,-3.0,12.0,-3.0,11.0,-4.0,11.0": {
"title": "Region Discretization Longitude -4.0, Latitude 11.0",
"coincidence": "2019-01-03",
"acquisitions": [
{
"mission": "Sentinel-2A – MSI",
"name": "6718341",
"acquisition_date": "2019-01-03",
"browse_url": <BROWSE JPG URL>,
"order_url": <ORDER URL>,
"sun_azimuth": 150.134493948532,
"granule_name": "L1C_T30PVT_A018452_20190103T104928",
"sun_elevation": 39.3260813690852,
"scene_stop_time": "2019-01-03T11:00:14.693Z",
"cloud_cover_full": 0.0,
"scene_start_time": "2019-01-03T10:49:28.901Z",
"scene_center_latitude": 11.2632574,
"scene_center_longitude": -3.4135721,
"orbit_direction": "Descending",
"scene_coords": "-3.9181409,11.7585667,-2.9104213,11.76003,-2.910728,10.7670169,-3.914998,10.7656802,-3.9181409,11.7585667"
},
{
"mission": "Sentinel-1A - C-SAR – IWS",
"name": "S1A_IW_SLC__1SDV_20190103T182746_20190103T182813_025317_02CD19_622F",
"acquisition_date": "2019-01-03",
"browse_url": <BROWSE JPG URL>,
"order_url": <ORDER URL>,
"path": 45,
"frame": 32,
"orbit": 25317,
"scene_end_time": "2019-01-03T18:28:13.000000",
"center_latitude": 11.562,
"center_longitude": -3.8554,
"processing_level": "SLC",
"scene_start_time": "2019-01-03T18:27:46.000000",
"sending_polarization": "VV",
"receiving_polarization": "VH",
"orbit_direction": "Ascending",
"scene_coords": "-2.560575,10.969422,-4.81989,10.522881,-5.154573,12.152341,-2.8816349999999997,12.594698,-2.560575,10.969422"
}
],
"coincidence_asc": "",
"coincidence_desc": "",
"coincidence_count": 1,
"coincidence_asc_count": 0,
"coincidence_desc_count": 0
}
(JSON RESULTS TRUNCATED)
]
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 pairs of missions/constellations intersecting the block within the start date and end date for the task.
GET
https://ceos-cove.org/en/api/v1_2/coincident_calculator/archived/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 coincidences 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.'}
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/
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", "constellations": [], "missions": [{"mission":
"Sentinel-1A", "instrument": "C-SAR", "mode": "IWS"},{"mission":
"Sentinel-2A", "instrument": "MSI"}, {"mission": "Landsat 8",
"instrument": "OLI/TIRS"}], "discretization": {"size": 5.0, "unit":
"deg"}, "coincidence_seconds": 86400}'
https://ceos-cove.org/en/api/coincident_calculator/archived/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/constellations/
curl -H "Content-Type: application/json" -X POST -u username:password -d
'{"name": "SatGroup - A", "missions": [{"mission": "Sentinel-1A",
"instrument": "C-SAR", "mode": "IWS"},{"mission": "Sentinel-2A",
"instrument": "MSI"}]'
https://ceos-cove.org/en/api/coincident_calculator/archived/constellations/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/<TASK ID>/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/json/<TASK ID>/
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/png/<TASK ID>/
-o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/png/<TASK
ID>/?orbit_direction=ascending -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/png/<TASK
ID>/?orbit_direction=descending -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/png/<TASK
ID>/?transparent=true -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/png/<TASK
ID>/?transparency=0.65 -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/png/<TASK
ID>/?resolution=200 -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/png/<TASK
ID>/?show_region_outline=false -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/png/<TASK
ID>/?map_coordinates=true -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/png/<TASK
ID>/?map_legend=true -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/coincident_calculator/archived/png/<TASK
ID>/?map_coordinates=true&map_legend=true -o filename.png