So now that Zeitgeist 0.2.0 is out I’ve thought I’d write down some examples of how to use it’s API to get information from it. Please keep in mind that this is a development version and the API isn’t guaranteed to be stable (and I can tell you now, many of them will change). If you’re going to develop something for Zeitgeist it’s a good idea to come by and explain us what you’re doing (so that we can keep your use cases in mind and notify you in case of any important changes). This said, here we go.

Installation

If you use Ubuntu you can grab packages from Zeitgeits’s PPA, else get the tarball and install it (# make; make install). Once installed, start “zeitgeist-daemon” and leave it running in the background (at first it may be busy for some time going through all of your Firefox history, but after that you shouldn’t notice it).

Zeitgeist comes with a public Python module providing some convenience functions. This module makes it very easy to play with Zeitgeist from an interactive Python instance, which is something I recommend you to do while reading this post. Thanks to it, you can get access to Zeitgeist’s D-Bus interface simply doing: from zeitgeist import dbusutils; iface = dbusutils.DBusInterface().

API Examples

For brevity, I’m only going to show some examples, but not explain what every parameter used in the call stands for. You’ll need to look at the DBus API documentation to completely understand them.

Also, I’m using Python for the examples, but the same works with very little modifications in any other language (as long as it has D-Bus bindings).

iface.GetItems([u'file:///home/rainct/todo'])
Returns a dictionary with basic information about the “todo” file in my home directory; uri, text (usually the filename), mimetype, tags, whether it’s bookmarked or not, etc. The values for some keys, like “timestamp”, are empty because they are only relevant for events, which are items put into a timeline (yes, this is a bit confusing, in future versions of Zeitgeist we will clearly differentiation between events and items).

iface.FindEvents(time.time() - 24*3600, time.time(), 5, False, 'event', [])
Returns the five last events (or less, if less than five events where logged within the last twenty-four hours). If you opened the same file twice, it will have two events; to avoid this change 'event' to 'item'.

iface.FindEvents(0, 0, 10, True, 'event', [])
Returns the ten first events ever registered with Zeitgeist which happened first (the sorting is always done by timestamp, not by insertion order).

iface.FindEvents(0, 0, 2, False, 'mostused', [])
Returns the last two events for to the items (URIs) which are used the most often.

iface.FindEvents(0, 0, 0, False, 'item', [{'tags': [u'zeitgeist'], 'bookmarked': True}])
Returns all events (when there are more than one with the same URI, only the most recent of them because of the 'item' parameter) which are bookmarked and have the tag “zeitgeist”.

iface.FindEvents(0, 0, 0, False, 'item', [{'tags': [u'zeitgeist']}, {'mimetypes': ['text/x-python'], 'bookmarked': True}])
Returns all events (when there are more than one with the same URI, only the most recent of them because of the 'item' parameter) which are bookmarked and have the tag “zeitgeist”.

iface.FindEvents(0, 0, 0, False, 'item', [{'tags': [u'zeitgeist', 'engine']}, {'mimetypes': ['text/x-python'], 'bookmarked': True}])
Returns all events (without duplicated URIs) which either have the tags “zeitgeist” and “engine” or, alternatively, are Python files (determined by their mimetype) and are bookmarked.

iface.CountEvents(0, 0, 'item', [{'tags': [u'zeitgeist', 'engine']}, {'mimetypes': ['text/x-python'], 'bookmarked': True}])
Same as above, but returning only the amount of results that the previous call would yield.

iface.FindApplications(time.time() - 3600*24*30, 0, [{'mimetypes': ['text/x-python']}])
Returns the path to the .desktop files of all applications which were used to manipulate Python files within the last 30 days (eg., in my case: [u’/usr/share/applications/geany.desktop’, u’/usr/share/applications/gedit.desktop’ ]).

iface.GetTags(0, 0, 5, u'a%')
Returns the five most used tags which start with “a” (case insensitive) in a list of tuples containing both the tag name and the amount of times it was used.

iface.GetLastInsertionDate(u'/usr/share/applications/gedit.desktop')
Returns the timestamp of the last event related to Gedit.

iface.connect('EventsChanged', callback_function); import gobject; gobject.MainLoop.run()
Calls callback_function every time a new event is inserted into the database or an existing one is modified. The callback function receives a list containing in the first place a string representing the type of change (“added”, “modified”, “deleted”) and in second place a list containing the affected events (or, in case of deletion, only a list with the deleted URIs).