View source for REST API GFMS

[[File:example7.jpg|right|100px|caption]]
[[GFMS | [Home]]] - [[DATA ACCESS | [Data access]]]
----

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:
# how to get a list of all available product output layers together with their description 
# 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 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: 
* [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: 
 Bearer Q8ajYGdedXVwtbqbkoHD4G1tTTja6PrXVxNgXnZTfL 
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
* a product is the full set of all the 11 [[PRODUCTS | flood-related 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  [[PRODUCTS | 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  [[File: ep_product1.jpg | 500px]]
* 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]]
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'''. Therefore, please visit the /aoi endpoint. 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 | 500px]]
* 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" 

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 
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. 
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 
•	all: Returns all products for the AOI 
•	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. 
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: 
•	"product_id": 5 
•	"product_time": "2019-08-16T11:40:09" 
  

8	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: 
/products/{product_id}/output_layers/{layer_name} endpoint of the API. 
This service accepts two additional path parameters: 
•	product_id: Unique product identifier (e.g.: product_id: 5) 
•	layer_name: The actual output layer we are interested in (e.g.: observed_flood_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 product output layers. 
o	Note, an overview of the product output layers can we found 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  
 For the example above (Myanmar / water_extent), the response looks like this: 
•	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 
  

9	API Specifications - Overview
 
API Specifications - Overview
 
GFM product output layer	Product data format	Endpoint (latest observation)
flood_extent	Product output layers - Raster data	
Raster data	<base-url>/v1/flood_extent/{roi-id}
reference_water_mask	Raster layer	<base-url>/v1/water_mask/{roi-id}
water_extent	Raster layer	<base-url>/v1/water_extent/{roi-id}
exclusion_mask	Raster layer	<base-url>/v1/exclusion_mask/{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}
sentinel-1_metadata	Vector data (GeoJSON)	<base-url>/v1/metadata/{roi-id}
sentinel-1_footprint	Vector data (GeoJSON)	<base-url>/v1/footprint/{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}
affected_landcover	Raster layer	<base-url>/v1/affected_landcover/{roi-id}



----
[[GFMS | [Home]]] - [[DATA ACCESS | [Data access]]]