Returns a list of historical datapoints within the specified range for one or more datastreams.

Example URL	https://api.xively.com/v2/feeds/feed_id?range
Formats	json, xml, csv
Methods	GET

range is one of the following:

• start=timestamp
• end=timestamp
• start=timestamp&end=timestamp
• start=timestamp&duration=time_unit

timestamp is an ISO 8601 formatted date (e.g. 2010-05-20T11:01:46Z).

time_unit is one of the following:

• seconds
• minute(s)
• hour(s)
• day(s)
• week(s)
• month(s)
• year(s)

Notes

• The window of requested data can be no larger than 6 hours. For example, you can request data for a 6 hour period from last week, or a 6 hour period from 2 months ago, but if you want to retrieve all datapoints from the last week you will have to make multiple individual API requests with a 6 hour window on each.

• The method for determining which datapoints are returned for a specific interval uses a simple sampling technique. The interval cycle starts at midnight and for each interval we return the value of the datastream at that point, which is the datapoint that was stored just before that interval. This means that for every interval, you get back the value of the datastream at that point in time. This technique does not work as well for datastreams which have a cycle close to that of the interval or with lots of noise.

Parameters

Historical queries are triggered by including the relevant parameters in the request URL, for either feeds or datastreams:

• start: Defines the starting point of the query as a timestamp, e.g. 2010-05-20T11:01:46Z. The default value is blank.
• end: Defines the end point of the data returned as a timestamp, e.g. 2010-05-21T11:01:46Z. The default value is set to the current timestamp
• find_previous: Will also return the previous value to the date range being requested. Note that this is useful for any graphing because if you want to draw a graph of the date range you specified you would end up with a small gap until the first value.
• limit: Limits the number of results to the number specified here. Defaults to 100 and has a maximum of 1000. In order to paginate through the data use the last timestamp returned as the start of the next query.
• interval_type: If set to “discrete” the data will be returned in fixed time interval format according to the interval value supplied. If this is not set, the raw datapoints will be returned.
• interval: Determines what interval of data is requested and is defined in seconds between the datapoints. If a value is passed in that does not match one of these values, it is rounded up to the next value. The acceptable values are currently:

Interval Value	Description	Maximum range in One Query
0	Every datapoint stored	6 hours
30	One datapoint every 30 seconds	12 hours
60	One datapoint every minute	24 hours
300	One datapoint every 5 minutes	5 days
900	One datapoint every 15 minutes	14 days
1800	One datapoint per 30 minutes	31 days
3600	One datapoint per hour	31 days
10800	One datapoint per three hours	90 days
21600	One datapoint per six hours	180 days
43200	One datapoint per twelve hours	1 year
86400	One datapoint per day	1 year

The maximum number of datapoints able to be returned from the API in one query is 1000. If you need more than 1000 datapoints for a specific period you should use the start and end times to split them up into smaller chunks.

API Call Examples

Request

 

 

Response