Introduction

The FEWS Web Mapping Service with time support is the FEWS implementation of the WMS-T OGC standard and is available since 2017.02. It allows requesting images for plots that have been configured in the FEWS grid display. The WMS version that is supported is version 1.3. The EPSG:3857 projection (WGS84 Web Mercator) is supported. A nice tool to get the bounding box for this projection is bboxfinder.

Every gridPlot that has been configured in the grid display configuration represents a WMS layer.

WMS Request methods

The available request methods with their supported parameters are described here.

GetCapabilties

Get the available gridPlots and times available for each gridPlot at the current server system time. GetCapabilties will return its content as XML by default. JSON is supported as well, which is more convenient for web development.

Vendor Request parameters

format (string, optional): Format of the response. Options are: application/xml or application/json. The default format is application/xml.
layers (string, optional, since 2019.02): the layerId of the plot for which the capabilities should be determined. Only one layerId is currently supported.
onlyHeaders (boolean, optional, since 2019.02): Get the capabilities without the times. The default is false.
forecastPeriod: By default only the current forecast will be returned by the GetCapabilities. To get other forecasts, a forecast period needs to be specified. When any forecasts are found, they will be returned as a layer with the plotId and external forecast time combined. For example: france_gfs_T_forecasts-2019-06-24T00:00:00Z. When requesting the capabilities with a forecast period, it is required to specify a layerId with the layers parameter.
- startForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ, since 2019.02): Start time of search period that looks for timeseries produced by forecasts that have their forecast time within this period.
- endForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ, since 2019.02): End time of search period that looks for timeseries produced by forecasts that have their forecast time within this period.
- forecastCount (integer, since 2019.02): Number of forecast runs to return when using start- and end- forecast time. Default is 1.
importFromExternalDataSource (boolean, optional, default=false, since 2020.01): apply seamless integration with the archive. Only valid when specifying a forecastPeriod (using startForecastTime, endForecastTime and forecastCount) and layers.

Response

XML or JSON response with all available gridPlots nested by gridPlotGroupds.

Example request

http://localhost:8080/FewsWebServices/wms?request=GetCapabilities&format=application/xml

Example xml response

<WMS_Capabilities xmlns="http://www.opengis.net/wms" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlink="http://www.w3.org/1999/xlink" xsi:schemaLocation="http://www.opengis.net/wms http://schemas.opengis.net/wms/1.3.0/capabilities_1_3_0.xsd" version="1.3.0">
	<Service>
		<Name>WMS</Name>
		<Title>
Delft-FEWS Web Mapping Service with time support (WMS-T)
</Title>
	</Service>
	<Capability>
		<Request>
			<GetCapabilities>
				<Format>application/xml</Format>
				<Format>application/json</Format>
			</GetCapabilities>
			<GetMap>
				<Format>image/png</Format>
			</GetMap>
		</Request>
		<Exception>
			<Format>XML</Format>
		</Exception>
		<Layer>
			<Title>Delft-FEWS Web Mapping Service layers</Title>
			<CRS>EPSG:3857</CRS>
			<BoundingBox CRS="EPSG:3857" maxx="20037508.342789" maxy="20037508.342789" minx="-20037508.342789" miny="-20037508.342789"/>
			<Layer>
				<Name>Satellite precipitation</Name>
				<Title>Satellite precipitation</Title>
				<Layer queryable="1">
					<Name>Precipitation GPM [mm]</Name>
					<Title/>
					<Dimension units="ISO8601" name="time">
2018-10-05T12:30:00Z,2018-10-05T13:00:00Z,2018-10-05T13:30:00Z,2018-10-05T14:00:00Z,2018-10-05T14:30:00Z,2018-10-05T15:00:00Z,2018-10-05T15:30:00Z
</Dimension>
				</Layer>
			</Layer>
		</Layer>
	</Capability>
</WMS_Capabilities>

Example JSON response

