Difference between revisions of "REST API GFMS"

From MyDewetra World
Jump to: navigation, search
(→‎Use Case 4 - Retrieve a flood product)
 
(21 intermediate revisions by the same user not shown)
Line 8: Line 8:
 
# how to get a full list of the available [[PRODUCTS |product output layers]] for a specific ''AOI'' (e.g., Myanmar)  
 
# how to get a full list of the available [[PRODUCTS |product output layers]] for a specific ''AOI'' (e.g., Myanmar)  
 
# how to get all the [[PRODUCTS | product output layers]] for a specific ''AOI ''
 
# how to get all the [[PRODUCTS | product output layers]] for a specific ''AOI ''
−
# how to retrieve a specific [[[PRODUCTS | product output layer]] (e.g., [[S-1_Observed_Water_Extent | water_extent]])   
+
# how to retrieve a specific [[PRODUCTS | product output layer]] (e.g., [[S-1_Observed_Water_Extent | water_extent]])   
 
 
 
[[INTRODUCTION | '''GFM''']]'s [https://en.wikipedia.org/wiki/API API] can be accessed at the following URL:  
 
[[INTRODUCTION | '''GFM''']]'s [https://en.wikipedia.org/wiki/API API] can be accessed at the following URL:  
Line 36: Line 36:
  
 
=='''Use Case 2 – Get an Area of Interest (AOI)'''==
 
=='''Use Case 2 – Get an Area of Interest (AOI)'''==
−
The second use case is devoted to give users the details through which they can address all ''AOIs'''. Therefore, please visit the /aoi endpoint. After providing the access token, the endpoint provides a list of all stored '''AOIs'''. <br>
+
The second use case is devoted to give users the details through which they can address all ''AOIs'''. After providing the access token, the endpoint provides a list of all stored '''AOIs'''. <br>
 
To do that, users have to follow a four-step procedure:
 
To do that, users have to follow a four-step procedure:
−
* Step 1: Select the endpoint  [[File: ep_product0.jpg | 500px]]
+
* Step 1: Select the endpoint  [[File: ep_product0.jpg | 350px]]
 
* Step 2: Press the ''Try it out'' button  [[File: ep_product2.jpg | 100px]]
 
* Step 2: Press the ''Try it out'' button  [[File: ep_product2.jpg | 100px]]
 
* Step 3: Enter the access token  
 
* Step 3: Enter the access token  
Line 47: Line 47:
 
  "aoi_name": "Myanmar"  
 
  "aoi_name": "Myanmar"  
  
−
After finding out the aoi_id for Myanmar, we can now use another endpoint to get a list of all available products for this AOI.   
+
After finding out the ''aoi_id'' for Myanmar, another endpoint is used to get a list of all available [[PRODUCTS | products]] for this ''AOI''.   
 
    
 
    
  
−
7 Use Case 3 - Get all products for a specific AOI  
+
=='''Use Case 3 - Get all products for a specific AOI'''==
−
This use case shows how to get a list of all products for an AOI. Therefore, please visit the /aoi/{aoi_id}/products endpoint. This endpoint requires the additional path parameter aoi-id which addresses a specific AOI (e.g.: Myanmar). A product bundles the different output layers.  
+
This use case shows how to get a list of all the [[PRODUCTS | products]] available for a specific ''AOI''. This endpoint requires the additional path parameter ''aoi_id'' (see the previous Use Case) to address a specific AOI (Myanmar, in the example). <br>
−
In order to filter the response, this API endpoint provides the additional query parameter time. This parameter accepts three values:  
+
 
−
• latest: Returns the latest product for the AOI  
+
To do that, users have to follow a four-step procedure:
−
• all: Returns all products for the AOI  
+
* Step 1: Select the endpoint  [[File: ep_product-1.jpg | 500px]]
−
• range: Returns all products within a date range. If applied, two additional query parameters (to, from) are required.  Please use the YYYY-MM-DDTHH:MM:SS date scheme to provide a date value.  
+
* Step 2: Press the ''Try it out'' button  [[File: ep_product2.jpg | 100px]]
−
The service returns a list of all products which matches the filter criteria. In particular, the endpoint provides a product_id and a timestamp for each product:  
+
* Step 3: Enter the access token
−
• "product_id": 5  
+
* Step 4: Enter the extra parameters to define the query in a specific time range. In order to filter the response, this API endpoint provides the additional query parameter '''time'''. This parameter can assume three values:  
−
• "product_time": "2019-08-16T11:40:09"  
+
# '''latest''': returns the latest product for the AOI  
 +
