1.1   Links to WMS-Related Information

• MapServer WMS Server howto
• MapServer WMS Client howto
• WMS 1.1.1 specification
• MapServer OGC Web Services Workshop

2.1   Time Patterns

WMS specifies that the basic format used for TIME requests is based on the ISO 8601:1988(E) "extended" format. MapServer supports a limited set of patterns that are defined in the ISO 8601 specifications, as well as few other patterns that are useful but not compliant to ISO 8601. Here is a list of patterns currently supported:

Table 1. Supported Time Patterns

2.2   Setting Up a WMS Layer with Time Support

To have a valid WMS layer with time support, the user has to define the following metadata at the layer level:

• wms_timeextent: (Mandatory) this is used in the capabilities document to return the valid time values for the layer. The value defined here should be a valid time range. (more on this in 'Specifying Time Extents' below)
• wms_ timeitem: (Mandatory) this is the name of the field in the DB that contains the time values.
• wms_timedefault: (Optional) this value is used if it is defined and the TIME value is missing in the request.

LAYER
  NAME earthquakes
  METADATA
    "wms_title"    "Earthquakes"
    "wms_timeextent" "2004-01-01/2004-02-01"
    "wms_timeitem" "TIME"
    "wms_timedefault" "2004-01-01 14:10:00"
  END
  TYPE POINT
  STATUS ON
  DATA quakes
  CLASS
    ..
  END
END

2.3   GetCapabilities Output

If your layer is set up properly, requesting the capabilities on the server outputs a Dimension element. Here is an example of a GetCapabilities result for a layer configured for time support:

<Layer queryable="0" opaque="0" cascaded="0">
    <Name>earthquakes</Name>
    <Title>Earthquakes</Title>
    <SRS>EPSG:4326</SRS>
    <LatLonBoundingBox minx="-131.02" miny="24.84" maxx="-66.59" maxy="48.39" />
    <BoundingBox SRS="EPSG:4326"
                minx="-131.02" miny="24.84" maxx="-66.59" maxy="48.39" />
    <Dimension name="time" units="ISO8601"/>
    <Extent name="time" default="2004-01-01 14:10:00" nearestValue="0">2004-01-01/2004-02-01</Extent>
</Layer>            

2.4   Supported Time Requests

When sending a request with the TIME parameter, different types of time values can be specified. The following are supported by MapServer:

• single value: for example: ...&TIME=2004-10-12&...
• multiple values: for example: ...&TIME=2004-10-12, 2004-10-13, 2004-10-14&...
• single range value: for example: ...&TIME=2004-10-12/2004-10-13&...
• multiple range values: for example: ...&TIME=2004-10-12/2004-10-13, 2004-10-15/2004-10-16&...

2.5   Interpreting Time Values

When MapServer receives a request with a TIME parameter, it transforms the time requests into valid expressions that are assigned to the filter parameter on layers that are time-aware. Here are some examples of how different types of requests are treated (wms_timeitem is defined here as being "time_field"):

• single value (2004-10-12) transforms to (`[time_field]` eq `2004-10-12`)
• multiple values (2004-10-12, 2004-10-13) transform to (`[time_field]` eq `2004-10-12` OR `[time_field]` eq `2004-10-13`)
• single range : 2004-10-12/2004-10-13 transforms to ((`[time_field]` ge `2004-10-12`) AND (`[time_field]` le `2004-10-13`))
• multiple ranges (2004-10-12/2004-10-13, 2004-10-15/2004-10-16) transform to ((`[time_field]` ge `2004-10-12` AND `[time_field]` le `2004-10-13`) OR (`[time_field]` ge `2004-10-15` AND `[time_field]` le `2004-10-16`))

