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.
Request Method: GET
Request URL:
https://ceos-cove.org/en/api/v1_2/regions/
URL Parameters: None
[
{
"folder": "Africa",
"region": "Algeria"
}, {
"folder": "Africa",
"region": "Angola"
}, {
"folder": "Africa",
"region": "Benin"
}, {
"folder": "Africa",
"region": "Botswana"
},
(REGIONS LIST TRUNCATED)
]
Parameter Name | Data Type | Required | Description |
---|---|---|---|
region_folder | String | No | Default folder is User Folder. |
region | String | Yes | Region Name |
{
"region_folder": "Africa",
"region": "Ghana"
}
POST
https://ceos-cove.org/en/api/v1_2/regions/
None
{
"status": 200,
"region_folder": "Africa",
"region": "Ghana",
"id": 171
}
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.
Parameter Name | Data Type | Required | Description |
---|---|---|---|
region | String | Yes | Region name |
data | String | Yes | KML file passed as a string. |
{
"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>"
}
POST
https://ceos-cove.org/en/api/v1_2/regions/
None
{'status': 415, 'message': 'Unable to parse KML string.'}
KML files must contain only one region. If the KML file contains multiple regions, it must be imported from the COVE UI.
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. |
POST
https://ceos-cove.org/en/api/v1_2/regions/upload/
None
{'status': 415, 'message': '<Error Message>'}
Shapefiles must contain only one region. If the shapefile contains multiple regions, it must be imported from the COVE UI.
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. |
POST
https://ceos-cove.org/en/api/v1_2/regions/upload/
None
{'status': 415, 'message': '<Error Message>'}
GET
https://ceos-cove.org/en/api/v1_2/regions/kml/
None
The shapefile file exported (ZIP) is used in geographic information systems (GIS) and contains polygon coordinates of the region of interest.
GET
https://ceos-cove.org/en/api/v1_2/regions/shapefile/
None
The PNG image file shows a map of the region of interest, and allows users to view existing and imported regions.
GET
https://ceos-cove.org/en/api/v1_2/regions/png/<REGION ID>/
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.
|
{
"status": 200,
"map_coordinates": [
[-8.661654877310252, -0.16135473389262667],
[-8.661654877310252, 14.838645266107374],
[6.3383451226897485, 14.838645266107374],
[6.3383451226897485, -0.16135473389262667],
[-8.661654877310252, -0.16135473389262667]
]
}
{'status': 404, 'message': 'File not found.'}
curl -H "Accept: application/json; indent=4" -u username:password
https://ceos-cove.org/en/api/regions/
curl -H "Content-Type: application/json" -X POST -u username:password -d
'{"region_folder": "Africa", "region": "Ghana"}'
https://ceos-cove.org/en/api/regions/
curl -H "Content-Type: application/json" -X POST -u username:password -d
'{"region": "RegionA", "data": "<KML STRING>"}'
https://ceos-cove.org/en/api/regions/
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/
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/
curl -u username:password https://ceos-cove.org/en/api/regions/png/<REGION
ID>/ -o region.png
curl -u username:password https://ceos-cove.org/en/api/region/png/<REGION
ID>/?transparent=true -o filename.png
curl -u username:password https://ceos-cove.org/en/api/regions/png/<REGION
ID>/?resolution=200 -o filename.png
curl -u username:password https://ceos-cove.org/en/api/regions/png/<REGION
ID>/?line_width=0.5 -o filename.png
curl -u username:password https://ceos-cove.org/en/api/regions/png/<REGION
ID>/?line_color=%23FFFFFF -o filename.png
curl -u username:password https://ceos-cove.org/en/api/regions/png/<REGION
ID>/?map_coordinates=true -o filename.png
curl -u username:password https://ceos-cove.org/en/api/regions/kml/<REGION
ID>/ -o region.kml
curl -u username:password https://ceos-cove.org/en/api/regions/shapefile/<REGION
ID>/ -o region.zip