{
  "title" : "Loire Spatial Data Display",
  "layers" : [ {
    "name" : "Precipitation GPM [mm]",
    "title" : "",
    "groupName" : "Satellite precipitation",
    "groupTitle" : "Satellite precipitation",
    "times" : [ "2018-10-05T12:30:00Z", "2018-10-05T13:00:00Z", "2018-10-05T13:30:00Z", "2018-10-05T14:00:00Z", "2018-10-05T14:30:00Z", "2018-10-05T15:00:00Z", "2018-10-05T15:30:00Z" ]
  }
}

Example request for getting capabilities of multiple forecasts (since 2019.02).

http://localhost:8080/FewsWebServices/wms?request=GetCapabilities&layers=france_gfs_T_forecasts&forecastCount=10&startForecastTime=2019-06-01T00:00:00Z&endForecastTime=2019-08-01T00:00:00Z

The response will give a unique layer name per externalForecast. For example: france_gfs_T_forecasts-2019-07-01T00:00:00Z. The externalForecastTime will be set in the title of the layer.

<?xml version="1.0" encoding="UTF-8"?>
<WMS_Capabilities xsi:schemaLocation="http://www.opengis.net/wms http://schemas.opengis.net/wms/1.3.0/capabilities_1_3_0.xsd" xmlns="http://www.opengis.net/wms" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.3.0">
    <Service>
        <Name>WMS</Name>
        <Title>Delft-FEWS Web Mapping Service with time support (WMS-T)</Title>
    </Service>
    <Capability>
        <Request>
            <GetCapabilities>
                <Format>application/xml</Format>
                <Format>application/json</Format>
            </GetCapabilities>
            <GetMap>
                <Format>image/png</Format>
            </GetMap>
        </Request>
        <Exception>
            <Format>XML</Format>
        </Exception>
        <Layer>
            <Title>Delft-FEWS Web Mapping Service layers</Title>
            <CRS>EPSG:3857</CRS>
            <BoundingBox CRS="EPSG:3857" maxx="20037508.342789" maxy="20037508.342789" minx="-20037508.342789" miny="-20037508.342789"></BoundingBox>            
            <Layer>
                <Name>GFS Temperature Forecasts</Name>
                <Title></Title>
                <Layer queryable="1">
                    <Name>france_gfs_T_forecasts</Name>
                    <Title>GFS temperature forecasts France</Title>
                    <Layer queryable="1">
                        <Name>france_gfs_T_forecasts-2019-07-01T00:00:00Z</Name>
                        <Title>2019-07-01T00:00:00Z</Title>
                        <Dimension units="ISO8601" name="time">2019-07-01T00:00:00Z,2019-07-01T03:00:00Z,2019-07-01T06:00:00Z,2019-07-01T09:00:00Z,2019-07-01T12:00:00Z,2019-07-01T15:00:00Z,2019-07-01T18:00:00Z,2019-07-01T21:00:00Z,2019-07-02T00:00:00Z,2019-07-02T03:00:00Z,2019-07-02T06:00:00Z,2019-07-02T09:00:00Z,2019-07-02T12:00:00Z,2019-07-02T15:00:00Z,2019-07-02T18:00:00Z,2019-07-02T21:00:00Z,2019-07-03T00:00:00Z,2019-07-03T03:00:00Z,2019-07-03T06:00:00Z,2019-07-03T09:00:00Z,2019-07-03T12:00:00Z,2019-07-03T15:00:00Z,2019-07-03T18:00:00Z,2019-07-03T21:00:00Z,2019-07-04T00:00:00Z,2019-07-04T03:00:00Z,2019-07-04T06:00:00Z,2019-07-04T09:00:00Z,2019-07-04T12:00:00Z,2019-07-04T15:00:00Z,2019-07-04T18:00:00Z,2019-07-04T21:00:00Z,2019-07-05T00:00:00Z,2019-07-05T03:00:00Z,2019-07-05T06:00:00Z,2019-07-05T09:00:00Z,2019-07-05T12:00:00Z,2019-07-05T15:00:00Z,2019-07-05T18:00:00Z,2019-07-05T21:00:00Z,2019-07-06T00:00:00Z,2019-07-06T03:00:00Z,2019-07-06T06:00:00Z,2019-07-06T09:00:00Z,2019-07-06T12:00:00Z,2019-07-06T15:00:00Z,2019-07-06T18:00:00Z,2019-07-06T21:00:00Z,2019-07-07T00:00:00Z,2019-07-07T03:00:00Z,2019-07-07T06:00:00Z,2019-07-07T09:00:00Z,2019-07-07T12:00:00Z,2019-07-07T15:00:00Z,2019-07-07T18:00:00Z,2019-07-07T21:00:00Z,2019-07-08T00:00:00Z,2019-07-08T03:00:00Z,2019-07-08T06:00:00Z,2019-07-08T09:00:00Z,2019-07-08T12:00:00Z,2019-07-08T15:00:00Z,2019-07-08T18:00:00Z,2019-07-08T21:00:00Z,2019-07-09T00:00:00Z,2019-07-09T03:00:00Z,2019-07-09T06:00:00Z,2019-07-09T09:00:00Z,2019-07-09T12:00:00Z,2019-07-09T15:00:00Z,2019-07-09T18:00:00Z,2019-07-09T21:00:00Z,2019-07-10T00:00:00Z,2019-07-10T03:00:00Z,2019-07-10T06:00:00Z,2019-07-10T09:00:00Z,2019-07-10T12:00:00Z,2019-07-10T15:00:00Z,2019-07-10T18:00:00Z,2019-07-10T21:00:00Z,2019-07-11T00:00:00Z</Dimension>
                    </Layer>
                    <Layer queryable="1">
                        <Name>france_gfs_T_forecasts-2019-06-24T00:00:00Z</Name>
                        <Title>2019-06-24T00:00:00Z</Title>
                        <Dimension units="ISO8601" name="time">2019-06-24T00:00:00Z,2019-06-24T03:00:00Z,2019-06-24T06:00:00Z,2019-06-24T09:00:00Z,2019-06-24T12:00:00Z,2019-06-24T15:00:00Z,2019-06-24T18:00:00Z,2019-06-24T21:00:00Z,2019-06-25T00:00:00Z,2019-06-25T03:00:00Z,2019-06-25T06:00:00Z,2019-06-25T09:00:00Z,2019-06-25T12:00:00Z,2019-06-25T15:00:00Z,2019-06-25T18:00:00Z,2019-06-25T21:00:00Z,2019-06-26T00:00:00Z,2019-06-26T03:00:00Z,2019-06-26T06:00:00Z,2019-06-26T09:00:00Z,2019-06-26T12:00:00Z,2019-06-26T15:00:00Z,2019-06-26T18:00:00Z,2019-06-26T21:00:00Z,2019-06-27T00:00:00Z,2019-06-27T03:00:00Z,2019-06-27T06:00:00Z,2019-06-27T09:00:00Z,2019-06-27T12:00:00Z,2019-06-27T15:00:00Z,2019-06-27T18:00:00Z,2019-06-27T21:00:00Z,2019-06-28T00:00:00Z,2019-06-28T03:00:00Z,2019-06-28T06:00:00Z,2019-06-28T09:00:00Z,2019-06-28T12:00:00Z,2019-06-28T15:00:00Z,2019-06-28T18:00:00Z,2019-06-28T21:00:00Z,2019-06-29T00:00:00Z,2019-06-29T03:00:00Z,2019-06-29T06:00:00Z,2019-06-29T09:00:00Z,2019-06-29T12:00:00Z,2019-06-29T15:00:00Z,2019-06-29T18:00:00Z,2019-06-29T21:00:00Z,2019-06-30T00:00:00Z,2019-06-30T03:00:00Z,2019-06-30T06:00:00Z,2019-06-30T09:00:00Z,2019-06-30T12:00:00Z,2019-06-30T15:00:00Z,2019-06-30T18:00:00Z,2019-06-30T21:00:00Z,2019-07-01T00:00:00Z,2019-07-01T03:00:00Z,2019-07-01T06:00:00Z,2019-07-01T09:00:00Z,2019-07-01T12:00:00Z,2019-07-01T15:00:00Z,2019-07-01T18:00:00Z,2019-07-01T21:00:00Z,2019-07-02T00:00:00Z,2019-07-02T03:00:00Z,2019-07-02T06:00:00Z,2019-07-02T09:00:00Z,2019-07-02T12:00:00Z,2019-07-02T15:00:00Z,2019-07-02T18:00:00Z,2019-07-02T21:00:00Z,2019-07-03T00:00:00Z,2019-07-03T03:00:00Z,2019-07-03T06:00:00Z,2019-07-03T09:00:00Z,2019-07-03T12:00:00Z,2019-07-03T15:00:00Z,2019-07-03T18:00:00Z,2019-07-03T21:00:00Z,2019-07-04T00:00:00Z</Dimension>
                    </Layer>
                </Layer>
            </Layer>
        </Layer>
    </Capability>
</WMS_Capabilities>

GetMap

Get the plot image as png for a layer for a requested time, image size and extent. Only untiled images are supported, which means the complete image has to be requested for the complete extent.

Request parameters

layers (required): the layerId of the plot to display. Only one layerid is supported.
time (required): the time for which the grid has to be plotted. Only one time is supported. Time ranges are NOT supported. Time has to be in the xml dateformat: yyyy-MM-ddTHH:mm:ssZ. The times returned by the GetCapabilities are in this format as well.
width (optional): width of the image. Default is 800.
height (optional): height of the image. Default is 600
version (optional): supported version is 1.3 and is the default if not set. Older versions might work, but are not supported
crs (required): the output projection of the plot. Only supported projection is: EPSG:3857
bbox (required): the bounding box (in the projection as defined by the SRS parameter) of the extent that should be plot

Vendor request parameters

showContours (optional, since 2018.02): Display contour lines if enabled in the gridplot. Default is false. Set to true to show contour lines.
externalForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ, since 2019.02): get the map for a specific forecast time.
importFromExternalDataSource (boolean, optional, default=false, since 2020.01): apply seamless integration with the archive. Only valid for external forecasts. Both an externalForecast time and layers have to be specified as well.