# '''all''': returns all products for the AOI  
 +
# '''range''': returns all products within a specified date range. If applied, two additional query parameters (''to'', ''from'') are required.  Please use the format '''YYYY-MM-DDTHH:MM:SS''' to enter a valid date.  
 +
 
 +
* Step 5: Click the “Execute” Button [[File: ep_product3.jpg | 65px]]
 +
 
 +
The service returns a list of all products that match the filter criteria. In particular, the endpoint provides a '''product_id''' and a timestamp ('''product_time''') for each product. <br>
 +
In the example:  
 +
"product_id": 5  
 +
"product_time": "2019-08-16T11:40:09"  
 
    
 
    
  
−
8 Use Case 4 - Retrieve a flood product  
+
=='''Use Case 4 - Retrieve a flood product'''==
−
The last use case in this tutorial describes how to access an actual flood layer. In the example we are interested in the water_extent layer. For this purpose, please visit the following endpoint:  
+
This use case describes how to access a specific [[PRODUCTS | output layer]] (in the example: the [[S-1_Observed_Water_Extent | water extent]] layer). <br>
−
/products/{product_id}/output_layers/{layer_name} endpoint of the API.  
+
To do that, users have to follow a four-step procedure:
−
This service accepts two additional path parameters:
+
* Step 1: Select the endpoint [[File: ep_product-2.jpg | 500px]]
−
• product_id: Unique product identifier (e.g.: product_id: 5)  
+
* Step 2: Press the ''Try it out'' button  [[File: ep_product2.jpg | 100px]]
−
• layer_name: The actual output layer we are interested in (e.g.: observed_flood_extent)  
+
* Step 3: Enter the access token
 +
* Step 4: Enter the extra parameters
 +
** '''product_id''': the unique product identifier (e.g.: product_id: 5)  
 +
** '''layer_name''': the actual [[PRODUCTS | output layer]] the query is about (e.g.: the [[S-1_Observed_Water_Extent | water extent]] )  
 
As a result, the user gets a more detailed product description. This description consists of the following information:  
 
As a result, the user gets a more detailed product description. This description consists of the following information:  
−
• product_id: Unique product identifier  
+
* product_id: Unique product identifier  
−
• layer_name: Names of the product output layers.
+
* layer_name: names of the [[PRODUCTS | output layer]]
−
o Note, an overview of the product output layers can we found below.
+
−
• layer_type: Layer type (raster or vector)  
+
Please note that a comprehensive list of the paramaters defining the [[PRODUCTS | output layer]] is given below:
−
• timestamp: Product date information  
+
* layer_type: Layer type (raster or vector)  
−
• url_data: URL to download the product  
+
* timestamp: Product date information  
−
• url_tiles: URL to access the tile information   
+
* url_data: URL to download the product  
−
For the example above (Myanmar / water_extent), the response looks like this:  
+
* url_tiles: URL to access the tile information   
−
• product_id: 5  
+
that, in the given example (Myanmar / water_extent) will look like:
−
• layer_name: water_extent  
+
* product_id: 5  
−
• layer_type: raster  
+
* layer_name: water_extent  
−
• Timestamp: 2019-08-16T11:40:09",  
+
* layer_type: raster  
−
• url_data  
+
* Timestamp: 2019-08-16T11:40:09",  
−
https://demo.geoville.com/jrc_gfm_demo/data/OL2_Observed_Water_Extent_Myanmar.tif  
+
* url_data: https://demo.geoville.com/jrc_gfm_demo/data/OL2_Observed_Water_Extent_Myanmar.tif  
−
• url_tiles  
+
* url_tiles: https://tileserver.geoville.com/jrc-gfms/OL2_S1_OWE_Myanmar/{z}/{x}/{y}.png  
−
https://tileserver.geoville.com/jrc-gfms/OL2_S1_OWE_Myanmar/{z}/{x}/{y}.png  
 
 
    
 
    
  
−
9 API Specifications - Overview
+
===API Specifications - Overview===
−
 
