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 [[[PRODUCTS | product output layers]] for a specific AOI
- how to retrieve a specific [[ product output layer (e.g., water_extent)
API Endpoint
GFM's API can be accessed at the following URL:
Currently, the API is divided into two namespaces:
- the AOI 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 this manual will make of use the terms products and output layers:
- an output layer is one of the eleven products delivered by the service
- a product is the full set of all the 11 flood-related layers
API Use Cases
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
- 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}
