Locations file

This page follows the reference format: a quick summary, a copy-paste example, the patterns you’ll actually use, then the complete field reference generated straight from the schema — so it can’t drift from the real grammar.

At a glance

Purpose : Declares the locations — gauges, reservoirs, catchments, grid points — that every time series is attached to. The “where” of your data model.

Folder : Config/RegionConfigFiles/

Root element : <locations>

Depends on : Nothing — locations are foundational nouns. Other files (parameters, imports, filters) refer to location IDs declared here.

Minimal example

Config/RegionConfigFiles/Locations 1.00 default.xml

<?xml version="1.0" encoding="UTF-8"?>
<locations xmlns="http://www.wldelft.nl/fews" version="1.1">
  <geoDatum>WGS 1984</geoDatum>
  <location id="RiverGauge_01" name="River Gauge at Town Bridge">
    <shortName>TownBr</shortName>
    <x>4.895</x>
    <y>52.370</y>
    <z>2.0</z>
  </location>
</locations>

geoDatum is required and fixes what x/y mean; each location needs a unique id and x/y. Everything else is optional.

Common patterns

• Group locations under a parent with parentLocationId — children are auto-selected with the parent in the Explorer. Good for “a station and its sub-sensors.”
• Time-limit a location with visibilityPeriod so decommissioned sites drop out of the UI after a date instead of being deleted.
• Build big location lists from data, not by hand — for hundreds of gauges, define them in a CSV or shapefile and load them via a location set rather than writing each <location>.

Tip

For large systems you rarely maintain a giant Locations file directly — you keep the attributes in a CSV/shapefile and let a location set read them. The <location> grammar below is still what each row resolves to.

Field reference

Auto-generated from locations.xsd. Descriptions are the schema's own annotations.

Element <locations>

Attributes

Attribute	Use	Notes
version	required	fixed: 1.1.

Elements

Element	Type	Cardinality	Description
timeZone	timeZoneStringType	optional	Optional time zone for dates and times defined in this configuration file. If no time zone is defined, then dates and times are in GMT.
geoDatum	geoDatumStringType	required
location	LocationComplexType	required · repeats

LocationComplexType

points which a times series can exists. The point is represented by X, Y and Z coordinates. Each location element of a time series location file corresponds to a time series data file and consist of four elements.

Attributes

Attribute	Use	Notes
id	required
name	optional

Elements

Element	Type	Cardinality	Description
description	string	optional	Long (descriptive) name of location (tool tip) or description
shortName	string	optional	Short name of location for chart legend
label	string	optional	Label to be displayed on the map in FewsExplorer. Besides the global properties you can use the following tags %ID%, %NAME%, et cetera (similar to toolTip)
toolTip	string	optional	Tooltip to be displayed in the FewsExplorer. You can use use \n or CDATA or HTML when you need multiple lines. Besides the global properties you can use the following tags %ID%, %NAME%, %DESCRIPTION%, %LAST_VALUE%, %LAST_VALUE_TIME%, %FORECAST_START_TIME%, %MAXIMUM_VALUE%, %MAXIMUM_VALUE_TIME% The tooltip supports html including images and hyperlinks. The url in the hyper link can be an internet url, an executable file, a document file, or a folder. Use the CDATA xml tag to include html in a xml file. By default the following tool tip is used. ID: %ID%\n Name: %NAME%\n Desc: " + "%DESCRIPTION%\n Last value [%LAST_VALUE%] Time [%LAST_VALUE_TIME%]\n Forecast Start Time [%FORECAST_START_TIME%]\n Maximum [%MAXIMUM_VALUE%] Time [%MAXIMUM_VALUE_TIME%]
parentLocationId	string	optional	When a location has a parent id it is an invisible child location. All the children of a location are automatically selected in the fews explorer
visibilityPeriod	LocationVisibilityPeriodComplexType	optional	Optional period for which this location is visible in the user interface. The start and the end of the period are inclusive. If not defined, then this location is visible for all times.
x	double	required	X coordinate of the point (Easting)
y	double	required	Y coordinate of the point (Northing)
z	double	optional	Z coordinate of the point (altitude)
bedLevel	double	optional	Since 2020.02
layerSigmaCoordinate	sigmaCoordinateDouble	optional	Since 2017.02. When this location represents a sigma layer

LocationVisibilityPeriodComplexType

Element	Type	Cardinality	Description
startDateTime	DateTimeComplexType	optional	The start date time of the period for which this location is visible in the user interface. Start date time is inclusive. If start date time not defined, then visible for all times before end date time.
endDateTime	DateTimeComplexType	optional	The end date time of the period for which this location is visible in the user interface. End date time is inclusive. If end date time not defined, then visible for all times after start date time.

DateTimeComplexType

Attributes

Attribute	Use	Notes
date	required
time	optional

Gotchas

• Duplicate ids silently break references — IDs must be unique across the file. FEWS keys locations by id.
• Missing geoDatum or coordinates in the wrong datum put your locations in the wrong place on the map. geoDatum is not optional.
• A higher-versioned sibling wins. If edits aren’t taking effect, look for Locations 1.01 default.xml next to your file — see how FEWS finds a file.
• Referencing an undeclared id elsewhere (an import or filter pointing at a locationId not defined here) fails to resolve. Declare the location first.

See also

• Task guide: Define locations & location sets
• Concept: The configuration directory
• Schema: locations.xsd