Country Coverage is a tool that allows users to generate and view GFOI Country Coverage reports for over 70 countries and 3 constellations. Users may send requests for a constellations list, a countries list, a daily history, submit a new task, get a task status, retrieve JSON results, retrieve PDF results, retrieve CSV results of scene metadata, retrieve a PNG bar graph, and retrieve ZIP archive file of the reports from the task results. Users must submit a new task to retrieve monthly cached report as well as to initiate report tasks.
Lists all constellations and the missions associated with each constellation. These constellations are only applicable to the Country Coverage tool and API.
Request Method: GET
Request URL:
https://ceos-cove.org/en/api/v1_2/country_coverage/constellations/
URL Parameters: None
{
"constellations": {
"Landsat": [
"Landsat 5 - TM",
"Landsat 7 - ETM",
"Landsat 8 - OLI/TIRS"
],
"Sentinel-1": [
"Sentinel-1A - C-SAR - EW",
"Sentinel-1A - C-SAR - IWS",
"Sentinel-1A - C-SAR - SM",
"Sentinel-1A - C-SAR - WV",
"Sentinel-1B - C-SAR - EW",
"Sentinel-1B - C-SAR - IWS",
"Sentinel-1B - C-SAR - SM",
"Sentinel-1B - C-SAR - WV"
],
"Sentinel-2": [
"Sentinel-2A - MSI",
"Sentinel-2B - MSI"
]
}
}
Lists over 70 countries available for generating Country Coverage reports in COVE.
Request Method: GET
Request URL:
https://ceos-cove.org/en/api/v1_2/country_coverage/countries/
URL Parameters: None
{
"countries": [
"Algeria",
"Argentina",
"Australia",
"Bangladesh",
"Belize",
(COUNTRIES LIST TRUNCATED)
]
}
Lists all existing and generating Country Coverage reports in COVE for the current day.
Request Method: GET
Request URL:
https://ceos-cove.org/en/api/v1_2/country_coverage/reports/
URL Parameters: None
{
"existing": {
"Algeria": [
"Landsat",
"Sentinel-1",
"Sentinel-2"
],
"Argentina": [
"Landsat",
"Sentinel-1"
],
"Australia": [
"Landsat"
]
},
"generating": {
"Argentina": [
"Sentinel-2",
],
"Australia": [
"Sentinel-1",
"Sentinel-2",
]
}
}
Lists all cached Country Coverage reports available in COVE. Reports are generated on the first day of each month and include the period of the start of the mission through the current month minus two months. For example, on January 1st reports will be generated for the period through November 30th.
Request Method: GET
Request URL:
https://ceos-cove.org/en/api/v1_2/country_coverage/reports/?daily_task=false
URL Parameters: None
{
"existing": {
"Algeria": [
"Landsat",
"Sentinel-1",
"Sentinel-2"
],
"Argentina": [
"Landsat",
"Sentinel-1",
"Sentinel-2"
],
"Australia": [
"Landsat",
"Sentinel-1",
"Sentinel-2"
],
(HISTORY TRUNCATED)
}
}
Country Coverage tasks have a size limit. The limit is the number of constellations times the number of countries requested in the task.
Parameter Name | Data Type | Required | Description |
---|---|---|---|
constellations | ConstellationsFilter [ ] | Yes |
Refer to
Retrieve constellations list
for a list of valid constellations.
Refer to
Special Data Types
for more information on ConstellationsFilter.
|
countries | CountriesFilter [ ] | Yes |
Refer to
Retrieve countries list
for a list of valid countries.
Refer to
Special Data Types
for more information on CountriesFilter.
|
daily_task | Boolean | No |
Default value is true.
If value is true, reports will be generated based on current data.
If value is false, resulting task id may be used to retrieve monthly
cached reports.
|
{
"constellations": [
"Landsat",
"Sentinel-1",
"Sentinel-2"
],
"countries": [
"Algeria",
"Argentina",
"Australia",
"Bangladesh",
"Belize"
],
"daily_task": true
}
POST
https://ceos-cove.org/en/api/v1_2/country_coverage/reports/
None
{
"status": 202,
"message": "Country Coverage reports task as been submitted. Please wait for the results.",
"id": "<TASK ID>"
}
{
"status": 200,
"message": "Country Coverage reports results are ready",
"id": "<TASK ID>"
}
{"status": 400, "message": "<Error Message>"}
{"status": 417, "message": "<Error Message>"}
{"status": 429, "message": "Another country coverage task is currently running. Please try again later,"}
GET
https://ceos-cove.org/en/api/v1_2/country_coverage/reports/<TASK ID>/
None
{
"execution_start": "2020-09-18 14:11:21",
"execution_time": "03:05:07",
"constellations": "Landsat",
"countries": "Benin",
"complete": true,
"status": 200,
"message": "Your task has completed successfully.",
"progress": 85,
"completed": {
"Benin": [
"Landsat"
]
}
}
The JSON results will contain scene counts for every year since mission launch for all missions in all constellations and all countries in a task request. If a URL parameter is included in the request URL, the results will be filtered by the parameter(s) provided.
GET
https://ceos-cove.org/en/api/v1_2/country_coverage/reports/json/<TASK ID>/
Parameter Name | Data Type | Required | Description |
---|---|---|---|
constellation | String | No | Refer to Retrieve constellations list for a valid list of constellations. |
country | String | No | Refer to Retrieve countries list for a valid list of countries. |
{
"Sentinel-1": {
"Benin": [
{
"year": 2014,
"Sentinel-1A": 0,
"Sentinel-1B": 0
},
{
"year": 2015,
"Sentinel-1A": 442,
"Sentinel-1B": 0
},
{
"year": 2016,
"Sentinel-1A": 575,
"Sentinel-1B": 0
},
(RESULTS TRUNCATED)
]
}
}
The PDF file will contain a chart with the totals of scenes for the country and mission in the constellation requested for each year since launch. It will also contain a bar graph of the totals for each year. Reports for Sentinel-1 include an additional bar graph where values are separated by processing level. If the task associated with the task id only requests one constellation and one country, no URL parameters are needed.
GET
https://ceos-cove.org/en/api/v1_2/country_coverage/reports/pdf/<TASK ID>/
Parameter Name | Data Type | Required | Description |
---|---|---|---|
constellation | String | No |
The constellation parameter is only required if multiple constellations
are associated with the task.
Refer to
Retrieve constellations list
for a valid list of constellations.
|
country | String | No |
The country parameter is only required if multiple countries are
associated with the task.
Refer to
Retrieve countries list
for a valid list of countries.
|
{'status': 404, 'message': 'File not found.'}
GET
https://ceos-cove.org/en/api/v1_2/country_coverage/reports/csv/<TASK ID>/
Parameter Name | Data Type | Required | Description |
---|---|---|---|
constellation | String | No |
The constellation parameter is only required if multiple constellations
are associated with the task.
Refer to
Retrieve constellations list
for a valid list of constellations.
|
country | String | No |
The country parameter is only required if multiple countries are
associated with the task.
Refer to
Retrieve countries list
for a valid list of countries.
|
{'status': 404, 'message': 'File not found.'}
The PNG image file is a bar graph which shows the number of scenes for each year for each mission for the country and constellation parameter specified in the request. If the task associated with the task id only requests one constellation and one country, no URL parameters are needed.
GET
https://ceos-cove.org/en/api/v1_2/country_coverage/reports/png/<TASK ID>/
Parameter Name | Data Type | Required | Description |
---|---|---|---|
constellation | String | No |
The constellation parameter is only required if multiple constellations
are associated with the task.
Refer to
Retrieve constellations list
for a valid list of constellations.
|
country | String | No |
The country parameter is only required if multiple countries are
associated with the task.
Refer to
Retrieve countries list
for a valid list of countries.
|
{'status': 404, 'message': 'File not found.'}
The ZIP archive file will contain all PDF and CSV files for all constellations and countries in the task request.
GET
https://ceos-cove.org/en/api/v1_2/country_coverage/reports/zip/<TASK ID>/
{'status': 404, 'message': 'File not found.'}
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/country_coverage/constellations/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/country_coverage/countries/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/country_coverage/reports/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/country_coverage/reports/?daily_task=false
curl -H "Content-Type: application/json" -X POST -u username:password -d
'{"constellations": [<CONSTELLATION>], "countries": [<COUNTRY>],
daily_task=true}'
https://ceos-cove.org/en/api/country_coverage/reports/
curl -H "Content-Type: application/json" -X POST -u username:password -d
'{"constellations": [<CONSTELLATION>], "countries": [<COUNTRY>],
daily_task=false}'
https://ceos-cove.org/en/api/country_coverage/reports/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/country_coverage/reports/<TASK ID>/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/country_coverage/reports/json/<TASK ID>/
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/country_coverage/reports/json/<TASK
ID>/?country=<COUNTRY>
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/country_coverage/reports/json/<TASK
ID>/?constellation=<CONSTELLATION>
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/country_coverage/reports/json/<TASK
ID>/?country=<COUNTRY>&constellation=<CONSTELLATION>
curl -u username:password
https://ceos-cove.org/en/api/dcountry_coverage/reports/csv/<TASK
ID>/?country=<COUNTRY>&constellation=<CONSTELLATION> -o filename.pdf
curl -u username:password
https://ceos-cove.org/en/api/country_coverage/reports/csv/<TASK
ID>/?country=<COUNTRY>&constellation=<CONSTELLATION> -o filename.csv
curl -u username:password
https://ceos-cove.org/en/api/country_coverage/reports/png/<TASK
ID>/?country=<COUNTRY>&constellation=<CONSTELLATION> -o filename.png
curl -u username:password
https://ceos-cove.org/en/api/country_coverage/reports/zip/<TASK
ID>/ -o filename.zip