API Reference¶

The xively-python library consists of two layers. The top layer uses the XivelyAPIClient and object wrappers. The lower layer via Client gives access directly to sending native python types and accessing the response.

API Client¶

class xively.XivelyAPIClient(key, use_ssl=False, **kwargs)¶

An instance of an authenticated Xively API Client.

The root object from which the user can manage feeds, keys and triggers.

Parameters:	key (str) – A Xively API Key use_ssl (bool [False]) – Use https for all connections instead of http kwargs – Other additional keyword arguments to pass to client

Usage:

>>> import xively
>>> xively.XivelyAPIClient("API_KEY")
<xively.XivelyAPIClient()>

>>> api = xively.XivelyAPIClient("API_KEY", use_ssl=True)
>>> api.feeds.base_url
'https://api.xively.com/v2/feeds'
>>> api.triggers.base_url
'https://api.xively.com/v2/triggers'
>>> api.keys.base_url
'https://api.xively.com/v2/keys'

api_version = 'v2'¶

client_class¶: alias of Client

feeds¶: Access Feed objects through a FeedsManager.

keys¶: Access Key objects through a KeysManager.

triggers¶: Access Trigger objects through a TriggersManager.

Feeds, Datastreams and Datapoints¶

class xively.managers.FeedsManager(client)¶

Create, update and return Feed objects.

Note

This manager should live on a XivelyAPIClient instance and not instantiated directly.

Parameters:	client – Low level `Client` instance

Usage:

>>> import xively
>>> api = xively.XivelyAPIClient("API_KEY")
>>> api.feeds.create(title="Xively Office environment")
<xively.Feed(7021)>
>>> api.feeds.get(7021)
<xively.Feed(7021)>
>>> api.feeds.update(7021, private=True)
>>> api.feeds.delete(7021)

create(title, description=None, website=None, email=None, tags=None, location=None, private=None, datastreams=None)¶

Creates a new Feed.

Parameters:

title – A descriptive name for the feed
description – A longer text description of the feed
website – The URL of a website which is relevant to this feed e.g. home page
email – A public contact email address for the creator of this feed
tags – Tagged metadata about the environment (characters ‘ ” and commas will be stripped out)
location – Location object for this feed
private – Whether the environment is private or not. Can be either True or False

delete(id_or_url)¶

Delete a feed by id or url.

Warning

This is final and cannot be undone.

Parameters:	id_or_url – The feed ID or its URL

get(id_or_url, datastreams=None, show_user=None, start=None, end=None, duration=None, find_previous=None, limit=None, interval_type=None, interval=None)¶

Fetches and returns a feed by id or url.

By default the most recent datastreams are returned. It is also possible to filter the datastreams returned with the feed by using the “datastreams” parameter and a list of datastream IDs.

Parameters:

datastreams (list of datastream IDs) – Filter the returned datastreams
show_user (bool) – Include user login for each feed. (default: False)
start – Defines the starting point of the query
end – Defines the end point of the data returned
duration – Specifies the duration of the query
find_previous – Will also return the previous value to the date range being requested.
limit – Limits the number of results to the number specified. Defaults to 100 and has a maximum of 1000.
interval_type – If set to “discrete” the data will be returned in fixed time interval format according to the inverval 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 which does not match one of these values, it is rounded up to the next value.

See history() for details.

list(page=None, per_page=None, content=None, q=None, tag=None, user=None, units=None, status=None, order=None, show_user=None, lat=None, lon=None, distance=None, distance_units=None)¶

Returns a paged list of feeds.

Only feeds that are viewable by the authenticated account will be returned. The following parameters can be applied to limit or refine the returned feeds:

Parameters:

page – Integer indicating which page of results you are requesting. Starts from 1.
per_page – Integer defining how many results to return per page (1 to 1000)
content – String parameter (‘full’ or ‘summary’) describing whether we want full or summary results. Full results means all datastream values are returned, summary just returns the environment meta data for each feed
q – Full text search parameter. Should return any feeds matching this string
tag – Returns feeds containing datastreams tagged with the search query
user – Returns feeds created by the user specified
units – Returns feeds containing datastreams with units specified by the search query
status – Possible values (‘live’, ‘frozen’, or ‘all’). Whether to search for only live feeds, only frozen feeds, or all feeds. Defaults to all
order – Order of returned feeds. Possible values (‘created_at’, ‘retrieved_at’, or ‘relevance’)
show_user – Include user login and user level for each feed. Possible values: true, false (default)

