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:
http://maps.api.xweather.com/{client_id}_{client_secret}/radar/500x500/minneapolis,mn,6/current.pngTo obtain the same radar overlay, though for 10 minutes ago you would use a time offset of -10minutes, as in:
http://maps.api.xweather.com/{client_id}_{client_secret}/radar/500x500/minneapolis,mn,6/-10minutes.pngLikewise, 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:
http://maps.api.xweather.com/{client_id}_{client_secret}/frad/500x500/minneapolis,mn,6/+1hour.pngThe following table provides the relative time descriptors that may be used within a time offset:
| Current | current |
| Seconds | s, second, seconds |
| Minutes | m, min, minute, minutes |
| Hours | h, hr, hour, hours |
| Days | d, 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:
| YYYY | Four digit Year |
| MM | Two digit Month |
| DD | Two digit Day |
| hh | Two digit hour, 24 hour format |
| ii | Two digit minute |
| ss | Two 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:
http://maps.api.xweather.com/{client_id}_{client_secret}/radar/500x500/minneapolis,mn,6/20160601174100.pngWhen 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.