Restrictions:

The product of width and height is limited to the full HD resolution of 1920x1200 to avoid memory issues. In case a GetMap request is done where WIDTH*HEIGHT > 2304000 a bad request error will be returned.

Response

Transparent PNG image of the requested gridPlot for the specified timeStep, size and extent.

Example request

http://localhost:8080/FewsWebServices/wms?service=WMS&request=GetMap&version=1.3&layers=Temp_forecast_nwp&crs=EPSG%3A3857&time=2018-09-01T00%3A00%3A00.000Z&width=920&height=500&bbox=-1261269.140637805,4786137.922323937,1921144.283455659,6515710.435418212

Example png response

Example request for a specific forecast using externalForecastTime and layers

http://localhost:8080/FewsWebServices/wms?request=GetMap&version=1.3&externalForecastTime=2019-07-01T00:00:00Z&layers=france_gfs_T_forecasts&crs=EPSG%3A3857&time=2019-07-01T12:00:00Z&width=920&height=500&bbox=-1416930.666816287,5052492.089340451,1765482.757277179,6782064.602434729

Example request for a specific forecast using a layer name with external forecast time embedded in the layer name.

http://localhost:8080/FewsWebServices/wms?request=GetMap&version=1.3&layers=france_gfs_T_forecasts-2019-06-24T00:00:00Z&crs=EPSG%3A3857&time=2019-07-01T12:00:00Z&width=920&height=500&bbox=-1416930.666816287,5052492.089340451,1765482.757277179,6782064.602434729

