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)
  • locationLocation 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)
  • locationLocation 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.

Table Of Contents

Previous topic

Welcome to Xively Python’s documentation

Next topic

Examples

This Page