Using the RescueTime Embed and Data API

share team status, show off top performers, and more

We’ve had substantial user interest in ways of sharing and re-using their RescueTime data. True to our principles of keep-it-simple, we’ve published a way to very easily and safely share views of your data. These features have been live for over a month now, and some of you have already found and done great things with them– thank you! Here I’d thought I’d outline the process and some example use cases to help undertand how you can take your data further.

Although sharing common underlying code, there are two different paths to API data, with two different intentions: embedding charts and raw data access.

Path 1: Super Easy! Embed a Chart

As you use our new, improved, faster, more flexible reports browser, when you come across a slicing and dicing you particularly like, just click the Embed button, found right under the chart. Grab the snippet, and stick it in your blog, or your intranet, or wherever you want to publish it. Note that you can put as many as you like on the same page. Some of our clients have built team dashboards on their corporate intranets where anyone can go to see the pulse of the organization. Some publish these on their websites to show off their performance. Some live blog examples include: www.tonywright.com, Chris Barrow’s Blog, TheG2.net Blog and node.to.

Behind the scenes, this sets up an access key for you and sets privileges on it: when you paste this snippet onto your blog or intranet, anyone trying to steal your info using this key can only get exactly what it already shows. Note that in the snippet you can tweak certain aspects of the chart.

Also note that while your report view in your browser is fixed to the date you are looking at it, your embedded chart will continue to update with whatever is current. The timeframe is saved– as in “a week” or “a day” but not the specific date.

Path 2: Get Funky With Your Data

We’ve released an API targeted a making it easier for users to obtain alternate perspectives on their data, or to re-use it in other applications in a programmatic way. The current interface offered is based around a read-only http query core that models your data in ways users are accustomed to from RescueTime’s existing report views. We’re working on some language-specific convenience wrappers around this query API, and the Python library is complete. Ruby, Java, and Javascript are in the plans.

The first step is to go to the “Embeds & Data API” link from the bottom of your logged in session. From there you can “Setup Data API” to create a key for raw data access. Instead of output being formatted for charts, instead you pick JSON or CSV output, which you can then parse and reformat however you please. You can also parameterize your requests to change what is returned, without needing new keys– you can change date, search key words, specific application names, among other things.

There is a security model around the key providing data scope control and access safety, based on the same key system used by embedding. In this case, a switch is flipped that allows parameterization– so it removes that “can only see what browse view saw” restriction that embed has. It is assumed you will keep these more privileged keys private. But you can always monitor traffic and disable a key if you believe someone is using it who shouldn’t be. You can also set basic network restrictions around the key, to lock it down to access for just your machines.

A Reference Implementation

You can see what we did with the API in our reference implementation hosted on Google’s Appengine. It uses all the aboved methods and API tools in one page. All of the code for it is available for download.


6 Comments on “Using the RescueTime Embed and Data API”

  1. Greg Bray says:

    I’d love to be able to pull the data into Excel or Resolver One for analysis, but after taking a quick look I can’t figure out how to use the raw HTTP Query Interface. The api documents lists some of the parameters, but there is no reference to the actual URL that you use to access the data. Any chance you could provide a sample of the full URL used to get category data for a given date range in csv format?

    I tried reading the Python wrapper code, but it doesn’t contain a url either (seems to reference “localhost:3000” as the servername. I tried snooping around the url used for embedding charts, but I couldn’t figure it out. my guess is something like:

    https://www.rescuetime.com/anapi/?op=select…..

    but that returns a 404. Also I’m not sure where to insert the api key. Is it a parameter or part of the url path? If it is a parameter, what name should we use? Also guidance as to which parameters are optional and which are required would be helpful.

    Sounds awesome though! Keep up the great work!

  2. Thanks for the feedback! That’s what I get for publishing code without docs! 🙂

    For reference, the base URL is:

    https://www.rescuetime.com/anapi/data

    So, I should set reasonable defaults and update the docs per your questions, but right now you would:

    1) Create a service object:

    svc = Service('https://www.rescuetime.com')

    2) Create a AnalyticApiKey object tied to that service:

    akey = AnalyticApiKey('THEKEYSTRINGFROMAPISETUPPAGE', svc)

    You get the key name / key string from the Setup Data API page.

    3) Create as many data requests you want for that key:

    d1 = ResponseData(akey, {'operation': 'select', 'perspective': 'rank', 'restrict_kind': 'overview', etc... add more params }
    d2 = ResponseData(akey, {'operation': 'select', 'perspective': 'interval', 'resolution_time': 'hour', 'restrict_kind': 'activity', etc... add more params }

    4) Call sync to get data

    d1.sync()
    d2.sync()

    The returned data is in: d1.object and d2.object

    Hope that helps!

  3. Greg Bray says:

    Still had to do a bit of snooping around since the http://www.rescuetime.com/apidoc page is missing information about the format=csv and rtapi_key=…. parameters, but after a few tries I got it to work. If anyone else is curious the following is a sample URL that will return a list of “Date,Time Spent (seconds),Number of People,Activity,Category,Productivity” data in CSV format for Sept 14th using an hour chunk size:

    https://www.rescuetime.com/anapi/data/?op=select&vn=0&pv=interval&rk=activity&rs=hour&rb=2009-09-14&rb=2009-09-15&format=csv&rtapi_key=YourKeyHere

    Playing around with the various parameters should let you customize the data that gets exported. This is pretty cool! The data drops right into Excel or Access for analysis with Pivot Charts and Tables. Keep up the awesome work!

  4. Mark Wolgemuth says:

    Bah, I forgot to add those too. Sorry Greg, I’ll update the docs again. Thanks for your feedback and example!

  5. Michael Sallmen says:

    A tip for the frustrated:
    I kept getting getting a 500 or {“error”: null} message until I realized that the server rules for my API key still contained the default ” ip/mask or hostname or domain name ” prompt string. I cleared that out and it worked immediately!

    Thanks very much for this API! You might want to think about ignoring or removing the default prompt string for people like me who think leaving a text box alone means it’s not going to affect the outcome.

  6. Mark Wolgemuth says:

    Thanks for the feedback!
    I’ll change the code to ignore an unedited value.