Time Offsets

When requesting a map or map tile, a valid time or offset is required so that AerisWeather 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:

Current current
Seconds s, second, seconds
Minutes m, min, minute, minutes
Hours h, hr, hour, hours
Days d, day, days

Heads Up! The numeric portion of a time offset must be an integer value and decimals are not permitted. For example, use -90minutes instead of -1.5hours.

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:


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.

Last modified: August 02, 2021