Time Offsets

When requesting a map or map tile, a valid time or offset is required so that Aeris 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, the Aeris Map Platform will perform a temporary redirect to the best available time for the relative time offset utilized.

Accessing by Valid Time

Aeris 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, Aeris 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 Aeris Maps would return the radar for 5:35pm since this one was the most recent interval for the requested time.

Weather Layer Valid Times

Some use-cases require using the exact valid times that a weather overlay is available for. Aeris Maps provides the ability to fetch the available times via a times JSON request, which returns the valid timestamp metadata for an overlay. The returned response will provide an array of objects, each containing date and time information for every interval currently available. Results will be returned sorted by time and date in descending order:


The [type] variable is the weather overlay that the valid times are required.  The following is an example response for a tiles JSON request:

	files: [
			timestamp: 1454419920,
			time: "20160202133200"
			timestamp: 1454419620,
			time: "20160202132700"

The time attribute is in the format utilized when requesting an API by time.