Table of Contents
- Overview
-
- The HTTP Query Interface
- Ruby API
- Python API
- JavaScript API
- Security Considerations
- Contact us about contributing another language API!
Overview: Analytic Data API
RescueTime data is detailed and complicated.
Our initial API release is targeted at bringing developers the prepared and pre-organized
data structures already familiar through the reporting views of www.rescuetime.com.
The data is read-only through the webservice, but you can perform any manipulations on the consumer side you want.
Keep in mind this is a draft interface, and may change in the future. We do intend to version the interfaces though,
so it is likely forward compatible.
Two primary vectors are offered into your data through the API, "embed" access and general "data api" access.
Embed access is granted from most reporting views you encounter through the website,
simply click the "embed" button and follow the instructions.
API data access is a little different. Follow the "Embed & Data API" link and select the "Setup Data API" link.
Embed sets up a key for you to publish a selection of your data,
precisely as you were viewing it in the reporting screen you started from. By default, it only provides data usable
by the charting interface, for which javascript is provided. You can enable raw data access to this same
set of data as well, and feed it to your application. For Data API users, the interest here is that you can save exact search keywords
this way, then if you enable data access, you can repeat this query programmatically. For example, you could view an activities report for the day,
and search for "Client XYZ". If you clicked the Embed button and then "Enable access to this through Data API", the key generated can be
used to automatically fetch the daily results into a back end system of some kind.
Data API access is provided from the "Setup Data API" tab in the "Embed & Data API"
section. It allows for parameterized access, which means you can change the subject and scope of data, and is
especially targeted for developer use. The data can be accessed either as raw data in several formats, as data formatted
for the chart interface, or through the several bundled language specific APIs.
The HTTP Query Interface
In this initial release, the Analytic Data API is presented as a read only resource accessed by simple GET/POST HTTP queries.
This provides maximum flexibility with minimal complexity; you can use the provided API tools, or just research the documented parameters and
construct your own queries.
Service Access
The current base URL to reach this HTTP query API is: https://www.rescuetime.com/anapi/data
Required parameters are:
- key = [ Your API key generated in the Embed and Data API -> Setup Data API ]
- format = [ csv | json ]
Query Parameters
Primary names are chosen for human reading. The short names are for when GET query length is at a premium.
The alias is for understanding roughly how it maps into the language used in reporting views, and our own internal nicknames.
| Principle name |
Short |
Alias |
Short |
Values |
Description |
| operation | op | | |
"select" |
Currently, only one operation is supported, "select", and it is enforced on the server, and does not need to be sent from client. |
| version | vn | | |
"0" |
Only one version is live right now, and therefore doesn't need to be passed. It will be a serial number. |
| perspective | pv | by | by |
1 of "rank", "interval", "member" |
Consider this the X - axis of the returned data. It is what determines how your data is crunched serverside for ordered return.
- rank: (default) Organized around a calculated value, usually a sum like time spent.
- interval: Organized around calendar time.
- member: Organized around users and groups,
|
| resolution_time | rs | interval | i |
1 of "month", "week", "day", "hour" |
Default is "hour". In an interval report, the X axis unit. In other words, data is summarizd into chunks of this size. |
| restrict_group | rg | group | g |
1 group name |
Provide the name of the group. Service will match that with your account to find group.
Avoid re-using the same name for multiple groups when creating them. Currently we do not prevent this. First match will be returned.
|
| restrict_user | ru | user | u |
1 user name or user email |
Provide the full (display) name of the user or email address. Service will match that with your account to find user. |
| restrict_begin | rb | | |
date time |
Sets the start day for data batch, inclusive (always at time 00:00, start hour/minute not supported)
Format ISO 8601 "YYYY-MM-DD"
|
| restrict_end | re | | |
date time |
Sets the end day for data batch, uninclusive (always at time 00:00, end hour/minute not supported)
So, to set 2009-07-31 data as last in your batch, set end date of 2009-08-01
Format ISO 8601 "YYYY-MM-DD"
|
| restrict_kind | rk | taxonomy | ty |
1 of "category", "activity", or "productivity"
"efficiency" is option when perspective is "interval" or "member"
|
Allows you to preprocess data through different statistical engines. The perspective dictates
the main grouping of the data, this provides different aspects of that main grouping.
- category: sums statistics for all activities into their category
- activity: sums statistics for individual applications / web sites / activities
- productivity: productivity calculation
- efficiency: efficiency calculation (not applicable in "rank" perspective)
|
| restrict_project | rj | project | |
name (of project) |
The name of a specific project in your account. If you create multiple projects with identical names, the first match returns.
The returned data will be limited to time active in only that project.
|
| restrict_thing | rt | taxon | tx |
name (of category, activity, or overview) |
The name of a specific overview, category, application or website.
For websites, use the domain component only if it starts with "www", eg. "www.nytimes.com" would be "nytimes.com".
The easiest way to see what name you should be using is to retrieve a list that contains the name you want, and inspect it for the exact names.
|
| restrict_thingy | ry | sub_taxon | tn |
name |
Refers to the specific "document" or "activity" we record for the currently active application, if supported.
For example, the document name active when using Microsoft Word. Available for most major applications and web sites.
Let us know if yours is not.
|
Output Formats
The initial release supports CSV and JSON output.
- CSV
layout provides rows of comma separated data with a header for column names at top.
- JSON
returns a JavaScript ready object. It has these properties:
- notes = String, a short explanation of the data envelope
- row_headers = Array, a label for the contents of each index in a row, in the order they appear in row
- rows = Array X Array, an array of data rows, where each row is itself an array described by the row_headers
Ruby API
Interface documentation for convienence wrapper around web service interface.
This is in progress, we will announce when this is complete.
Python API
Interface documentation for convienence wrapper around web service interface.
We'll
be posting detailed docs for this soon, but it's so simple you can just go grab and use it.
Javascript API
The JavaScript API is currently limited to a subset needed to render the embeded charts, and is controlled
only through the setting of JS variables prior to chart load.
The configurable variables are annotated in the embed pasteable code itself.
Security Precaution!
Putting your access key into javascript exposes it to the public, or who ever can get to the web page on which that javascript
is loaded. See Security Considerations.
Security Considerations
When you enable access to your data by embed or data api controls,
you generate a key that is saved in RescueTime's system. Essentially, this key provides an alternative
read-only authentication to your data. You can keep this key private, in which case it's just as safe as your login and password,
or publish it, without exposiing your account to other access or risks beyond the scope of the data.
The path followed to make embed access makes clear the limits of what it exposes.
It is assumed you will probably be sharing this data on your blog or intranet, where the provided
javascript interface necessarily exposes the key to anyone who cares to dig into their browser.
For this reason by default it does not allow raw data access, or the sending of parameters to change what data is presented.
In contrast, we assume data api access is being requested for use on the server side of things,
presumably in some code of your own. In this case, you can protect the key as you would any other server
side secret. It would never be seen in the browser, but used by your application to retrieve data from us then
process and render yourself somehow. So in this case, the key provides read-only access to your data by arbitrary
scope (within limits) through parameters.
At some point in the future, we may introduce optional PKI support as well, but that is currently not available.
|