GetLegendGraphic

Get the legend image as png for a specified gridPlotId.

Request parameters

layers (required): the gridPlotId of the gridPlot which legend should be displayed. Only one gridPlotId is supported.
width (optional): width of the legend. Default is 150.
height (optional): height of the image. The default is based on the number of legend items, 15 pixels per item.

Response

Transparent PNG image of the requested legend graphics for the specified gridPlotId and size.

Example request

http://localhost:8181/FewsWebServices/wms?SERVICE=WMS&REQUEST=GetLegendGraphic&LAYERS=Precipitation%20GPM%20%5Bmm%5D&WIDTH=150&HEIGHT=400

Example png response

Properties

The following WMS specific properties can be configured in the FewsPiService.properties file. For more information on properties, see: FEWS Web Services configuration FewsPiService.properties

WMS_BASE_URL (string): url that will be reported in the GetCapabilities response as URL to be used to request maps.
WMS_CLIENT_CACHE_TIMEOUT (integer): Timeout of the cache in seconds, that is sent to the browser. default is 300 seconds (15 minutes). To disable caching, set the timeout to 0.
WMS_ALLOWED_GRID_PLOT_GROUP_ID (string): Id of the grid plot group which layers will be made available in the WMS service. If not configured, all layers are available.
WMS_IMAGE_MAX_WIDTH_HEIGHT (integer): The maximum size of the WIDTH and HEIGHT product GetMap parameters. The default is set to 2304000 (the full HD resolution of 1920x1200). N.B.: The higher this value is set, the more memory is required to generated the WMS images.
WMS_MAX_NUMBER_OF_CACHED_LAYERS (integer, since 2019.02): The maximum number of layers that are cached in the WMS services. The default is 100. The optimal number depends on the amount of memory available and the number of configured layers and the size of the layers. When the WMS runs into Out Of Memory issues, the size of the number should be lowered or the memory increased.

