Help: COVE API User's Guide

The Committee on Earth Observation Satellites (CEOS) Visualization Environment (COVE) application programming interface (API) is a suite of endpoints for executing tasks and retrieving results for a collection of COVE tools.

All tasks created using the COVE API will be available in the COVE UI, and all tasks created in the COVE UI will be available in the COVE API.

A valid COVE username and password are required for all requests. A COVE login may be created in the COVE UI by clicking on the Log In/Register ling in the upper right corner.

COVE tool API sets are throttled to help reduce system overload. Throttle limits are subject to change if the need arises. The throttle limits will be detailed in each tool section below, and will be updated in this document as changes are made.

To submit a request to the service, include the appropriate JSON payload in the body of a POST request for the endpoint. Requests should include the trailing slash in the url. Examples using curl with each type of request are provided in each section below.

All responses will either be a JSON response or a binary file. All failed responses will be in JSON format, and will include a status (standard HTTP status code).

Execution start in all task status responses are in UTC time.

For CSV files, use unicode UTF-8.

Please refer to the COVE UI User's Guide for more information on the usage of each COVE tools.

The following COVE tools are accessible from the COVE API:

Acquisition Forecaster: A set of endpoints which provides users with the ability to:
  • History: retrieve a history of Acquisition Forecaster tasks previously completed
  • Submit: submit a task in the Acquisition Forecaster tool
  • Status: retrieve results of an Acquisition Forecaster task
  • CSV: retrieve CSV results of an Acquisition Forecaster task
  • PNG: retrieve a graphical representation of the results of an Acquisition Forecaster task
Examples using curl for Acquisition Forecaster are available here.
 
Coverage Analyzer: A set of endpoints which provides users with the ability to:
  • History: retrieve a history of Coverage Analyzer tasks previously completed
  • Submit: submit a task in the Coverage Analyzer tool
  • Status: retrieve results of a Coverage Analyzer task
  • JSON: retrieve JSON results of a Coverage Analyzer task
  • CSV: retrieve CSV results of a Coverage Analyzer task
  • PNG: retrieve a graphical representation of the results of a Coverage Analyzer task
  • GeoTiff: retrieve GeoTiff results of a Coverage Analyzer task
  • NetCDF: retrieve NetCDF results of a Coverage Analyzer task
Examples using curl for Coverage Analyzer are available here.
 
Revisits Calculator: A set of endpoints which provides users with the ability to submit a task in the Revisits Calculator tool, and retrieve results of the task (history, status, JSON, CSV, PNG).
  • History: retrieve a history of Revisits Calculator tasks previously completed
  • Submit: submit a task in the Revisits Calculator tool
  • Status: retrieve results of a Revisits Calculator task
  • JSON: retrieve JSON results of a Revisits Calculator task
  • CSV: retrieve CSV results of a Revisits Calculator task
  • PNG: retrieve a graphical representation of the results of a Revisits Calculator task
Examples using curl for Revisits Calculator are available here.
 
Coincident Calculator: A set of endpoints which provides users with the ability to:
 
For Coincident Calculator tasks using forecasted missions:
  • History: retrieve a history of Coincident Calculator tasks previously completed
  • Submit: submit a task in the Coincodent Calculator tool
  • Status: retrieve results of a Coincident Calculator task
  • JSON: retrieve JSON results of a Coincident Calculator task
  • PNG: retrieve a graphical representation of the results of a Coincident Calculator task
Examples using curl for Coincident Calculator using forecasted missions are available here.
 
For Coincident Calculator tasks using archived missions:
  • History: retrieve a history of Coincident Calculator tasks previously completed
  • Submit: submit a task in the Coincident Calculator tool
  • Status: retrieve results of a Coincident Calculator task
  • JSON: retrieve JSON results of a Coincident Calculator task
  • PNG: retrieve a graphical representation of the results of a Coincident Calculator task
Examples using curl for Coincident Calculator using archived missions are available here.
 
Data Browser: A set of endpoints which provides users with the ability to submit a task in the Data Browser tool, and retrieve results of the task (history, status, scene count, CSV, PNG).
  • History: retrieve a history of Data Browser tasks previously completed
  • Submit: submit a task in the Data Browser tool
  • Status: retrieve results of a Data Browser task
  • Scene count: retrieve a count of the number of scenes available for a Data Browser task
  • CSV: retrieve CSV results of a Data Browser task
  • PNG: retrieve a graphical representation of the results of an Data Browser task
Examples using curl for Data Browser are available here.
 
Country Coverage: A set of endpoints which provides users with the ability to submit a task in the Country Coverage tool, and retrieve results of the task (history, status, PDF, CSV, and PNG).
  • Constellations List: retrieve a list of all constellations and the missions associated with each constellation.
  • Countries List: retrieve a list of countries available for generating Country Coverage reports
  • Daily Task History: retrieve a list of all existing and generating Country Coverage reports in COVE for the current day
  • Monthly Cached History: retrieve a list all monthly cached Country Coverage reports available in COVE
  • Submit: submit a task in the Country Coverage tool, for daily reports or monthly cached reports
  • Status: retrieve results of a Country Coverage task
  • JSON: retrieve JSON results of a Country Coverage task
  • PDF: retrieve PDF results of a Country Coverage task
  • CSV: retrieve CSV results of a Country Coverage task
  • PNG: retrieve a graphical representation of the results of a Country Coverage task
  • ZIP: retrieve ZIP results of a Country Coverage task
Examples using curl for Country Coverage are available here.
 
Utilities: A set of endpoints for access to COVE utilities.
Examples using curl for Utilities are available here.
 

Other COVE API endpoints included in this document are:

Missions:
  • forecasted: an endpoint for Acquisition Forecaster, Coincident Calculator, and Revisits Calculator tasks which lists details on forecasted missions available
  • archived: an endpoint for Coverage Analyzer, Coincident Calculator, and Data Browser tasks which lists details on archived missions available
Examples using curl for Missions are available here.
Custom Missions: a pair of endpoints which provides users with the ability to:
  • Details: retrieve a list of details about a custom mission
  • Create: create a custom mission with one or more custom instruments
Examples using curl for Custom Missions are available here.
Constellations: endpoints which provides users with the ability to
  • Using forecasted missions:
    • Details: retrieve a list of all custom forecasted constellations in Coincident Calculator created by the user
    • Create: create new constellations using forecasted missions and/or custom missions
  • Using archived missions:
    • Details: retrieve a list of all custom archived constellations in Coincident Calculator created by the user
    • Create: create new constellations using archived missions
Examples using curl for Constellations are available here.
Regions: A set of endpoints which provides users with the ability to:
Examples using curl for Regions are available here.
 
Version Information: retrieve a summary of version information which includes the current version, supported versions, deprecated versions, and revision history
Examples using curl for Version Information are available here.
 

Additional information:

Python Examples: Includes examples for defining credentials and sending GET or POST requests
 
Special Data Types: A detailed guide to special data types used with the COVE API
 
Summary of all COVE API endpoints: A table summarizing all COVE API endpoints
 
Feedback: Feedback details. All feedback on COVE and the COVE API are appreciated!