Difference between revisions of "REST API GFMS"

# 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]])   

* [https://api.gfm.geoville.com/v1/  https://api.gfm.geoville.com/v1/]

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

==='''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>

* Step 1: Select the endpoint  [[File: ep_product0.jpg | 500px]]

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)  

• 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  

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}