ZoomCharts Documentation

Data

Time Chart features dynamic data loading and caching. Data loading is set up by specifying a data source in settings. There are several ways to do it:

• settings.data.dataFunction - a function to call to load data.
• settings.data.url - a URL to request data.
• settings.data.preloaded - a string or JSON object containing preloaded data.

Data request

The chart determines need time range and time unit and calls the data function or URL. Data function has the following parameters function(from, to, unit, success, error).

Parameters:

• from , to- the requested time range, javascript timestamp (milliseconds). From is inclusive, to is not inclusive.
• unit - data aggregation unit one of 'ms', 's', 'm','h', 'd', 'M' or 'y'.
• success(data) - callback function when data arrived.
• error() - callback function on failure to get data.

In the case of data URL the from, to and unit parameters` are passed in the request and response must contain the data as below.

The function must return immediately and use success() and error() callbacks to return data. Calling success() immediately is also okay.

From and to may be null. Null value means "return all the data you have in that direction". For example from = 946684800000 and to = null means "return all data after year 2000". In this case it's best if you can return a useful dataLimitTo to determine the range where data exists. Otherwise Time Chart will try to guess the end date from the returned data.

Data response

The response is formatted in JSON, with the following fields:

• from, to - (optional) time period the response covers (from inclusive, to not inclusive).
• unit - data aggregation unit, one of: "ms", "s", "m", "h", "d", "M", "y".
• values = [[1000,3],[2000,8],[3000,32],...] - data corresponding the [from .. to) period.
• dataLimitFrom, dataLimitTo - (optional) - specify limits of the available data period.

Items in the data array have the following format:

• 0 - timestamp - in milliseconds or seconds, switchable by data.timestampInSeconds parameter.
• 1 - value.
• 2.. - more values - can be bound to series using series.data.index parameter.

Instead of timestamp it is possible to pass date as a string that will be parsed to timestamp, but for better performance we recommend to use timestamps.

Optimally server return response that matches the requested unit and period.

The server can choose to return data smaller or bigger data period by specifying new from, to fields. If the period is smaller than requested chart will issue new request with the remaining period. If the period is bigger, the extra data will be cached in browser and reduce number of requests.

The server can choose to return the same aggregation unit or a smaller one. For example when requested data for years, server can return data aggregated by months. If a smaller unit is returned, Time Chart will automatically aggregate data for missing units. This reduces number of requests (but increases initial traffic).

DataLimitFrom, dataLimitTo can be used to dynamically limit the data range. Once a limit is encountered Time Chart never requests data outside that limit and displays grayed out area after that limit.

Display period autodetection

If the initial display period is not specified in settings, time chart performs autodetection.

• First, a data request is send with biggest display unit and from = null and to = null
• If dataLimitFrom and dataLimitTo fields are set in the response, they are used as display period.
• Otherwise first approximation based on returned data is made.
• If necessary more requests with smaller display unit are sent to fine tune the display period.

Data bounds determination

When displayed period is dependent on data availability, Time Chart determines data bounds.

It can be specified in several ways:

• with data.limitFrom, data.limitTo settings.
• by specifying dataLimitFrom and dataLimitTo in data response.
• if none of this is returned, chart tries to determine range from returned data itself.

Static data

If you do not need dynamic data loading, you can specify static data, using the data.preloaded setting.

For example:

    chart = new TimeChart({
      ...
      data:{preloaded:{
        unit:"s",
        values: [[0,5], [1000,10], [2000,10]],
        from:0,
        to: 3000
      }}
      ...
    });

Multiple Data Sources

TimeChart is capable of displaying simultaneously multiple series with different data sources. To use this feature, you have to specify an array of data sources in your chart configuration (opposed to a single object). Here is a sample of multidata configuration:

    ...
    data: [
        {name: "foo", url: "foo.json"},
        {name: "bar", url: "bar.json"}
    ]

Further, when configuring series, specify the data source like this:

    ...
    series: [
        {name: "a", data: {source: "foo"}},
        {name: "b", data: {source: "bar"}}
    ]
    ...

Note, if you specify multiple data sources, initial display period will be calculated considering the FIRST data source you specify - in this case the "foo" source would be used to determine initial display period.