Time Offsets

Time Offsets

When requesting a map or map tile, a valid time or offset is required so that Xweather Raster Maps can return the proper weather overlay. There are two methods that can be utilized: passing a time offset relative to now, or requesting for a specific valid time.

Accessing by Time Offset

Fetching maps and tiles by a time offset provides the simplest method for integrating maps within your application. A time offset allows you to provide a relative time for the weather layers requested.

Often you will want to display the currently active/most recent weather overlays, for this you would use a time offset of current or latest. For example, to obtain the latest radar overlay centered on Minneapolis:


To obtain the same radar overlay, though for 10 minutes ago you would use a time offset of -10minutes, as in:


Likewise, if you were using a forecast model and wanted to obtain the future radar for 1 hour into the future, you would use a time offset of +1hour:


The following table provides the relative time descriptors that may be used within a time offset:

Secondss, second, seconds
Minutesm, min, minute, minutes
Hoursh, hr, hour, hours
Daysd, day, days

When using the time offset, Maps will perform a temporary redirect to the best available time for the relative time offset utilized.

Accessing by Valid Time

Maps allow you to define a time by passing a valid UTC time in the YYYYMMDDhhiiss format. This format can be defined as:

YYYYFour digit Year
MMTwo digit Month
DDTwo digit Day
hhTwo digit hour, 24 hour format
iiTwo digit minute
ssTwo digit second

For example, to obtain a radar overlay for June 1st, 2016 at 5:41 pm UTC you would use the valid time 20160601174100:


When using this method, Maps will find the closest valid weather overlay to fit the requested time. For the above example, if there happened to be a radar overlay for 5:35pm and another for 5:45pm, then Maps would return the radar for 5:35pm since this one was the most recent interval for the requested time.