The following additional parameters are available which allow location based searching of feeds:

Parameters:	lat – Used to find feeds located around this latitude lon – Used to find feeds located around this longitude distance – search radius distance_units – miles or kms (default)

update(id_or_url, **kwargs)¶

Updates an existing feed by its id or url.

Parameters:	id_or_url – The id of a `Feed` or its URL kwargs – The fields to be updated

class xively.Feed(title, description=None, website=None, email=None, tags=None, location=None, private=None, datastreams=None)¶

Xively Feed, which can contain a number of Datastreams.

Parameters:

title – A descriptive name for the feed
description – A longer text description of the feed
website – The URL of a website which is relevant to this feed e.g. home page
email – A public contact email address for the provider of this feed
tags – Tagged metadata about the environment (characters ‘ ” and commas will be stripped out)
location – Location object for this feed
private (bool) – Whether the environment is private or not.

Usage:

>>> import xively
>>> xively.Feed(title="Xively Office environment")
<xively.Feed(None)>

VERSION = '1.0.0'¶

datastreams¶

Manager for datastreams of this feed.

When fetched from the API, datastreams behaves like a cache, populated with the most recently updated datastreams for this feed. The manager can also be used to create, update and delete datastreams for this feed.

Usage:

>>> import xively
>>> api = xively.XivelyAPIClient("API_KEY")
>>> feed = api.feeds.get(7021)
>>> feed.datastreams[0]  
<xively.Datastream('3')>

delete()¶: Delete this feed via the API.

Warning

This is final and cannot be undone.

update(fields=None)¶

Updates feed and datastreams via the API.

If successful, the current datastream values are stored and any changes in feed metadata overwrite previous values. Xively stores a server-side timestamp in the “updated” attribute and sets the feed to “live” if it wasn’t before.

Parameters:	fields (list of strings) – If given, only update these fields.

class xively.managers.DatastreamsManager(feed)¶

Create, update and return Datastream objects.

Instances of this class hang off of Feed objects to manage datastreams of that feed.

A list of datastreams can be retrieved along with the feed which can be accessed via this instance as a sequence.

Parameters:	feed – A `Feed` instance.

Usage:

>>> import xively
>>> api = xively.XivelyAPIClient("API_KEY")
>>> feed = api.feeds.get(7021)
>>> list(feed.datastreams)  
[<xively.Datastream('3')>, <xively.Datastream('4')>]
>>> feed.datastreams.create("1")
<xively.Datastream('1')>

create(id, current_value=None, tags=None, unit=None, min_value=None, max_value=None, at=None)¶

Creates a new datastream on a feed.

Parameters:	id – The ID of the datastream current_value – The current value of the datastream tags – Tagged metadata about the datastream unit – The `Unit` for this datastream min_value – The minimum value since the last reset max_value – The maximum value since the last reset at – The timestamp of the current value
Returns:	A `Datastream` object

delete(id_or_url)¶

Delete a datastream by id or url.

Warning

This is final and cannot be undone.

Parameters:	id_or_url – The datastream ID or its URL

get(id_or_url, start=None, end=None, duration=None, find_previous=None, limit=None, interval_type=None, interval=None)¶

Fetches and returns a feed’s datastream by its id.

If start, end or duration are given, also returns Datapoints for that period.

Parameters:

id_or_url – The ID of the datastream to retrieve or its URL
start – Defines the starting point of the query
end – Defines the end point of the data returned
duration – Specifies the duration of the query
find_previous – Will also return the previous value to the date range being requested.
limit – Limits the number of results to the number specified. Defaults to 100 and has a maximum of 1000.
interval_type – If set to “discrete” the data will be returned in fixed time interval format according to the inverval 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 which does not match one of these values, it is rounded up to the next value.

