CEOS COVE API Help: Regions

Regions allows users to create custom regions of interest. Regions are used in Acquisition Forecaster, Coverage Analyzer, Revisits Calculator, Coincident Calculator, and Data Browser. Users may send requests for a regions list, details of a region, import a region by KML string, KML binary file, or Shapefile, export a region by KML file or Shapefile, and retrieve a PNG map image of the region.

Regions throttle limits:

POST: 15 requests per hour
GET: 120 requests per hour

Retrieve regions list

Request Method: GET

Request URL:
https://ceos-cove.org/en/api/v1_2/regions/

URL Parameters: None

Response Example:

[

{

"folder": "Africa",

"region": "Algeria"

}, {

"folder": "Africa",

"region": "Angola"

}, {

"folder": "Africa",

"region": "Benin"

}, {

"folder": "Africa",

"region": "Botswana"

},

(REGIONS LIST TRUNCATED)

]

Retrieve region details

Input Parameters:

Parameter Name	Data Type	Required	Description
region_folder	String	No	Default folder is User Folder.
region	String	Yes	Region Name

Request Data Example::

{

"region_folder": "Africa",

"region": "Ghana"

}

Request Method: POST

Request URL:


              https://ceos-cove.org/en/api/v1_2/regions/

URL Parameters: None

Response Examples:

{

"status": 200,

"region_folder": "Africa",

"region": "Ghana",

"id": 171

}

Import region KML string

The KML (Keyhole Markup Language) is an XML formatted file, and is was developed for use with GoogleEarth. It contains polygon coordinates of the region of interest. KML files must contain only one region. If the KML file contains multiple regions, it must be imported from the COVE UI.

Input Parameters:

Parameter Name	Data Type	Required	Description
region	String	Yes	Region name
data	String	Yes	KML file passed as a string.

Request Data Example::

{

"region": "Barekese Dam",


              "data": "<?xml version="1.0" encoding="UTF-8"?><kml
              xmlns="http://www.opengis.net/kml/2.2"><Placemark><Polygon><outerBoundaryIs><LinearRing><coordinates>-1.722,6.844,0
              -1.721,6.844,0 -1.722,6.843,0
              -1.721,6.839,0 -1.723,6.837,0 -1.721,6.836,0 -1.723,6.832,0 -1.721,6.832,0
              -1.72,6.831,0 -1.718,6.83,0 -1.716,6.827,0 -1.716,6.83,0 -1.715,6.832,0
              -1.712,6.83,0 -1.707,6.825,0 -1.707,6.827,0 -1.71,6.831,0 -1.713,6.834,0
              -1.713,6.837,0 -1.71,6.838,0 -1.707,6.837,0 -1.707,6.837,0 -1.708,6.839,0
              -1.707,6.84,0 -1.704,6.839,0 -1.703,6.841,0 -1.703,6.842,0 -1.706,6.845,0
              -1.705,6.846,0 -1.706,6.849,0 -1.7,6.85,0 -1.697,6.852,0 -1.695,6.85,0
              -1.695,6.85,0 -1.695,6.852,0 -1.694,6.855,0 -1.693,6.855,0 -1.69,6.855,0
              -1.688,6.856,0 -1.686,6.854,0 -1.684,6.854,0 -1.684,6.856,0 -1.687,6.858,0
              -1.686,6.861,0 -1.687,6.863,0 -1.692,6.86,0 -1.697,6.858,0 -1.701,6.861,0
              -1.707,6.86,0 -1.701,6.861,0 -1.697,6.858,0 -1.701,6.855,0 -1.705,6.855,0
              -1.707,6.854,0 -1.71,6.855,0 -1.712,6.854,0 -1.712,6.852,0 -1.713,6.85,0
              -1.712,6.847,0 -1.715,6.843,0 -1.716,6.844,0 -1.716,6.842,0 -1.716,6.842,0
              -1.718,6.841,0 -1.721,6.841,0 -1.722,6.844,0</coordinates></LinearRing></outerBoundaryIs></Polygon></Placemark></kml>"

}

Request Method: POST

Request URL:


              https://ceos-cove.org/en/api/v1_2/regions/

URL Parameters: None

Failed Response Examples:

{'status': 415, 'message': 'Unable to parse KML string.'}

Import region KML file

KML files must contain only one region. If the KML file contains multiple regions, it must be imported from the COVE UI.

Input Parameters:

Parameter Name	Data Type	Required	Description
file	KML (binary)	Yes	Region name will be the name of the file received. If the file name is unable to be determined, the default name is User Region.