ICT requirements

For general FewsWebServices requirements, see: Installation

Specific requirements for the FEWS WMS service very much depend on the number of layers that are used and the size of the layer grids. To avoid memory issues the number of layers should be restricted by specifying the WMS_ALLOWED_GRID_PLOT_GROUP_ID property.

The tomcat server the WMS service is running on should have sufficient memory. When many concurrent users are using the WMS service the CPU requirements will increase as well since all images have to be rendered at the same time on the same server. It is recommended to start at least with 2GByte of memory with the -Xmx2G JVM parameter.

Since the WMS service is stateless, it can be scaled both vertically (more cpu and memory) and horizontally (more tomcat instances).

Tomcat itself can also be tuned by specifying the number of concurrent requests. In case memory errors occur, the tomcat server.xml can be tuned to limit the number of concurrent requests. In the tomcat server.xml the maxThreads parameter specifies the maximum number of concurrent requests that are allowed. For Tomcat 7 this is set to 200 by default, which is quite a lot for a WMS service. See the following example where the tomcat server.xml has been configured with a maximum of 50 threads.

<Connector port="8080" maxThreads="50" minSpareThreads="10" maxSpareThreads="20"
               enableLookups="false" redirectPort="4443" acceptCount="100"
               debug="0" connectionTimeout="60000" 
               disableUploadTimeout="true" />

Page tree

FEWS Web Mapping Service with time support (WMS-T)

Introduction

WMS Request methods

GetCapabilties

Vendor Request parameters

Response

Example request

Example xml response

Example JSON response

GetMap

Request parameters

Vendor request parameters

Restrictions:

Response

Example request

Example png response

Example request for a specific forecast using externalForecastTime and layers

Example request for a specific forecast using a layer name with external forecast time embedded in the layer name.

GetLegendGraphic

Request parameters

Response

Example request

Example png response

Properties

ICT requirements