Toggl API v8
Toggl is a time tracking tool.
togglv8 is a Ruby Wrapper for Toggl API v8. It is designed to mirror the Toggl API as closely as possible.
togglv8 supports both Toggl API and Reports API
Change Log
See CHANGELOG for a summary of notable changes in each version.
Installation
Add this line to your application's Gemfile:
gem 'togglv8'
And then execute:
$ bundle
Or install it yourself as:
$ gem install togglv8
Initialization
TogglV8::API
TogglV8::API communicates with Toggl API v8 and can be initialized in one of three ways.
TogglV8::API.new # reads API token from file ~/.toggl
TogglV8::API.new(api_token) # explicit API token
TogglV8::API.new(email, password) # email & password
TogglV8::ReportsV2
TogglV8::ReportsV2 communicates with Toggl Reports API v2 and can be initialized in one of three ways. Toggl.com requires authentication with an API token for Reports API v2.
TogglV8::ReportsV2.new # reads API token from file ~/.toggl
TogglV8::ReportsV2.new(toggl_api_file: toggl_file) # reads API token from toggl_file
TogglV8::ReportsV2.new(api_token: api_token) # explicit API token
Note: workspace_id
must be set in order to generate reports.
toggl = TogglV8::API.new
reports = TogglV8::ReportsV2.new
reports.workspace_id = toggl.workspaces.first['id']
Usage
This short example shows one way to create a time entry for the first workspace of the user identified by <API_TOKEN>
. It then generates various reports containing that time entry.
require 'togglv8'
require 'json'
toggl_api = TogglV8::API.new(<API_TOKEN>)
user = toggl_api.me(all=true)
workspaces = toggl_api.my_workspaces(user)
workspace_id = workspaces.first['id']
time_entry = toggl_api.create_time_entry({
'description' => "My awesome workspace time entry",
'wid' => workspace_id,
'duration' => 1200,
'start' => toggl_api.iso8601((Time.now - 3600).to_datetime),
'created_with' => "My awesome Ruby application"
})
begin
reports = TogglV8::ReportsV2.new(api_token: <API_TOKEN>)
begin
reports.summary
rescue Exception => e
puts e.message # workspace_id is required
end
reports.workspace_id = workspace_id
summary = reports.summary
puts "Generating summary JSON..."
puts JSON.pretty_generate(summary)
puts "Generating summary PDF..."
reports.write_summary('toggl_summary.pdf')
puts "Generating weekly CSV..."
reports.write_weekly('toggl_weekly.csv')
puts "Generating details XLS..."
reports.write_details('toggl_details.xls')
# Note: toggl.com does not generate Weekly XLS report (as of 2016-07-24)
ensure
toggl_api.delete_time_entry(time_entry['id'])
end
See specs for more examples.
Note: Requests are rate-limited. The togglv8 gem will handle a 429 response by pausing for 1 second and trying again, for up to 3 attempts. See Toggl API docs:
For rate limiting we have implemented a Leaky bucket. When a limit has been hit the request will get a HTTP 429 response and it's the task of the client to sleep/wait until bucket is empty. Limits will and can change during time, but a safe window will be 1 request per second. Limiting is applied per api token per IP, meaning two users from the same IP will get their rate allocated separately.
Debugging
The TogglV8::API#debug
method determines if debug output is printed to STDOUT. This code snippet demonstrates the debug output.
require 'togglv8'
toggl = TogglV8::API.new
toggl.debug(true) # or simply toggl.debug
user1 = toggl.me
puts "user: #{user1['fullname']}, debug: true"
puts '-'*80
toggl.debug(false)
user2 = toggl.me
puts "user: #{user2['fullname']}, debug: false"
Documentation
Run rdoc
to generate documentation. Open doc/index.html
in your browser.
Also available on DocumentUp
Acknowledgements
- Thanks to the following contributors (in alphabetical order):
- archonic (fork)
- ddiatmb (fork)
- itaymendel
- ppawlikmb (fork)
- worldsmithroy (fork)
- Thanks to Koen Van der Auwera for the Ruby Wrapper for Toggl API v6
- Thanks to the Toggl team for exposing the API.
Contributing
- Fork it ( https://github.com/kanet77/togglv8/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Pull Requests that include tests are much more likely to be accepted and merged quickly.
License
Copyright (c) 2013-2016 Tom Kane. Released under the MIT License. See LICENSE.txt for details.