Splitwise Python SDK

This is the python sdk for Splitwise APIs. Pull requests and bug reports are welcomed.

Latest Version

The latest version of splitwise SDK is Splitwise-3.0.0

Docs

The detailed docs are hosted at readthedocs.org

Installation

Install using pip :

$ pip install splitwise

Register your application

Register your application on splitwise and get your consumer key and consumer secret.

Include splitwise in your application

from splitwise import Splitwise

Get splitwise instance

To get an instance to splitwise just provide the consumer key and secret.

sObj = Splitwise("<consumer key>","<consumer secret>")

Debug

To get the debug logs use

import logging
logging.basicConfig(level=logging.DEBUG)

Usage

Authorize splitwise

Before you can make call to splitwise, you need to get access token of the user on whose behalf you will be making call. Think of it as login with splitwise. Its based on OAuth and its a 2 step process.

OAuth1

1. Get the Authorize URL and Secret. Redirect the user to the Authorize url and store the secret in somewhere for eg in session.

   sObj = Splitwise("<consumer key>","<consumer secret>")
   url, secret = sObj.getAuthorizeURL()
   #Store secret so you can retrieve it later
   #redirect user to url
   

2. After authorization splitwise will redirect the user back to the callback url that you provided during registration. It will also provide oauth_token and oauth_verifier that can be used along with secret from step 1 to get access token. The below snippet is from Flask application to extract parameters and then using SDK to get access token. This access token can be stored in your db to make calls on his/her behalf.

   oauth_token    = request.args.get('oauth_token')
   oauth_verifier = request.args.get('oauth_verifier')
   
   sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
   access_token = sObj.getAccessToken(oauth_token,session['secret'],oauth_verifier)
   
   session['access_token'] = access_token
   

OAuth2

It is now possible to use OAuth2 with Splitwise. For details you can refer to readthedocs.org

API Key

You can use API Key provided by Splitwise to test APIs for your user.

sObj = Splitwise("<consumer key>","<consumer secret>",api_key="<api key>")
current = sObj.getCurrentUser()

Get data from splitwise

Once you have the access token you can make the calls to splitwise. Get the splitwise instance and set the access token and then make authorized calls.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])
sObj.getFriends()

Get Current User

You can use getCurrentUser() to get the current user. It returns a CurrentUser object.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])
sObj.getCurrentUser()

Get User

You can use getUser(id) to get the user. It returns a User object.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])
id = 7123
user = sObj.getUser(id)

Update User

You can use updateUser(user) to update the user. It takes in a partial CurrentUser object with atleast id set. It returns a CurrentUser object. Note that you can update anything for your user and first_name, last_name and email for any acquaintances who has not created account yet.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])
user = User()
user.setId(10)
user.setFirstName("naman")
updated_user, error = sObj.updateUser(user)
print(updated_user.getFirstName())

Get Friends

You can use getFriends() to get all the friends of the current user along with the balances. It returns a list of Friend objects.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])
sObj.getFriends()

Get Groups

You can use getGroups() to get all the groups of the current user along with the members and balances. It returns a list of Group objects.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])
sObj.getGroups()

Get Currencies

You can use getCurrencies() to get all the currencies supported by splitwise. It returns a list of Currency objects.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])
sObj.getCurrencies()

Get Category

You can use getCategories() to get all the categories and sub categories provided by splitwise. It returns a list of Category objects.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])
sObj.getCategories()

Get Group

You can use getGroup(id) to get the particular group of the current user along with the members and balances. It returns a Group object. Use id as 0 to get all non group expenses.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])
sObj.getGroup(43233)

Get Expenses

You can use getExpenses(offset,limit,group_id,friend_id,dated_after,dated_before,updated_after,updated_before,visible) to get all the expenses of the current user based on filter options. It returns a list of Expense objects.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])
sObj.getExpenses()

Get Expense

You can use getExpense(id) to get the particular expense of the current user. It returns a Expense object.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])
sObj.getExpense(43233)

Create Expense

You can use createExpense(Expense) to create a new Expense. It takes in parameter a partial Expense object and returns an Expense object.

Following things need to be set on the Expense object.

1. Cost
2. Description
3. Users - Should be a list of ExpenseUser with id and paidShare and owedShare set.

from splitwise.expense import Expense
from splitwise.user import ExpenseUser

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])

expense = Expense()
expense.setCost('10')
expense.setDescription("Testing")
expense.setReceipt("/Users/naman/receipt.jpg")

user1 = ExpenseUser()
user1.setId(79774)
user1.setPaidShare('10.00')
user1.setOwedShare('2.0')

user2 = ExpenseUser()
user2.setId(281236)
user2.setPaidShare('0.00')
user2.setOwedShare('8.00')

users = []
users.append(user1)
users.append(user2)

expense.setUsers(users)

expense, errors = sObj.createExpense(expense)
print expense.getId()

Create Group

You can use createGroup(Group) to create a new Group. It takes in parameter a partial Group object and returns an Group object.

Following things need to be set on the Group object.

1. Name
2. Users - Should be a list of User with either FirstName, LastName and Email or just Id set.

from splitwise.group import Group
from splitwise.user import User

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])

group = Group()
group.setName("Testing")

user1 = User()
user1.setId(79774)

user2 = User()
user2.setId(281236)

users = []
users.append(user1)
users.append(user2)

group.setMembers(users)

group, errors = sObj.createGroup(group)
print group.getId()

Add user to group

You can use addUserToGroup(User, group_id) to add user to group. It takes in a splitwise.user.User object that has either id or firstName and email set and a group_id.

from splitwise.group import Group
from splitwise.user import User

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])

user = User()
user.setId(1223)

success, user, errors = sObj.addUserToGroup(user, 4456)

print(success)

Delete group

You can use deleteGroup(group_id) to delete an existing group.

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])

success, errors = sObj.deleteGroup(4456)

print(success)

Update Expense

You can use updateExpense(Expense) to update an existing Expense. It takes in parameter a partial Expense object and returns an Expense object.

Following things need to be set on the Expense object.

1. Id
2. any field you would want to update

from splitwise.expense import Expense

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])

expense = Expense()
expense.id = 12345678
expense.setCost('10')
expense.setDescription("Updated description")

expense, errors = sObj.updateExpense(expense)
print(expense.getId())

or update the fetched expense

from splitwise.expense import Expense

sObj = Splitwise(Config.consumer_key,Config.consumer_secret)
sObj.setAccessToken(session['access_token'])

expense, error = sObj.getExpense(12345)
expense.setDescription("Updated description")

expense, errors = sObj.updateExpense(expense)
print(expense.getDescription())

Delete expense