...
The available request methods with their supported parameters are described here.
...
GetCapabilities
Get the available gridPlots and times available for each gridPlot at the current server system time. GetCapabilties GetCapabilities will return its content as XML by default. JSON is supported as well, which is more convenient for web development.
...
Code Block |
---|
{ "title" : "Spatial Display", "layers" : [ { "name" : "giss_e2_h_grid_monthly_historical_nat", "title" : "Goddard NASA historical Natural surface temperature", "groupName" : "Goddard NASA Monthly Historical Grids", "keywordList" : [ { "parameterId" : "T.hindcast.mean.global.historicalNat", "locationId" : "giss_e2_h_grid", "moduleInstanceId" : "ImportForecastGissE2HHistoricalNatGrid", "timeSeriesType" : "EXTERNAL_FORECASTING", "forecastTime" : "1850-01-16T12:00:00Z" } ], "timesDefault" : "1850-12-16T12:00:00Z", "times" : [ "1850-01-16T12:00:00Z", "1850-02-15T00:00:00Z", "1850-03-16T12:00:00Z", "1850-04-16T00:00:00Z", "1850-05-16T12:00:00Z", "1850-06-16T00:00:00Z", "1850-07-16T12:00:00Z", "1850-08-16T12:00:00Z", "1850-09-16T00:00:00Z", "1850-10-16T12:00:00Z", "1850-11-16T00:00:00Z", "1850-12-16T12:00:00Z" ] } ] } |
Example request for getting capabilities of multiple forecasts (since 2019.02).
...
Code Block | ||||
---|---|---|---|---|
| ||||
<Layer queryable="1"> <Name>kzn_temperature</Name> <Title>Temperature</Title> <KeywordList> <Keyword>parameterId=water_temperature</Keyword> <Keyword>locationId=SigmaLayer_0</Keyword> <Keyword>moduleInstanceId=kzn</Keyword> <Keyword>timeSeriesType=EXTERNAL_HISTORICAL</Keyword> </KeywordList> <Dimension units="ISO8601" name="time">2010-04-15T00:00:00Z,2010-04-15T01:00:00Z,2010-04-15T02:00:00Z,2010-04-15T03:00:00Z,2010-04-15T04:00:00Z,2010-04-15T05:00:00Z,2010-04-15T06:00:00Z,2010-04-15T07:00:00Z,2010-04-15T08:00:00Z,2010-04-15T09:00:00Z,2010-04-15T10:00:00Z,2010-04-15T11:00:00Z,2010-04-15T12:00:00Z,2010-04-15T13:00:00Z,2010-04-15T14:00:00Z,2010-04-15T15:00:00Z,2010-04-15T16:00:00Z,2010-04-15T17:00:00Z,2010-04-15T18:00:00Z,2010-04-15T19:00:00Z,2010-04-15T20:00:00Z,2010-04-15T21:00:00Z,2010-04-15T22:00:00Z,2010-04-15T23:00:00Z,2010-04-16T00:00:00Z</Dimension> <Dimension units="water_depth" name="elevation">10.453057/3432.3235</Dimension> <Style> <Name>Class.Temperature</Name> <Title>Temperature Style</Title> </Style> <Style> <Name>Class.Temperature.Extreme</Name> <Title>Extreme Temperature Style</Title> </Style> </Layer> |
Get
...
Capabilities Elevation dimension (2020.02)
For 3D grids the GetCapabilities can report the elevation as a dimension. In case there are any sigma layers or z-layers in the configured grid display plot, the elevation dimension will be specified by the lower and upper values seperated separated by a backslash. For example: 1010.453057/3432.3235. The name attribute of the dimension is set to "elevation". An example of an elevation dimenstion dimension is as follows:
Code Block |
---|
<Dimension units="water_depth" name="elevation">10.453057/3432.3235</Dimension> |
Get
...
Capabilities default time (2021.01)
For all layers a default time is no reported. This default time will be used by the Get Map when no time parameter is used. See the following example where the default time is set to the last time step.
...
Code Block |
---|
"timesDefault" : "2019-07-11T00:00:00Z", "times" : [ "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" ] |
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, optional since 2021.01): 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. Since 2020.02 milliseconds are supported as well in the format: yyyy-MM-ddTHH:mm:ss.sssZ. Since 2021.01 the default time as reported by the GetCapabilities will be used if no time parameter was specified.
- elevation (optional, since 2020.02): for 3d grids an elevation can be specified. The elevations should be inside the range as reported by the GetCapabilities.
- 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.
- styles (optional, since 2020.02 ): a style can be passed as request parameter by passing the styles parameter. N.B. only one style can currently be passed to the GetMap request. For example: styles=Class.Temperature.Extreme. Available styles are reported by GetCapabilities per layer.
- format (optional, image/png is the default): image/png or image/tiff is supported. Image tiff is only supported for wind layers using u and v time series in combination with the following vendor parameters: convertUVtoRG or convertMagnitudeDirectiontoRG.
Vendor specific request parameters
Get Capabilities boundingBox (2023.01)
For all layers the extents is reported as a BoundingBox element is reported based on the default extent that applies to a layer. The coordinates are always in EPSG:3857, also known as Web Mercator.
Code Block |
---|
<CRS>EPSG:3857</CRS>
<BoundingBox CRS="EPSG:3857" maxx="0.00161697" maxy="15028132.47295554" minx="-20037508.34278924" miny="-0.00071121"></BoundingBox> |
In JSON the boundingBox property is used:
Code Block |
---|
"boundingBox" : {
"crs" : "EPSG:3857",
"minx" : "-20037508.34278924",
"maxy" : "15028132.47295554",
"maxx" : "0.00161697",
"miny" : "-0.00071121"
} |
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, optional since 2021.01): 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. Since 2020.02 milliseconds are supported as well in the format: yyyy-MM-ddTHH:mm:ss.sssZ. Since 2021.01 the default time as reported by the GetCapabilities will be used if no time parameter was specified.
- elevation (optional, since 2020.02): for 3d grids an elevation can be specified. The elevations should be inside the range as reported by the GetCapabilities.
- 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. You can find your bbox at http://bboxfinder.com/
- styles (optional, since 2020.02 ): a style can be passed as request parameter by passing the styles parameter. N.B. only one style can currently be passed to the GetMap request. For example: styles=Class.Temperature.Extreme. Available styles are reported by GetCapabilities per layer.
- format (optional, image/png is the default): image/png or image/tiff is supported. Image tiff is only supported for wind layers using u and v time series in combination with the following vendor parameters: convertUVtoRG or convertMagnitudeDirectiontoRG.
Vendor specific 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 (optional, dateTime: yyyy-MM-ddTHH:mm:ssZ, since 2019.02): get the map for a specific forecast time. If omitted the latest/current forecast is returned
- 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.
- ensembleId (optional).
- showContours (optional, since 2018.02): Display contour lines if enabled in the gridplot. Default is false. Set to true to show contour lines.
- externalForecastTime (optional, dateTime: yyyy-MM-ddTHH:mm:ssZ, since 2019.02): get the map for a specific forecast time. If omitted the latest/current forecast is returned
- 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.
- ensembleId (optional). Since 2020.01. Specify the ensemble id of the requested grid. When using this parameter, specifying the ensembleMemberId is required as well. The available ensembleId is reported by the GetCapabilities request.
- ensembleMemberId (optional). Since 2020.01. Specify the ensemble member id of the requested grid. When using this parameter, specifying the ensembleId is required as well. The available ensembleMemberIds are reported by the GetCapabilities request.
- dim_ensemble_member (otpionaloptional). Since 2020.01. This parameter can be used instead of the ensembleId and ensembleMemberId parameters and follow the recommendations in: https://docs.opengeospatial.org/bp/16-086r3/16-086r3.html#23. This parameter can be used to pass both the ensembleId and ensembleMemberId separated by a underscore. For example: dim_ensemble_member=MOSurge_1
- colorscalerange colorScaleRange (optional, since 2020.02): rescale the colors in the map by changing the min and max values of the range. The minimum value and maximum value are separated by a comma, For example: colorscalerange=2.0,10.0. This option can be used for legends as well. convertUVtoRG It is best to also use this parameter together with useDisplayUnits.
- useDisplayUnits (optional, boolean, default = false): Specifies whether display units (true) or system units (false) are assumed for the provided colorScaleRange.
- convertUVtoRG (optional, default = false, , since 2021.02): Only supported in combination with format=image/tiff for wind layers using u and v time series sets. The u and v values will be stored in the R and G values of a TIFF image. The alpha channel is set to 255 if the pixel maps to a grid value. If the pixel is outside the grid, the alpha channel is set to 0. The scales and offsets are stored in geo tiff tags: ModelPixelScaleTag ModelPixelScaleTag (first double contains the scale for u values, the second double contains the scale for v values) and ModelTiepointTag and ModelTiepointTag (first double contains the offset for u values, the second double contains the offset for v values). To calculate the u an v values the pixel values for R and G channels should be multiplied by the scale value and the offet offset should be added. For example. The R value of a pixel in the TIFF value has value: 200, the u scale = 0.1 and the u offset is 1.0. The u value = 200*0.1 + 1.0 = 21.0. A missing value is indicated by setting the R and G value to 255.
- convertMagnitudeDirectiontoRG (optional, default = false, planned for 2021.02): not implemented yet.
...
Transparent PNG image of the requested legend graphics for the specified gridPlotId and size.
Example request:
Code Block |
---|
http://localhost:8080/FewsWebServices/wms?SERVICE=WMS&REQUEST=GetLegendGraphic&LAYERS=Precipitation%20GPM%20%5Bmm%5D&WIDTH=150&HEIGHT=400 |
Example png response
Response in JSON with style
The following example requests a legend in json format and applies a style as well.
Code Block |
---|
http://localhost:8080/FewsWebServices/wms?SERVICE=WMS&REQUEST=GetLegendGraphic&LAYERS=Precipitation%20GPM%20%5Bmm%5D&WIDTH=150&HEIGHT=400
|
Example png response
://localhost:8080/FewsWebServices/wms?SERVICE=WMS&request=GetLegendGraphic&layers=kzn_temperature&format=application/json&style=Class.Temperature.Extreme |
The json response is as follows:
Code Block |
---|
{
"unit" : "Celsius",
"legend" : [ {
"lowerValue" : 0.0,
"color" : "#042333"
}, {
"lowerValue" : 10.0,
"color" : "#3c0912"
}, {
"lowerValue" : 20.0,
"color" : "#730e27"
}, {
"lowerValue" : 30.0,
"color" : "#a62225"
}, {
"lowerValue" : 40.0,
"color" : "#c0583b"
}, {
"lowerValue" : 50.0,
"color" : "#d08b73"
}, {
"lowerValue" : 60.0,
"color" : "#dfbcb0"
}, {
"lowerValue" : 70.0,
"color" : "#f1edec"
} ]
} |
Response in JSON with style and colorscalerangeResponse in JSON with style
The following example requests a legend in json format and applies a style and applies a colorscale range as well.
Code Block |
---|
http://localhost:8080/FewsWebServices/wms?SERVICE=WMS&request=GetLegendGraphic&layers=kzn_temperature&format=application/json&style=Class.Temperature.Extreme&colorscalerange=30.0,50.0 |
The json response is as follows::
Code Block |
---|
{
"unit" : "Celsius",
"legend" : [ {
"lowerValue" : 30.0,
"color" : "#042333"
}, {
"lowerValue" : 32.9,
"color" : "#3c0912"
}, |
Code Block |
{ "legend" : [ { "lowerValue" : 035.07, "color" : "#042333#730e27" }, { "lowerValue" : 1038.06, "color" : "#3c0912#a62225" }, { "lowerValue" : 2041.04, "color" : "#730e27#c0583b" }, { "lowerValue" : 3044.03, "color" : "#a62225#d08b73" }, { "lowerValue" : 4047.01, "color" : "#c0583b#dfbcb0" }, { "lowerValue" : 50.0, "color" : "#f1edec" } "lowerValue" : 50.0, "color" : "#d08b73" }, { "lowerValue" : 60.0, "color" : "#dfbcb0" }, { "lowerValue" : 70.0, "color" : "#f1edec" } ] } |
Response in JSON with style and colorscalerange
The following example requests a legend in json format and applies a style and applies a colorscale range as well.
Code Block |
---|
http://localhost:8080/FewsWebServices/wms?SERVICE=WMS&request=GetLegendGraphic&layers=kzn_temperature&format=application/json&style=Class.Temperature.Extreme&colorscalerange=30.0,50.0 |
The json response is as follows:
]
} |
GetVersion (2022.01)
GET version inforamtion of the current installed Web Services.
Request parameters
- documentFormat (string): PI_XML (default) or PI_JSON
Response
- PI-XML or PI-JSON file content.
Example request
Code Block |
---|
curl "http://localhost:8080/FewsWebServices/wms?SERVICE=WMS&request=GetVersion"
|
Example PI-XML response
Code Block |
---|
<?xml version="1.0" encoding="UTF-8"?>
<Version xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews/PI" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_version.xsd">
<implementation>2017.02</implementation>
<buildType>stable</buildType>
<buildNumber>12345</buildNumber>
<buildTime>2017-10-31T23:00:00Z</buildTime>
</Version> |
GetOAS (2022.01)
GET open api specification of the WMS Service.
Response
- JSON response with the open api specification.
Example request
Code Block |
---|
curl "http://localhost:8080/FewsWebServices/wms?SERVICE=WMS&request=GetOAS"
|
Example PI-XML response
Code Block |
---|
{
"openapi" : "3.0.3",
"info" : {
"title" : "Delft-FEWS Web Services - WMS Service",
"description" : "Delft-FEWS Web Services - WMS Service",
"version" : ""
},
"servers" : [ {
"url" : "/FewsWebServices",
"description" : "API server |
Code Block |
{
"legend" : [ {
"lowerValue" : 30.0,
"color" : "#042333"
}, {
"lowerValue" : 32.9,
"color" : "#3c0912"
}, {
"lowerValue" : 35.7,
"color" : "#730e27"
}, {
"lowerValue" : 38.6,
"color" : "#a62225"
}, {
"lowerValue" : 41.4,
"color" : "#c0583b"
}, {
"lowerValue" : 44.3,
"color" : "#d08b73"
}, {
"lowerValue" : 47.1,
"color" : "#dfbcb0"
}, {
"lowerValue" : 50.0,
"color" : "#f1edec"
} ]
} |
WMS Test Page
Most functionality of the WMS service can be tested using the WMS service test page.
...
Downloading the same image as TIFF, will result in the following image: The Red channel is used for the U component of wind and the Green channel is used for the V component of wind.
Information about the offset and scale can be determined using GeoTIFF tags. The following is the meta information stored in the TIFF image, displayed with the tool jhove.
jhove.bat wms.tiff
This will report the following GeoTIFF properties:
GeoTIFFProperties:
ModelTiepointTag: -3.369999885559082, -6.0, 0.0, 0.0, 0.0, 0.0
ModelPixelScaleTag: 0.06125489994883537, 0.09243137389421463, 0.0
The ModelTiepointTag stores the offsets for the u and v values. Only the first two values are relevant. In this case the UOffset = -3.369999885559082 and the VOffset = -6.0.
...
The following WMS specific properties can be configured in the FewsPiService.properties file. For more information on properties, see: FEWS Web Services configuration Configuration FewsPiService.properties - deprecated since 2022.02
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. For 2020.01 the default is set to 10 million (The default before 2020.01 was 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, obsolete since 2020.01 since layers are no longer cached): 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.
- WMS_PRELOAD_CAPABILITIES (boolean, default false, since 2019.02): The first request to GetCapabilities might take long if a lot of grids are configured. To preload these grids on startup, the WMS_PRELOAD_CAPABILITIES can be set to true. This will make the first request to GetCapabilities fast as well.
...