REST API GFMS

From MyDewetra World
Revision as of 13:44, 17 June 2021 by Admin (talk | contribs)

Jump to: navigation, search
caption

[Home] - [Data access]


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:

  1. how to get a list of all available product output layers together with their description
  2. how to get a full list of the available product output layers for a specific AOI (e.g., Myanmar)
  3. how to get all the [[[PRODUCTS | product output layers]] for a specific AOI
  4. 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:

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:

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 Ep product1.jpg
  • Step 2: Press the Try it out button Ep product2.jpg
  • Step 3: Enter the access token
  • Step 4: Click the “Execute” Button Ep product3.jpg

As a result, the API endpoint provides a list of all available output layers, the type of the layer and description:

Ep product4.jpg

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}



[Home] - [Data access]