See history() for details.

list(datastreams=None, show_user=None)¶

Returns a list of datastreams for the parent feed object.

Parameters:	datastreams (list of datastream IDs) – Filter the returned datastreams show_user (bool) – Include user login for each feed (default: False)

update(datastream_id, **kwargs)¶

Updates a feeds datastream by id.

Parameters:	datastream_id – The ID of the datastream to update kwargs – The datastream fields to be updated

class xively.Datastream(id, tags=None, unit=None, min_value=None, max_value=None, current_value=None, datapoints=None, at=None)¶

Xively Datastream containing current and historical values.

Parameters:	id – The ID of the datastream tags – Tagged metadata about the datastream unit – The `Unit` of the datastream min_value – The minimum value since the last reset max_value – The maximum value since the last reset current_value – The current value of the datastream at – The timestamp of the current value datapoints – A collection of timestamped values

datapoints¶

Manager for datapoints of this datastream.

When a datastream is fetched with history from the API, datapoints is a sequence of timestamped values for the period requested. The manger can also be used tocreate, update and delte datapoints for this datastream.

Usage:

>>> import xively
>>> import datetime
>>> api = xively.XivelyAPIClient("API_KEY")
>>> feed = api.feeds.get(7021)
>>> datastream = feed.datastreams.get("random5",
...     start=datetime.datetime(2013, 1, 1, 14, 0, 0),
...     end=datetime.datetime(2013, 1, 1, 16, 0, 0))
>>> datastream.datapoints[:2]
... 
[xively.Datapoint(datetime.datetime(...), '0.25741970'),
 xively.Datapoint(datetime.datetime(...), '0.86826886')]

delete()¶: Delete this datastream from Xively.

Warning

This is final and cannot be undone.

update(fields=None)¶

Sends the current state of this datastream to Xively.

This method updates just the single datastream.

Parameters:	fields (list of strings) – If given, only update these fields.

class xively.managers.DatapointsManager(datastream)¶

Manage datapoints of a datastream.

A list of Datapoint objects can be retrieved along with the Datastream (or Feed) which can be accessed via this instance as a sequence.

Parameters:	datastream – A `Datastream` instance.

create(value, at=None)¶

Create a single new datapoint for this datastream.

Parameters:	at – The timestamp of the datapoint (default: datetime.now()) value – The value at this time

To create multiple datapoints at the same time do the following instead:

Note

You can use ISO8601 formatted strings instead of datetime objects when dealing with the API.

>>> import xively
>>> api = xively.XivelyAPIClient("API_KEY")
>>> feed = api.feeds.get(7021)
>>> datastream = feed.datastreams[0]
>>> # First create the datapoints.
>>> datastream.datapoints = [
...     xively.Datapoint(at="2010-05-20T11:01:43Z", value=294),
...     xively.Datapoint(at="2010-05-20T11:01:44Z", value=295),
...     xively.Datapoint(at="2010-05-20T11:01:45Z", value=296),
...     xively.Datapoint(at="2010-05-20T11:01:46Z", value=297),
... ]
>>> # Then send them to the server.
>>> datastream.update(fields='datapoints')

delete(at=None, start=None, end=None, duration=None)¶

Delete a datapoint or a range of datapoints.

Parameters:	at – A timestamp of a single datapoint to delete start – Defines the starting point of the query end – Defines the end point of the datapoints deleted duration – Specifies the duration of the query

By providing a start and end timestamp as query parameters, you may remove all datapoints that lie between those dates. If you send your request with only a start timestamp, all datapoints after the value will be removed. Providing an end timestamp will remove all datapoints prior to the supplied value.

Additionally, this method supports a duration parameter (e.g. duration="3hours"). Providing a start and a duration will delete all datapoints between the start and (start + duration). Providing end will delete all datapoints between (end - duration) and end. The formatting of the duration parameter is the same as is used in the history() method.

get(at)¶

Fetch and return a Datapoint at the given timestamp.

Parameters:	at – The timestamp to return a datapoint for

history(start=None, end=None, duration=None, find_previous=None, limit=None, interval_type=None, interval=None)¶

