Difference between revisions of "REST API GFMS"

From MyDewetra World
Jump to: navigation, search
(→‎API Use Cases)
(→‎Use Case 4 - Retrieve a flood product)
 
(42 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 | 200px]]
+
* Step 1: Select the endpoint  [[File: ep_product1.jpg | 500px]]
−
* Step 2: Press the ''Try it out'' button   
+
* 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  
+
* 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}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​