Difference between revisions of "REST API GFMS"

From MyDewetra World
Jump to: navigation, search
(API Use Cases)
(Use Case 4 - Retrieve a flood product)
 
(39 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
----
 
----
  
This section is devoted to explain how '''GFM''''s dissemination [https://en.wikipedia.org/wiki/API API] can be used to access and download flood products.
+
This section is devoted to explain how [[INTRODUCTION | '''GFM''']]'s dissemination [https://en.wikipedia.org/wiki/API API] can be used to access and download flood products.
 
The chapter is organized as follows:
 
The chapter is organized as follows:
 
# how to get a list of all available product output layers together with their description  
 
# how to get a list of all available product output layers together with their description  
# how to get a full list of the available 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 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 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]])   
 
 
==API Endpoint==
+
[[INTRODUCTION | '''GFM''']]'s [https://en.wikipedia.org/wiki/API API] can be accessed at the following URL:  
The [https://en.wikipedia.org/wiki/API API] can be accessed at the following URL:  
+
[https://api.gfm.geoville.com/v1/  https://api.gfm.geoville.com/v1/]
* [https://api.gfm.geoville.com/v1/  https://api.gfm.geoville.com/v1/]
+
 
Currently, the [https://en.wikipedia.org/wiki/API API] is divided into two namespaces:
 
*the AOI namespace offers endpoints to access the [[PRODUCTS | flood products / output layers]]
 
 
For the authentication the following token can be used:  
 
For the authentication the following token can be used:  
 
  Bearer Q8ajYGdedXVwtbqbkoHD4G1tTTja6PrXVxNgXnZTfL  
 
  Bearer Q8ajYGdedXVwtbqbkoHD4G1tTTja6PrXVxNgXnZTfL  
 +
 
In the following use cases this manual will make of use the terms '''products''' and '''output layers''':
 
In the following use cases this manual will make of use the terms '''products''' and '''output layers''':
 
* an output layer is one of the eleven [[PRODUCTS | products]] delivered by the service
 
* an output layer is one of the eleven [[PRODUCTS | products]] delivered by the service
 
* a product is the full set of all the 11 [[PRODUCTS | flood-related layers]]
 
* a product is the full set of all the 11 [[PRODUCTS | flood-related layers]]
  
==API Use Cases==
+
 
===Use Case 1 – Get all available output layer types for flood products===   
+
=='''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  [[PRODUCTS | output layer types]] together with their description.   
 
The first use case shows how to get a list of all the available  [[PRODUCTS | output layer types]] together with their description.   
 
Expand the  
 
Expand the  
Line 28: Line 27:
 
''''Therefore, please visit the /products/output_layer_types endpoint in the API documentation.''''
 
''''Therefore, please visit the /products/output_layer_types endpoint in the API documentation.''''
 
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_product1.jpg | 400px]]
+
* Step 1: Select the endpoint  [[File: ep_product1.jpg | 500px]]
* Step 2: Press the ''Try it out'' button  [[File: ep_product2.jpg | 400px]]
+
* 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  
* Step 4: Click the “Execute” Button [[File: ep_product3.jpg | 400px]]
+
* Step 4: Click the “Execute” Button [[File: ep_product3.jpg | 65px]]
As a result, the API endpoint provides a list of all available output layers, the type of the layer and description.
+
As a result, the API endpoint provides a list of all available output layers, the type of the layer and description:
 
    
 
    
 +
[[File: ep_product4.jpg | 500px]]
 +
 +
=='''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'''. 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:
 +
* Step 1: Select the endpoint  [[File: ep_product0.jpg | 350px]]
 +
* Step 2: Press the ''Try it out'' button  [[File: ep_product2.jpg | 100px]]
 +
* Step 3: Enter the access token
 +
* Step 4: Click the “Execute” Button [[File: ep_product3.jpg | 65px]]
  
 +
In this tutorial the Myanmar AOI is used: 
 +
"aoi_id": "e289b746fa66c0bea2049a020aa38b0c9aacb8783c112117a9002ae035511bcb"
 +
"aoi_name": "Myanmar"
  
6 Use Case 2 – Get an Area of Interest (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''.   
The second use case demonstrates how a user can address all AOIs. Therefore, please visit the /aoi endpoint. After providing the access token, the endpoint provides a list of all stored AOIs. 
 
In this tutorial we are interested in the AOI Myanmar: 
 
• "aoi_id": "e289b746fa66c0bea2049a020aa38b0c9aacb8783c112117a9002ae035511bcb"
 
• "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.   
 
 
    
 
    
  
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 of all available output layers, the type of the layer and description:

Ep product4.jpg

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'. After providing the access token, the endpoint provides a list of all stored AOIs.
To do that, users have to follow a four-step procedure:

  • Step 1: Select the endpoint Ep product0.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

In this tutorial the Myanmar AOI is used:

"aoi_id": "e289b746fa66c0bea2049a020aa38b0c9aacb8783c112117a9002ae035511bcb" 
"aoi_name": "Myanmar" 

After finding out the aoi_id for Myanmar, another endpoint is used to get a list of all available products for this AOI.


Use Case 3 - Get all products for a specific AOI

This use case shows how to get a list of all the 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).

To do that, users have to follow a four-step procedure:

  • Step 1: Select the endpoint Ep product-1.jpg
  • Step 2: Press the Try it out button Ep product2.jpg
  • Step 3: Enter the access token
  • 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:
  1. latest: returns the latest product for the AOI
  2. all: returns all products for the AOI
  3. 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 Ep product3.jpg

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.
In the example:

"product_id": 5 
"product_time": "2019-08-16T11:40:09" 
 

Use Case 4 - Retrieve a flood product

This use case describes how to access a specific output layer (in the example: the water extent layer).
To do that, users have to follow a four-step procedure:

  • Step 1: Select the endpoint Ep product-2.jpg
  • Step 2: Press the Try it out button Ep product2.jpg
  • 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 output layer the query is about (e.g.: the water extent )

As a result, the user gets a more detailed product description. This description consists of the following information:

* product_id: Unique product identifier 
* layer_name: names of the  output layer 

Please note that a comprehensive list of the paramaters defining the output layer is given below:

* layer_type: Layer type (raster or vector) 
* timestamp: Product date information 
* url_data: URL to download the product 
* url_tiles: URL to access the tile information  

that, in the given example (Myanmar / water_extent) will look like:

* product_id: 5 
* layer_name: water_extent 
* layer_type: raster 
* Timestamp: 2019-08-16T11:40:09", 
* url_data: https://demo.geoville.com/jrc_gfm_demo/data/OL2_Observed_Water_Extent_Myanmar.tif 
* url_tiles: https://tileserver.geoville.com/jrc-gfms/OL2_S1_OWE_Myanmar/{z}/{x}/{y}.png 
 

API Specifications - Overview

GFM product output layer Product data format Endpoint (latest observation)
flood_extent Product output layers - Raster data /v1/flood_extent/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
reference_water_mask Product output layers - Raster data /v1/water_mask/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
water_extent Product output layers - Raster data /v1/water_extent/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​roi-id}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
exclusion_mask Product output layers - Raster data /v1/exclusion_mask/{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​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}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​



[Home] - [Data access]