Fetch and return a list of datapoints in a given timerange.

Parameters:

start – Defines the starting point of the query
end – Defines the end point of the data returned
duration – Specifies the duration of the query
find_previous – Will also return the previous value to the date range being requested.
limit – Limits the number of results to the number specified. Defaults to 100 and has a maximum of 1000.
interval_type – If set to “discrete” the data will be returned in fixed time interval format according to the inverval 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 which does not match one of these values, it is rounded up to the next value.

Note

find_previous 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.

Note

In order to paginate through the data use the last timestamp returned as the start of the next query.

Note

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.

The valid time units are:

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

The acceptable intervals are currently:

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

update(at, value)¶

Update the value of a datapiont at a given timestamp.

Parameters:	at – The timestamp of a value to change value – The value to change

Note

A datapoint at the given time must already exist.

class xively.Datapoint(at, value)¶

A Datapoint represents a value at a certain point in time.

Parameters:	at – The timestamp of the datapoint value – The value at this time

delete()¶: Delete this datapoint.

Warning

This is final and cannot be undone.

update()¶: Update this datapoint’s value.

Location and Waypoints¶

class xively.Location(name=None, domain=None, exposure=None, disposition=None, lat=None, lon=None, ele=None, waypoints=None)¶

The location and location type of a feed.

Parameters:

name – The name of the location
domain – The domain of the location, i.e. ‘physical’ or ‘virtual’
exposure – Whether the location is indoors or outdoors
disposition – Whether the location is mobile or static
lat – The latitude of the feed
lon – The longitude of the feed
ele – The elevation of the feed
waypoints – A list of locations for a mobile feed

class xively.Waypoint(at, lat, lon)¶

A waypoint represents where a mobile feed was at a particular time.

Parameters:	at – The timestamp of the waypoint lat – The latitude at that time lon – The longitude at that time

API Keys¶

class xively.managers.KeysManager(client)¶

Manage keys their permissions and restrict by resource.

This manager should live on a XivelyAPIClient instance and not instantiated directly.

Parameters:	client – Low level `Client` instance

Usage:

>>> import xively
>>> api = xively.XivelyAPIClient("API_KEY")
>>> api.keys.create(
...     label="sharing key",
...     private_access=True,
...     permissions=[
...         xively.Permission(
...             access_methods=["put"],
...             source_ip="128.44.98.129",
...             resources=[
...                 xively.Resource(feed_id=504),
...             ]),
...         xively.Permission(access_methods=["get"])
...     ])
<xively.Key('sharing key')>

create(label, permissions, expires_at=None, private_access=None)¶

Create a new API key.

Parameters:	label – A label by which the key can be referenced permissions – Collection of Permission objects controlling the access level expires_at – Expiry date for the key after which it won’t work private_access – Flag that indicates whether this key can access private resources belonging to the user

delete(key_id)¶

Delete the specified key.

Parameters:	key_id – The key ID

get(key_id)¶

Fetch and return an API key by its id.

Parameters:	key_id – The ID of the key to get.

list(feed_id=None)¶

List all API keys for this account or for the given feed.

Parameters:	feed_id – Returns api keys limited to that feed and its datastreams.

resource = 'keys'¶

class xively.Key(label, permissions, expires_at=None, private_access=False)¶

Keys set which permissions are granted for certain resources.

Parameters:	label – A label by which the key can be referenced permissions – Collection of Permission objects controlling the access level expires_at – Expiry date for the key after which it won’t work private_access – Flag that indicates whether this key can access private resources belonging to the user

delete()¶: Delete this key.

class xively.Permission(access_methods, source_ip=None, referer=None, minimum_interval=None, label=None, resources=None)¶

Permissions restrict what can be done by a key.

Parameters:

access_methods – A list containing one or more of [get, put, post, delete] indicating what type of access the key has
source_ip – An IP address that access should be restricted to, so if specified, only requests coming from this IP address will be permitted
referer – The referer domain. If present this key will only be able to be embedded in a web page with the matching URL. Subdomains are treated as different domains
minimum_interval – Can be used to create a key that can only request data with a certain resolution, i.e. a key could be created that only displays graphs with daily values when embedded in a web page. The same key could not be used to access full resolution data
label – Optional label for identifying permission set
resources – Optional collection of Resource objects restricting access to specific feeds or datastreams

