Single Datastream

Returns a snapshot of the specified Datastream, without any of the Feed metadata. Reading data from a single Datastream at a time is not recommended, as the same information can be returned for all Datastreams simultaneously by reading the Feed that holds that Datastream.

Though it is often better to read a Feed as described above, a unique feature of reading data from a single Datastream is that this API call offers the ability to request a PNG graph of the Datastream’s history.

PNG Graphs

Requesting the Datastream as a PNG image will generate a customizable graph of the Datastream’s history as a .png file.

The time period of the graph can be customized by appending time period parameters to the request URL, as outlined in the API Resources Table under “datastreams - Read (range)”. The interval is calculated automatically depending on the time range.

The appearance of the graph can also be customized by appending a question mark ( ? ) and the following parameters to the URL of the request. Combine more than one parameter using the ampersand ( & ) character. The look and feel of this graph can be controlled by the following parameters:

Parameter Description Example
w width in pixels 600
h height in pixels 400
c color in hex FFCC33
t title “My Favorite Graph”
l legend “Legend For My Graph”
s stroke size in pixels 4
b show axis labels true / false
g show detailed grid true / false
scale method used to determine the y-axis scale auto / Datastream / manual
min y-axis minimum value if scale=manual 0
max y-axis maximum value if scale=manual 100
timezone time zone of the graph time zone from this list

As an example, a default graph might look like this:

https://api.xively.com/v2/feeds/FEED_ID_HERE/ datastreams/DATASTREAM_ID.png

Whereas appending color, grid, title, and axis label parameters to the same Datastream will produce:

https://api.xively.com/v2/feeds/61916/datastreams/ random900.png?c=2188c5&g=true&t="My Graph"&b=true

API Call Examples

Request

Parameters
Method GET
Base URL https://api.xively.com
API Endpoint /v2/feeds/FEED_ID_HERE/datastreams/DATASTREAM_ID
Headers
X-ApiKey API_KEY_HERE
Body
JSON
XML
CSV
PNG
  • GET/v2/feeds/FEED_ID_HERE/datastreams/DATASTREAM_ID.json

    This request does not require body data
    
  • GET/v2/feeds/FEED_ID_HERE/datastreams/DATASTREAM_ID.xml

    This request does not require body data
    
  • GET/v2/feeds/FEED_ID_HERE.csv

    This request does not require body data
    
  • GET/v2/feeds/FEED_ID_HERE/datastreams/DATASTREAM_ID.png

    This request does not require body data
    

 

 

Response

Parameters
Status Code 200 OK
Headers
No Headers
Body
JSON
XML
CSV
PNG
  • {
        "id":"example",
        "current_value":"500",
        "at":"2013-05-06T00:30:45.694188Z",
        "max_value":"500.0",
        "min_value":"333.0",
        "version":"1.0.0"
    }
    
  • <?xml version="1.0" encoding="UTF-8"?>
    <eeml 
        xmlns="http://www.eeml.org/xsd/0.5.1"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="0.5.1" xsi:schemaLocation="http://www.eeml.org/xsd/0.5.1 http://www.eeml.org/xsd/0.5.1/0.5.1.xsd">
        <environment updated="2013-05-05T19:40:08.859383Z" created="2013-03-29T15:50:43.398788Z" id="121601" creator="https://xively.com/users/calumbarnes">
            <data id="example">
                <current_value at="2013-05-06T00:30:45.694188Z">500</current_value>
                <max_value>500.0</max_value>
                <min_value>333.0</min_value>
            </data>
        </environment>
    </eeml>
    
  • 2013-05-06T00:30:45.694188Z,500