TogglPy Python Library

To use TogglPy, you must instantiate the Toggl class and provide your Toggl API key using the setAPIKey method. This key is used in the request headers for all subsequent API calls. You can also customize the User-Agent header using setUserAgent.

from toggl.TogglPy import Toggl

toggl = Toggl()
toggl.setAPIKey('YOUR_API_KEY')
# Optional: set a custom user agent
toggl.setUserAgent('MyCustomAgent/1.0')

Install TogglPy using pip. To use the library, import the Toggl class from toggl.TogglPy. You can authenticate using either email/password credentials or a personal API token.

Note: If you need to access the Reports API endpoints, you must use your personal API token via setAPIKey().

pip install -U TogglPy

from toggl.TogglPy import Toggl

toggl = Toggl()

# Use API Token (Required for Reports API)
toggl.setAPIKey('<API-TOKEN>')

# OR use credentials
toggl.setAuthCredentials('<EMAIL>', '<PASSWORD>')

You can control timers and create custom time entries using the following methods:

• startTimeEntry(description, project_pid): Starts a new timer for a specific project ID.
• stopTimeEntry(entry_id): Stops a running timer using its ID.
• createTimeEntry(...): Creates a custom time entry with specific parameters like duration, project, client, and time.

# Start a new timer
toggl.startTimeEntry("my description", 10959693)

# Stop a timer (requires the entry ID)
toggl.stopTimeEntry(entry_id)

# Create a custom entry for today at 10 AM for 9 hours
toggl.createTimeEntry(hourduration=9, projectname='GoogleDrive', hour=10)

# Create a custom entry with client name and specific date
toggl.createTimeEntry(hourduration=9, projectname='GoogleDrive', clientname='Google', month=1, day=31, hour=10)

You can interact with any Toggl API endpoint directly using request() for GET requests or postRequest() for POST requests. Pass request data as a dictionary to the parameters argument.

# GET request with parameters
data = {
    'id': 42,
    'some_key': 'some_value',
    'user_agent': 'TogglPy_test',
}
response = toggl.request("https://api.track.toggl.com/api/v8/some/endpoint", parameters=data)

# POST request with parameters
post_data = {
    "project": {
        "name": "some project",
        "wid": 777,
        "template_id": 10237,
        "is_private": True,
        "cid": 123397
    }
}
response = toggl.postRequest("https://api.track.toggl.com/api/v8/projects", parameters=post_data)

To generate and save PDF reports (Summary, Weekly, or Detailed), you must authenticate with your personal API token. Provide a dictionary containing report parameters (like workspace_id, since, and until) and the desired filename.

# Authentication with API Key is required for this
data = {
    'workspace_id': 0000,
    'since': '2015-04-27',
    'until': '2015-05-03',
}

toggl.getWeeklyReportPDF(data, "weekly-report.pdf")
toggl.getDetailedReportPDF(data, "detailed-report.pdf")
toggl.getSummaryReportPDF(data, "summary-report.pdf")

If the built-in methods do not cover your needs, you can interact directly with the Toggl API endpoints.

• request(endpoint, parameters=None): Makes a request to the specified endpoint and returns the response as a parsed JSON dictionary.
• requestRaw(endpoint, parameters=None): Makes a request to the specified endpoint and returns the raw response data (typically JSON).

TogglPy provides methods to retrieve workspace and client information.

• getWorkspaces(): Returns all workspaces visible to the user.
• getWorkspace(name=None, id=None): Returns the first workspace matching a specific name or ID.
• getWorkspaceProjects(id): Returns all projects associated with a specific Workspace ID.
• getClients(): Returns all clients visible to the user.
• getClient(name=None, id=None): Returns the first client matching a specific name or ID.

TogglPy supports generating various report types (Detailed, Summary, and Weekly) both as data objects and as PDF files.

Report Types

• Detailed Reports: Use getDetailedReport(data) for data or getDetailedReportPDF(data, filename) to save as a PDF. Use getDetailedReportPages(data) to retrieve data across all pages.
• Summary Reports: Use getSummaryReport(data) for data or getSummaryReportPDF(data, filename) to save as a PDF.
• Weekly Reports: Use getWeeklyReport(data) for data or getWeeklyReportPDF(data, filename) to save as a PDF.

Note: The data parameter typically contains the parameters required by the Toggl API for the specific report type.

TogglPy provides helper methods to retrieve workspaces and clients. You can fetch all items or find a specific one by name or ID.

# Get all workspaces and clients
workspaces = toggl.getWorkspaces()
clients = toggl.getClients()

# Find a specific client by name
client = toggl.getClient(name="John Doe")

# Find a specific workspace by name
workspace = toggl.getWorkspace(name="Personal")

# Find by ID
client_by_id = toggl.getClient(id=12345)
workspace_by_id = toggl.getWorkspace(id=67890)