class xively.Resource(feed_id, datastream_id=None)¶

A Resource defines what an API key has access to.

Parameters:	feed_id – Reference to a specific feed id datastream_id – Reference to a specific datastream id within a feed. If specified then the feed id must also be specified

Triggers¶

class xively.managers.TriggersManager(client)¶

Manage Trigger.

This manager should live on a XivelyAPIClient instance and not instantiated directly.

Parameters:	client – Low level `Client` instance

Usage:

>>> import xively
>>> api = xively.XivelyAPIClient("API_KEY")
>>> api.triggers.create(
...     environment_id=8470, stream_id="0",
...     url="http://www.postbin.org/1ijyltn",
...     trigger_type='lt', threshold_value="15.0")
<xively.Trigger(3)>

create(environment_id, stream_id, url, trigger_type, threshold_value=None)¶

Create a new Trigger.

Parameters:	environment_id – An ID of a `Feed` stream_id – An ID of a `Datastream` url – The URL to POST events to trigger_type – The type of trigger (from below) threshold_value – The threshold at which the trigger fires
Returns:	A new `Trigger` object.

Possible values for trigger_type are:

gt	greater than
gte	greater than or equal to
lt	less than
lte	less than or equal to
eq	equal to
change	any change
frozen	no updates for 15 minutes
live	updated again after being frozen

delete(id_or_url)¶

Delete a trigger by id or url.

Warning

This is final and cannot be undone.

Parameters:	id_or_url – The datastream ID or its URL

get(id_or_url)¶

Fetch and return an existing trigger.

Parameters:	id_or_url – The ID of the trigger or its URL

list(feed_id=None)¶

Return a list of triggers.

Parameters:	feed_id – Filter the returned triggers to only include those on datastreams of the specified feed.

update(id_or_url, **kwargs)¶

Update an existing trigger.

Parameters:	id_or_url – The ID of the `Trigger` to update or its URL kwargs – The fields to be updated

class xively.Trigger(environment_id, stream_id, url, trigger_type, threshold_value=None)¶

Triggers provide ‘push’ capabilities (aka notifications).

To create a new trigger, use the TriggersManager on a XivelyAPIClient instance.

>>> from xively import XivelyAPIClient
>>> api = XivelyAPIClient("API_KEY")
>>> api.triggers.create(123, "temperature", "http://example.com", "frozen")
<xively.Trigger(3)>

delete()¶: Delete a trigger.

Warning

This is final and cannot be undone.

update(fields=None)¶

Update an existing trigger.

Parameters:	fields (list of strings) – If given, only update these fields

Low Level Client¶

class xively.Client(key, use_ssl=False, verify=True)¶

Bases: requests.sessions.Session

A Xively API Client object.

This is instantiated with an API key which is used for all requests to the Xively API. It also defines a BASE_URL so that we can specify relative urls when using the client (all requests via this client are going to Xively).

Parameters:	key (str) – A Xively API Key use_ssl (bool [False]) – Use https for all connections instead of http verify – Verify SSL certificates (default: True)

A Client instance can also be used when you want low level access to the API and can be used with CSV or XML instead of the default JSON.

Usage:

>>> client = xively.Client("YOUR_API_KEY")
>>> body = "1,123\r\n2,456\r\n"
>>> client.post('/v2/feeds/1977.csv', data=body)
<Response [200]>

request(method, url, *args, **kwargs)¶

Constructs and sends a Request to the Xively API.

Objects that implement __getstate__ will be serialised.

API Reference¶

API Client¶

Feeds, Datastreams and Datapoints¶

Location and Waypoints¶

API Keys¶

Triggers¶

Low Level Client¶

Table Of Contents

Previous topic

Next topic

This Page

Navigation

API Reference¶

API Client¶

Feeds, Datastreams and Datapoints¶

Location and Waypoints¶

API Keys¶

Triggers¶

Low Level Client¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation