CEOS COVE Help: API User's Guide: Country Coverage

Help: COVE API User's Guide: Country Coverage

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.

Revisits Calculator throttle limits:

POST: 1 Country Coverage task running in COVE at a time
GET: 120 requests per hour

Retrieve constellations list

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

Response Example:

{

"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"

]

}

Retrieve countries list

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

Response Example:

{

"countries": [

"Algeria",

"Argentina",

"Australia",

"Bangladesh",

"Belize",

(COUNTRIES LIST TRUNCATED)

]

}

Retrieve daily history

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

Response Example:

{

"existing": {

"Algeria": [

"Landsat",

"Sentinel-1",

"Sentinel-2"

],

"Argentina": [

"Landsat",

"Sentinel-1"

],

"Australia": [

"Landsat"

]

},

"generating": {

"Argentina": [

"Sentinel-2",

],

"Australia": [

"Sentinel-1",

"Sentinel-2",

]

}

Retrieve monthly cached history

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

Response Example:

{

"existing": {

"Algeria": [

"Landsat",

"Sentinel-1",

"Sentinel-2"

],

"Argentina": [

"Landsat",

"Sentinel-1",

"Sentinel-2"

],

"Australia": [

"Landsat",

"Sentinel-1",

"Sentinel-2"

],

(HISTORY TRUNCATED)

}

Submit a task

Country Coverage tasks have a size limit. The limit is the number of constellations times the number of countries requested in the task.

Task Input Parameters for Country Coverage:

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.

Request Data Example::

{

"constellations": [

"Landsat",

"Sentinel-1",

"Sentinel-2"

],

"countries": [

"Algeria",

"Argentina",

"Australia",

"Bangladesh",

"Belize"

],

"daily_task": true

}

Request Method: POST

Request URL:


            https://ceos-cove.org/en/api/v1_2/country_coverage/reports/

URL Parameters: None

Response Examples:

Example successful response from request where the results are not ready to retrieve:

{

"status": 202,

"message": "Country Coverage reports 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": "Country Coverage reports results are ready",

"id": "<TASK ID>"

}

Failed Response Examples:

{"status": 400, "message": "<Error Message>"}

{"status": 417, "message": "<Error Message>"}

{"status": 429, "message": "Another country coverage task is currently running. Please try again later,"}

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 JSON, PDF, CSV, PNG, or ZIP results.

Request Method: GET

Request URL:

https://ceos-cove.org/en/api/v1_2/country_coverage/reports/<TASK ID>/

URL Parameters: None

Response Example:

{

"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"

]

}

Retrieve JSON results

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.

Request Method: GET

Request URL:


            https://ceos-cove.org/en/api/v1_2/country_coverage/reports/json/<TASK ID>/

URL Parameters:

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.

Response Example:

{

"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)

]

}

Retrieve PDF results

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.

Request Method: GET

Request URL:


            https://ceos-cove.org/en/api/v1_2/country_coverage/reports/pdf/<TASK ID>/

URL Parameters:

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.

Failed Response Example:

{'status': 404, 'message': 'File not found.'}

Retrieve CSV results

The CSV file (binary) will contain the scene metadata. The CSV file contains the columns:

Landsat:

Date Acquired, Year, Mission, Path, Row, Scene Cloud Cover, Processing Level, Tier, Product ID, Scene ID
Sentinel-1:

Date Acquired, Year, Mission, Path, Frame, Processing Level, Orbit Direction, Granule Name
Sentinel-2:

Date Acquired, Year, Mission, Scene Center Latitude, Scene Center Longitude, Scene Cloud Cover, Scene ID

Request Method: GET

Request URL:


              https://ceos-cove.org/en/api/v1_2/country_coverage/reports/csv/<TASK ID>/

URL Parameters:

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.

Failed Response Example:

{'status': 404, 'message': 'File not found.'}

Retrieve PNG results

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.

Request Method: GET

Request URL:


            https://ceos-cove.org/en/api/v1_2/country_coverage/reports/png/<TASK ID>/

URL Parameters:

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.

Failed Response Example:

{'status': 404, 'message': 'File not found.'}

Retrieve ZIP results

The ZIP archive file will contain all PDF and CSV files for all constellations and countries in the task request.

Request Method: GET

Request URL:


            https://ceos-cove.org/en/api/v1_2/country_coverage/reports/zip/<TASK ID>/

URL Parameters: None

Failed Response Example:

{'status': 404, 'message': 'File not found.'}

Example API requests using curl

Request Constellations List:


            curl -H "Accept: application/json; indent=4" -u username:password
            https://ceos-cove.org/en/api/country_coverage/constellations/

Request Countries List:


            curl -H "Accept: application/json; indent=4" -u username:password
            https://ceos-cove.org/en/api/country_coverage/countries/

Request Country Coverage daily history:


            curl -H "Accept: application/json; indent=4" -u username:password
            https://ceos-cove.org/en/api/country_coverage/reports/

Request Country Coverage monthly cached history:


            curl -H "Accept: application/json; indent=4" -u username:password
            https://ceos-cove.org/en/api/country_coverage/reports/?daily_task=false

Request for Country Coverage daily reports task:


            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/

Request for Country Coverage monthly cached reports task:


              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/

Request task status:


              curl -H "Accept: application/json; indent=4" -u username:password
              https://ceos-cove.org/en/api/country_coverage/reports/<TASK ID>/

Request JSON results for all countries and constellations in task:


              curl -H "Accept: application/json; indent=4" -u username:password
              https://ceos-cove.org/en/api/country_coverage/reports/json/<TASK ID>/

Request JSON results for all constellations for a country in task:


              curl -H "Accept: application/json; indent=4" -u username:password
              https://ceos-cove.org/en/api/country_coverage/reports/json/<TASK
              ID>/?country=<COUNTRY>

Request JSON results for all countries for a constellation in task:


              curl -H "Accept: application/json; indent=4" -u username:password
              https://ceos-cove.org/en/api/country_coverage/reports/json/<TASK
              ID>/?constellation=<CONSTELLATION>

Request JSON results for a country and a constellation in task:


              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>

Request PDF report:


              curl -u username:password
              https://ceos-cove.org/en/api/dcountry_coverage/reports/csv/<TASK
              ID>/?country=<COUNTRY>&constellation=<CONSTELLATION> -o filename.pdf

Request CSV File:


              curl -u username:password
              https://ceos-cove.org/en/api/country_coverage/reports/csv/<TASK
              ID>/?country=<COUNTRY>&constellation=<CONSTELLATION> -o filename.csv

Request PNG Bar Chart:


              curl -u username:password
              https://ceos-cove.org/en/api/country_coverage/reports/png/<TASK
              ID>/?country=<COUNTRY>&constellation=<CONSTELLATION> -o filename.png

Request ZIP File:


              curl -u username:password
              https://ceos-cove.org/en/api/country_coverage/reports/zip/<TASK
              ID>/ -o filename.zip