−
API Specifications - Overview
 
 
   
 
   
−
GFM product output layer Product data format Endpoint (latest observation)
+
{| class="wikitable" style="text-align: center;
−
flood_extent Product output layers - Raster data
+
| align="center" style="background:#f0f0f0;"|'''GFM product output layer'''
−
Raster data <base-url>/v1/flood_extent/{roi-id}
+
| align="center" style="background:#f0f0f0;"|'''Product data format'''
−
reference_water_mask Raster layer <base-url>/v1/water_mask/{roi-id}
+
| align="center" style="background:#f0f0f0;"|'''Endpoint (latest observation)'''
−
water_extent Raster layer <base-url>/v1/water_extent/{roi-id}
+
|-
−
exclusion_mask Raster layer <base-url>/v1/exclusion_mask/{roi-id}
+
| flood_extent || Product output layers - Raster data || /v1/flood_extent/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
−
uncertainty_values Raster layer <base-url>/v1/uncertainty_values /{roi-id}
+
|-
−
advisory_flags Vector data (GeoJSON) <base-url>/v1/advisory_flags/{roi-id}
+
| reference_water_mask||Product output layers - Raster data||/v1/water_mask/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
−
sentinel-1_metadata Vector data (GeoJSON) <base-url>/v1/metadata/{roi-id}
+
|-
−
sentinel-1_footprint Vector data (GeoJSON) <base-url>/v1/footprint/{roi-id}
+
| [[S-1_Observed_Water_Extent | water_extent]] ||Product output layers - Raster data||/v1/water_extent/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
−
sentinel-1_schedule Vector data (GeoJSON) <base-url>/v1/schedule/{roi-id}
+
|-
−
affected_population Raster layer <base-url>/v1/affected_population/{roi-id}
+
| exclusion_mask||Product output layers - Raster data||/v1/exclusion_mask/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
−
affected_landcover Raster layer <base-url>/v1/affected_landcover/{roi-id}
+
|-
 +
| uncertainty_values||Product output layers - Raster data||/v1/uncertainty_values /{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
 +
|-
 +
| advisory_flags||Product output layers - GeoJSON data||/v1/advisory_flags/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
 +
|-
 +
| sentinel-1_metadata||Product output layers - GeoJSON data||/v1/sentinel-1_metadata/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
 +
|-
 +
| sentinel-1_footprint||Product output layers - GeoJSON data||/v1/sentinel-1_footprint/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
 +
|-
 +
| sentinel-1_schedule||Product output layers - GeoJSON data||/v1/sentinel-1_schedule/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
 +
|-
 +
| affected_population||Product output layers - Raster data||/v1/affected_population/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
 +
|-
 +
| affected_landcover||Product output layers - Raster data||/v1/affected_landcover/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
 +
|-
 +
|
 +
|}
  
  

Latest revision as of 08:43, 13 July 2021

caption

[Home] - [Data access]

This section is devoted to explain how GFM's dissemination API can be used to access and download flood products. The chapter is organized as follows:

  1. how to get a list of all available product output layers together with their description
  2. how to get a full list of the available product output layers for a specific AOI (e.g., Myanmar)
  3. how to get all the product output layers for a specific AOI
  4. how to retrieve a specific product output layer (e.g., water_extent)

GFM's API can be accessed at the following URL: 

https://api.gfm.geoville.com/v1/

For the authentication the following token can be used: 

Bearer Q8ajYGdedXVwtbqbkoHD4G1tTTja6PrXVxNgXnZTfL

In the following use cases this manual will make of use the terms products and output layers:


Use Case 1 – Get all available output layer types for flood products

The first use case shows how to get a list of all the available output layer types together with their description. Expand the

'Therefore, please visit the /products/output_layer_types endpoint in the API documentation.' To do that, users have to follow a four-step procedure:

  • Step 1: Select the endpoint Ep product1.jpg
  • Step 2: Press the Try it out button Ep product2.jpg
  • Step 3: Enter the access token
  • Step 4: Click the “Execute” Button Ep product3.jpg

As a result, the API endpoint provides a list o