Request Method: POST

Request URL:


              https://ceos-cove.org/en/api/v1_2/regions/upload/

URL Parameters: None

Failed Response Examples:

{'status': 415, 'message': '<Error Message>'}

Import region shapefile

Shapefiles must contain only one region. If the shapefile contains multiple regions, it must be imported from the COVE UI.

Input Parameters:

Parameter Name	Data Type	Required	Description
file	Shapefile	Yes	Region name will be the name of the file received. If the file name is unable to be determined, the default name is User Region.

Request Method: POST

Request URL:


              https://ceos-cove.org/en/api/v1_2/regions/upload/

URL Parameters: None

Failed Response Examples:

{'status': 415, 'message': '<Error Message>'}

Export region KML file

Request Method: GET

Request URL:


              https://ceos-cove.org/en/api/v1_2/regions/kml/

URL Parameters: None

Export region shapefile

The shapefile file exported (ZIP) is used in geographic information systems (GIS) and contains polygon coordinates of the region of interest.

Request Method: GET

Request URL:


              https://ceos-cove.org/en/api/v1_2/regions/shapefile/

URL Parameters: None

Retrieve region PNG

The PNG image file shows a map of the region of interest, and allows users to view existing and imported regions.

Request Method: GET

Request URL:


              https://ceos-cove.org/en/api/v1_2/regions/png/<REGION ID>/

URL Parameters:

Parameter Name	Data Type	Required	Description
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.
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.
line_width	Float	No	Values should be greater than 0. Allows users to define the line width of scene footprint outlines. This parameter does not apply to region outlines. Default value is 0.5.
line_color	String	No	Values should be a standard six character hex color string. The leading # character is optional. Allows users to define the line color for the region outline. Default value is #FFFFFF (white).
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. If an orbit_direction parameter is used to generate an image, it should be included in requests for map coordinates.

Map Coordinates Response Example:

{

"status": 200,

"map_coordinates": [

[-8.661654877310252, -0.16135473389262667],

[-8.661654877310252, 14.838645266107374],

[6.3383451226897485, 14.838645266107374],

[6.3383451226897485, -0.16135473389262667],

[-8.661654877310252, -0.16135473389262667]

]

}

Failed Response Example:

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

Example API requests using curl

Request region list:


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

Request region information:


              curl -H "Content-Type: application/json" -X POST -u username:password -d
              '{"region_folder": "Africa", "region": "Ghana"}'
              https://ceos-cove.org/en/api/regions/

Import region KML string:


              curl -H "Content-Type: application/json" -X POST -u username:password -d
              '{"region": "RegionA", "data": "<KML STRING>"}'
              https://ceos-cove.org/en/api/regions/

Import region KML file:


              curl -H "Content-Type: multipart/form-data" -X POST -u username:password
              -F file=@region_name.kml https://ceos-cove.org/en/api/regions/upload/

Import region shapefile:


              curl -H "Content-Type: multipart/form-data" -X POST -u username:password
              -F file=@region_name.zip https://ceos-cove.org/en/api/regions/upload/

Export region PNG map image:


              curl -u username:password https://ceos-cove.org/en/api/regions/png/<REGION
              ID>/ -o region.png

Request PNG map image (transparent):


              curl -u username:password https://ceos-cove.org/en/api/region/png/<REGION
              ID>/?transparent=true -o filename.png

Request PNG map image (resolution):


              curl -u username:password https://ceos-cove.org/en/api/regions/png/<REGION
              ID>/?resolution=200 -o filename.png

Request PNG map image (line_width):


              curl -u username:password https://ceos-cove.org/en/api/regions/png/<REGION
              ID>/?line_width=0.5 -o filename.png

Request PNG map image (line_color):


              curl -u username:password https://ceos-cove.org/en/api/regions/png/<REGION
              ID>/?line_color=%23FFFFFF -o filename.png

Request PNG map image (map_coordinates):


              curl -u username:password https://ceos-cove.org/en/api/regions/png/<REGION
              ID>/?map_coordinates=true -o filename.png

Export region KML file:


              curl -u username:password https://ceos-cove.org/en/api/regions/kml/<REGION
              ID>/ -o region.kml

Export region shapefile:


              curl -u username:password https://ceos-cove.org/en/api/regions/shapefile/<REGION
              ID>/ -o region.zip

Help: COVE API User's Guide: Regions

Retrieve regions list

Retrieve region details

Import region KML string

Import region KML file

Import region shapefile

Export region KML file

Export region shapefile

Retrieve region PNG

Example API requests using curl