REST API GFMS
From MyDewetra World
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)
GFM's API can be accessed at the following URL:
https://api.gfm.geoville.com/v1/
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
Contents
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:
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.
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
In this tutorial the Myanmar AOI is used:
"aoi_id": "e289b746fa66c0bea2049a020aa38b0c9aacb8783c112117a9002ae035511bcb" "aoi_name": "Myanmar"
After finding out the aoi_id for Myanmar, another endpoint is used to get a list of all available products for this AOI.
Use Case 3 - Get all products for a specific AOI
This use case shows how to get a list of all the 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).
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: 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:
- 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
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.
In the example:
"product_id": 5 "product_time": "2019-08-16T11:40:09"
Use Case 4 - Retrieve a flood product
This use case describes how to access a specific output layer (in the example: the water extent layer).
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: Enter the extra parameters
- product_id: the unique product identifier (e.g.: product_id: 5)
- layer_name: the actual output layer the query is about (e.g.: the water 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 output layer
Please note that a comprehensive list of the paramaters defining the output layer is given 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
that, in the given example (Myanmar / water_extent) will look like:
* 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 | /v1/flood_extent/{roi-id} |
| reference_water_mask | Product output layers - Raster data | /v1/water_mask/{roi-id} |
| water_extent | Product output layers - Raster data | /v1/water_extent/{roi-id} |
| exclusion_mask | Product output layers - Raster data | /v1/exclusion_mask/{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} |
| affected_population | Product output layers - Raster data | /v1/affected_population/{roi-id} |
| affected_landcover | Product output layers - Raster data | /v1/affected_landcover/{roi-id} |
