REST API GFMS
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:
- 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 all the product output layers for a specific AOI
- how to retrieve a specific product output layer (e.g., water_extent)
API Endpoint
The API can be accessed at the following URL: • https://api.gfm.geoville.com/v1/ Currently, the API is divided into two namespaces. The AOI namespace can be used to get the area of interest (AOI) information. The products namespace offers endpoints to access the flood products / output layers. For the authentication the following token can be used: • Bearer Q8ajYGdedXVwtbqbkoHD4G1tTTja6PrXVxNgXnZTfL In the following use cases we will use the terms products and output layers. A product is a set of multiple output layers (e.g.: water_exten, flood_extent, …). In most cases, a product contains exactly eleven output layers.
5 Use Cases 1 – Get all available output layer types for flood products The first use case shows how to get a list of all available output layer types and a description. Therefore, please visit the /products/output_layer_types endpoint in the API documentation. • Step 1: Select the endpoint • Step 2: Press the “Try it out” button • Step 3: Enter the access token • Step 4: Click the “Execute” Button
As a result, the API endpoint provides a list of all available output layers, the type of the layer and description.
6 Use Case 2 – Get an Area of Interest (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
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}