As shown in the above examples, all fields and values are written inside back tics (`) - this is the general way of specifying time expressions inside MapServer.

Exceptions to this rule:

1. When dealing with layers that are not Shapefiles nor through OGR, the expression built has slightly different syntax. For example, the expression set in the filter for the first example above would be ([time_field] = '2004-10-12').
2. For PostGIS layers, the time expression built uses the date_trunc function available in PostgreSQL. For example, if the user passes a time value of '2004-10-12', the expression set in the filter is date_trunc('day', time_field) = '2004-10-12'. The use of the date_trunc function allows requests to use the concept of time resolution. In the example above, for a request of '2004-10-12', MapServer determines that the resolution is "day" by parsing the time string and the result gives all records matching the date 2004-10-12 regardless of the values set for Hours/Minutes/Seconds in the database. For more information on the date_trunc function, please refer to the PostgreSQL documentation.

2.6   Limiting the Time Formats to Use

The user has the ability to define the time format(s) to be used when a request is sent, in metadata at the WEB level. For example, the user can define the following two formats:

"wms_timeformat" "YYYY-MM-DDTHH, YYYY-MM-DDTHH:MM"  

Another example is for a WMS layer that is based on time data that contains precise time values taken every minute (e.g., 2004-10-12T13:55, 2004-10-12T13:56, 2004-10-12 T13:57, ...). Normally, a valid request on such a layer would require the time value to be as complete as the data underneath. By defining a set of patterns to use, MapServer introduces the notion of resolution to be used when doing a query. Using the example above, a request TIME= 2004-10-12T13:55 would be valid and a request TIME= 2004-10-12T13 would also be valid and would return all elements taken for that hour.

Note that this functionality is only available on layers based on Shapefiles and OGR.

2.7   Example of WMS-T with PostGIS Tile Index for Raster Imagery

This example currently requires latest 4.9 CVS build!

Here is an example mapfile snippet for a raster WMS-T instance using a PostGIS tileindex. This example shows US Nexrad Base Reflectivity running at Iowa State U at http://mesonet.agron.iastate.edu/cgi-bin/wms/nexrad/n0r.cgi?SERVICE=WMS&request=GetCapabilities

#  Tile Index
LAYER
  STATUS ON
  NAME "time_idx"
  TYPE POLYGON
  DATA "the_geom from nexrad_n0r_tindex"
  METADATA
    "wms_title" "TIME INDEX"
    "wms_srs"   "EPSG:4326"
    "wms_extent" "-126 24 -66 50"
    "wms_timeextent" "2003-08-01/2006-12-31/P5M"
    "wms_timeitem" "datetime" #column in postgis table of type timestamp
    "wms_timedefault" "2006-06-23T03:10:00Z"
  END
  CONNECTION "dbname=postgis host=10.10.10.20"
  CONNECTIONTYPE postgis
END

# raster layer
LAYER
  NAME "nexrad-n0r-wmst"
  TYPE RASTER
  STATUS ON
  DEBUG ON
  DUMP TRUE
  PROJECTION
    "init=epsg:4326"
  END
  METADATA
    "wms_title" "NEXRAD BASE REF WMS-T"
    "wms_srs"   "EPSG:4326"
    "wms_extent" "-126 24 -66 50"
    "wms_timeextent" "2003-08-01/2006-12-31/P5M"
    "wms_timeitem" "datetime" #datetime is a column in postgis table of type timestamp
    "wms_timedefault" "2006-06-23T03:10:00Z"
  END
  OFFSITE 0 0 0
  TILEITEM "filepath" #filepath is a column in postgis table with varchar of the filepath to each image
  TILEINDEX "time_idx" 
END

You can find more information on Time and tileindexes in the WCS documentation. http://mapserver.gis.umn.edu/docs/howto/wcs_server/#d45e385

5.1   Copyright Information

Copyright (c) 2005, Jeff McKenna.

This documentation is covered by the same Open Source license as the MapServer software itself. See MapServer's License and Credits page for the complete text.

5.2   Disclaimer

No liability for the contents of this document can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies that may be damaging to your system. Although this is highly unlikely, the author(s) do not take any responsibility for that: proceed with caution.