Difference between revisions of "REST API GFMS"

Revision as of 13:43, 17 June 2021

[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:

• https://api.gfm.geoville.com/v1/

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}

[Home] - [Data access]