API

<
"

 

COVE API Documentation

Last Revision: 06/09/16

The COVE API is an easy-to-use, RESTful interface that gives you access to the powerful engine that generates COVE data sets. Using the API you can:

  • Generate swath KML files
  • Generate coincidence KML files
  • Generate coincidence CSV files
  • Generate potential acquisition CSV files
  • Generate actual acquisition CSV files

All functionality is accessible using simple HTTP requests.


Note that, in URLs the plus character '+' is used in lieu of the space character ' '. Thus the instrument "AMSR-E - 1445 km" would be represented as "AMSR-E+-+1445+km". Other special characters can be included using percent encoding.

 

Getting Started

Swath and Coincidence Files 

 

Most of the COVE API functionality can be accessed from http://www.ceos-cove.org/api/getKML.php. This URL provides access to swath KML, coincidence KML and coincidence CSV reports.

 

Base URL (Swath and Coincidence files):
  • http://www.ceos-cove.org/api/getKML.php
URL Parameters for Swath KML:
Example Request

Notes:

  • Using these parameters For swath KML files will generate a swath KML file for the daytime viewing region of an instrument.
  • The value of the endDate parameter may be up to 1 week after startDate.
  • Future acquisitions can only be generated for up to 150 days into the future. Blank KML files will be returned when the startDate is greater than 150 days from the current date.
Additional Parameters for Coincidence KML/CSV files:
  • modename2 - the reference name (case sensitive) of the second instrument mode (see listModes.php for JSON list of names and associated missions and instruments)
  • modename3 - the reference name (case sensitive) of the third instrument mode (see listModes.php for JSON cialis prix list of names and associated missions and instruments)
  • modename4 - the reference name (case sensitive) of the fourth instrument mode (see listModes.php for JSON list of names and associated missions and instruments)
  • lapseTime (hh:mm)
  • mode (values: day, night, coincidence, csv)

Notes:

  • If more than one mission is specified, then coincidence between the given missions is computed. Up to four satellites may be used in coincidence calculations. Coincidence calculations are peformed pair-wise, so if four missions are selected, COVE will display all regions that were acquired by any two of the four satellites.
  • The lapseTime parameter specifies the maximum time between satellite acquisitions that should be considered "coincidental." For example, if Aqua has an acquisition of Miami, Fl at 11:03 UTC and GeoEye has an acquisition of Miami at 15:23 UTC, then COVE will only report a coincidence for these two acquisitions if lapseTime is set to less than 04:20:00. lapseTime has no effect if only one mission is specified.
  • For requests with a single mission specified, mode defaults to day. Setting mode=night will cause COVE to return the night time swath of the instrument, rather than the daytime. For instruments that are day-time only, a blank swath will be returned.
  • For requests with more than one mission specified, mode defaults to coincidence. In coincidence mode, COVE will return a KML file that displays all of the projected coincidences. If mode is set to csv, then COVE will instead return an aquisition report in .csv format. This format can be viewed in most spreadsheet applications.

 

 

Potential Acquisitions 

 

Acquisition reports, like those generated by the Rapid Acquisition Tool, can also be generated from the COVE API. The base URL for acquisition reports is http://www.ceos-cove.org/api/getAcq.php.

 

 

Base URL (Potential Acquisitions):
  • http://www.ceos-cove.org/api/getAcq.php
URL Parameters for Potential Acquisitions:
Example Request

This link finds all Landsat 7 acquisitions over Williamsburg, VA from October 1, 2015 to October 29, 2015:

Notes:

  • Reports are generated in CSV format.
  • The value of endDate may be up to 10 weeks after startDate.
  • Acquisitions over regions (as opposed to points) is not supported.
  • Future acquisitions can only be generated for up to 150 days into the future.

 

Actual Acquisitions

 

A list of actual acquisitions over a given region within a given time period can be obtained by using http://www.ceos-cove.org/api/getActualAcquisitions.php.

 

 

Base URL (Actual Acquisitions)
  • http://www.ceos-cove.org/api/getActualAcquisitions.php
URL Parameters for Actual Acquisitions:
  • startDate - in the format mm/dd/yyyy (e.g. 02/28/1996)
  • endDate - in the same format as startDate
  • modeName - the reference name (case sensitive) of the instrument mode (see listRegions.php for information on finding the ID of a given region)
  • regionId - the numeric ID of the region of interest
  • cloudMax - OPTIONAL upper limit on the cloud cover percentage (Expressed as a percentage in the range 0 to 100, where the default value of 100 means that all acquisitions will be returned)
Example Request

This link finds all SPOT 5 HRG acquisitions over Kenya from January 20, 2006 to February 15, 2006 with cloud cover of 60% or less:

Notes:

  • Reports are generated in CSV format.
  • The value of endDate may be up to 2 years after startDate. If the endDate is more than 2 years after startDate then endDate will be truncated and the endDate value will be set at the 2 year mark. If the startDate is after the endDate, then the two dates will be swapped.

 

 

Instrument Mode Reference Names 


All other functionality of the API depends on specifying the mode reference name or names in the request to specify to the API which instrument/mode you want to use.
A full JSON list of these mode reference names and associated instruments and missions can be found by going to http://www.ceos-cove.org/api/listModes.php

Region List 


Some COVE API functions require a region ID as input. A list of currently available regions can be obtained by going to http://www.ceos-cove.org/api/listRegions.php. The list of regions is returned in JSON format by default, but other formats are available by specifying either CSV, HTML, or TEXT as shown below:
http://www.ceos-cove.org/api/listRegions.php?format=HTML


back to top