Toggl is one of the best time trackers in the market. It is simple, easy to learn and reliable. We have been using this tool on Swapps for more than three years and it has always been useful. Thanks to it, our performance has been improved significantly.

During one of our internal projects, we needed to get information from toggl and integrate it with our system. That is when we started working with python-toggl; You may find the code of the module at Github. Python-toggl allows you to get workspaces, projects and time entries information with no effort; reducing boilerplate and easing the development process. Let’s see how easy is to use this package.

First, let’s install it by simply running

pip install python-toggl

Then, let’s configure the Client

from toggl.api_client import TogglClientApi

configuration = {
    'token': "My Secret Token",
    'user_agent': 'swapps',
    'workspace_id': "XXXYYY"
}
client = TogglClientApi(configuration)

And That’s it!

Now, let’s get our registered projects.

In [1]: client.get_projects().json()                                            
Out[1]:
[{'active': True,
  'actual_hours': 10,
  'at': '2019-01-01T12:00:00+00:00',
  'auto_estimates': False,
  'billable': True,
  'cid': 12345678,
  'color': '8',
  'created_at': '2019-01-01T12:00:00+00:00',
  'hex_color': '#3750b5',
  'id': 12345678,
  'is_private': False,
  'name': 'Test project',
  'template': False,
  'wid': 123456}]

As you may see, it returns a list with the detail of all of our registered projects. It even returns the inactive projects. It also returns useful information such as the project id, that we will require to fetch its times, the creation datetime, etc.

Now, lets get all of the members of our team. This feature is useful if you want to get time information per team member instead of per project.

In[2]: members = client.get_workspace_members("my-workspace-id")
In[3]: members.json()
Out[3]:
[{'active': True,
 'admin': False,
 'at': '2019-01-01T00:00:00+00:00',
 'avatar_file_name': 'https://assets.toggl.com/avatars/f98355dfadcc3aac9de3851bca88b2c4.png',
 'email': '[email protected]',
 'group_ids': [123],
 'id': 123,
 'inactive': False,
 'invitation_code': None,
 'invite_url': None,
 'labour_cost': None,
 'name': 'Jose',
 'owner': False,
 'rate': None,
 'timezone': 'America/New_York',
 'uid': 123,
 'wid': 123}]

As you may see, it returns a list of all the members inside your team with their most important information such as their toggl Id, email, name, etc.

Now, Let’s get the most important element in toggl: times. The related method requires the toggl project ID and the date range you want to retrieve. Let’s check the code!

In [4]: from datetime import date                                              
In [5]: start_date = date(2019, 1, 1)                                           
In [6]: end_date = date(2019, 1, 31)
# the id '12345678' is obtained from the get_projects method
In [7]: client.get_project_times('12345678', start_date, end_date)
Out [7]:
{'data': [{'billable': None,
   'client': 'Test Client',
   'cur': None,
   'description': "This is my first tracked time!",
   'dur': 1526000,
   'end': '2019-01-21T09:00:35-05:00',
   'id': 12345,
   'is_billable': True,
   'pid': 12345678,
   'project': 'Test project',
   'project_color': '0',
   'project_hex_color': '#06aaf5',
   'start': '2019-01-21T08:35:09-05:00',
   'tags': [],
   'task': None,
   'tid': None,
   'uid': 123,
   'updated': '2019-01-21T09:00:45-05:00',
   'use_stop': True,
   'user': 'Jose Ariza'}],
 'per_page': 50,
 'total_billable': 1526000,
 'total_count': 1,
 'total_currencies': [{'amount': None, 'currency': None}],
 'total_grand': 1526000}

The method returns a list with all the time entries found for the required project between start_date and end_date. Each time entry contains information such as its start and end time, its duration, the user who created it, his/her id (uid), etc. As well, it returns how many time entries there are, how many time entries are returned per page, how much time is billable, etc. You may find the complete data reference here.

As well, if you need to use the method with extra parameters, for example the page number or the user id, you may use it like this:

In [8]: client.get_project_times('12345678', start_date, end_date, extra_params={"page": 2})

You may find a complete parameters guide here.

There is one small limitation with this endpoint: Toggl does not allow ranges greater than one year. So, if you need to retrieve the information from several years, you would need to use this method inside a loop; sending a request per required year.

And that’s it! in less that ten lines, we were able to get very useful information from our Toggl account without effort. If you are going to use the client in a bigger project, I strongly recommend to use a class to encapsulate it along with your integration to keep everything under control.

I hope that this entry was useful to you and that you were able to start improving your work from the data obtained from Toggl. Happy coding!