Home

rescuetime

A Ruby interface to the RescueTime APIs. Rescuetime provides a simple DSL for interacting with your personal or team RescueTime data. Currently, this gem only supports the Data Analytics API with API key authorization.

For more information about RescueTime, visit the RescueTime homepage.

Navigation

• Installation
• Usage
  • Prerequisites
  • In a Nutshell (skip to here if you want to see the syntax)
  • Custom Report Formatters
  • Defaults

Useful Links

• Gem API Documentation (RDoc)
• RescueTime key management
• RescueTime API Docs

Installation

Add this line to your application's Gemfile:

gem 'rescuetime'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rescuetime

Usage

Prerequisites

Ensure that you are using a supported ruby version for your project.

In order to use access your RescueTime data, you will need an API key. If you do not already have a key, visit the API key management page.

In a Nutshell

require 'rescuetime'

@client = Rescuetime::Client.new(api_key: <YOUR_API_KEY>)
@client.api_key?            #=> true
@client.valid_credentials?  #=> true

# Rescuetime uses lazy evaluation, so until you either manipulate the collection
# or explicitly call for it (with #all), it will remain in the Rescuetime::Collection
# format.
@client.overview.class      #=> Rescuetime::Collection
@client.overview.all.class  #=> Array
@client.overview.map {...}  #=> Array

@client.overview      # Returns an overview report, defaulting to "rank" order
@client.categories    # Returns a catigorical report, defaulting to "rank" order
@client.activities    # Returns a list of activities, defaulting to "rank" order
@client.productivity  # Returns a productivity report, defaulting to "rank" order
@client.efficiency    # Returns an efficiency report, defaulting to "time order"

##
# Date Range (:date, :frome, :to)
# -------------------------------
# Defaults:
#   If nothing is provided, defaults to current day (since 00:00)
#   If :from is provided, defaults :to to current day
#
# Valid date formats:
#   - "YYYY-MM-DD"    - "MM-DD-YYYY"    - "DD/MM"
#   - Object#strftime
@client.overview                      # Fetches results from today
@client.overview.date('2014-12-31')   # Fetches results from Dec 31, 2014.
@client.overview.from('2015-01-01').to('2015-02-01')
@client.overview.from('2015-04-01')


##
# Report Order (:order_by)
# ------------------------
# Defaults:
#   Efficiency defaults to chronological order; everything else defaults to "rank" order
#
# You can order_by:
#   :rank, :time, or :member (note: efficiency can't be sorted by :rank)
#
# When ordering by time, default interval is 1 hour.
# Options include:
#   :minute (5-minute chunks), :hour, :day, :week, :month
@client.efficiency    # Defaults to :time
@client.productivity  # Defaults to :rank

@client.productivity.order_by(:rank)
@client.productivity.order_by(:time)
@client.productivity.order_by(:member)

@client.productivity.order_by(:time)  # Defaults to :hour
@client.productivity.order_by(:time, interval: :minute)
@client.productivity.order_by(:time, interval: :hour)
@client.productivity.order_by(:time, interval: :day)
@client.productivity.order_by(:time, interval: :week)
@client.productivity.order_by(:time, interval: :month)

##
# Name Restrictions (:where)
# --------------------------
# Fetches results where name is an exact match
# The following reports can be limited by name:
#   :activities, :categories, :overview
#
# For activities, you can also limit by specific document title
#   (ex. document 'rails/rails' for activity 'github.com')
#   Try the query sans document for a list of valid options
#
# Names must be exact matches.
@client.activities.where(name: 'github.com')
@client.categories.where(name: 'Intelligence')
@client.overview.where(name: 'Utilities')
@client.activities.where(name: 'github.com', document: 'vcr/vcr')

##
# Formatting options (:csv, :array)
# ---------------------------------
@client.efficiency                  # Default return type is Array<Hash>
@client.efficiency.format(:cvs)     # Returns a CSV
@client.efficiency.format(:array)   # Returns Array<Hash>

Custom Report Formatters

See Adding Custom Report Formatters

Defaults

The Rescuetime::Client#activities action has the following defaults:

{ order_by:         'rank'
  interval:         'hour'
  date:             <TODAY> }