Splitwise Ruby Gem

A Ruby gem for the Splitwise API.

Installation

Add this line to your application's Gemfile:

gem 'splitwise'

And then execute:

$ bundle

Or install it yourself as:

$ gem install splitwise

Configuration

follow this to get required key and secret

require 'splitwise'

SPLITWISE_KEY = <YOUR_CONSUMER_KEY> 
SPLITWISE_SECRET = <YOUR_CONSUMER_SECRET>
Splitwise.access_token = access_token 

here access_token is access token obtained after authenticating app by user, more about it below.

Usage

All data returned will be in string format. Do JSON.parse(response) to convert it to json.

• API Methods

  • get_currencies

    Splitwise::Request.new.fetch("get_currencies")

  • get_categories

    Splitwise::Request.new.fetch("get_categories")

• Users

  • get_current_user

    Splitwise::Users.get_current_user

  • get_user

    Splitwise::Users.user_info(id) 
    # 'id' of user who shares a group or a friendship with current user

  • update_user_info

    Splitwise::Users.update_user(id, data)
    # id - current_user_id or user_id of invited user who has not logged in yet
    # data - Hash of Parameters

    • Parameters:

      • first_name, last_name, email, password, locale, date_format, default_currency, default_group_id, notification_settings

      • Eg:

        id = 123
        data = { 'first_name' => 'first', 'last_name' => 'last', ... }
        Splitwise::Users.update_user(id, data)

    • Note:
      1. A user can update anything about himself.
      2. For other users (for users who is acquainted with but haven’t logged in yet) only [first_name, last_name, email] can be updated.

• Groups

  • list_groups : list all groups of current user

    Splitwise::Groups.list_groups

  • group_info : get group info of group_id

    Splitwise::Groups.group_info(group_id)

  • create : create group

    Splitwise::Groups.create(data)
    # data - Hash of Parameters

    • Parameters:
      • name (mandatory), group_type (optional), country_code (optional),
      • a list of group members (optional)
        1. users__ARRAYINDEX__PARAMNAME,
        2. params are either: (first_name, last_name, email) or (user_id)

  • delete: delete group

    Splitwise::Groups.delete(group_id)
    # Returns: {:success ⇒ true/false}

  • add_user_to_group: add a user to existing group

    Splitwise::Groups.add_user(data)
    # data - Hash of Parameters
    # Return: {:success ⇒ true/false, :errors ⇒ [any errors]}

    • Parameters:
      • group_id and user_id, or
      • group_id, first_name, last_name, email (should send an invite if successful and account does not already exist)

  • remove_user_from_group: remove user from an existing group

    Splitwise::Groups.remove_user(data)
    # data - Hash of Parameters (group_id, user_id)
    # Return: {:success ⇒ true/false, :errors ⇒ [any errors]}

• Expenses

  • list_all_expenses : get all your expenses

  Splitwise::Expenses.list_all_expenses

  • expense_info: get expense info of expense_id

    Splitwise::Expenses.expense_info(expense_id)

  • create_expense: create a new expense

    Splitwise::Expenses.create(data)
    # data - Hash of Parameters

    • Parameters:
      • payment, cost, description
      • refer this for more info

  • update_expense: update an expense

    Splitwise::Expenses.update_expense(expense_id, data)
    # data - Hash of Parameters

  • delete_expense: delete given expense

    Splitwise::Expenses.delete(expense_id)

• Friends

  • list_friends: list all friends of user

    Splitwise::Friends.list_friends

  • friend_info: get friend infformation

    Splitwise::Friends.friend_info(friend_id)

  • create_friend: create a new friend

    Splitwise::Friends.create(data)
    # data - Hash of Parameters

  • delete_friend: delete a friend

    Splitwise::Friends.unfriend(friend_id)

Usage guideline to integrate with Ruby on Rails / Sinatra app

Splitwise uses OAuth 1.0 for authenticating user which means it needs one time authorization from user. Read more about it here.

I have made a sample Sinatra app as a demo of API usage. Refer example.
I am using omniauth-splitwise for authentication Splitwise API.

How to run it:

1. cd example
2. bundle
3. Enter SPLITWISE_KEY and SPLITWISE_SECRET in the example_splitwise_api.rb
4. ruby example_splitwise_api.rb
5. Goto localhost:4567, you will be directed to authorization page.
6. Once authorized, you can use the api.

Contributing

1. Fork it ( https://github.com/divyum/splitwise-ruby/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

To-do's

• detailed readme (esp expenses, groups, friends ) - [ ] examples for each type - [ ] return values for each
• more error handling: - [ ] timeout - [ ] mandatory parameter checks
• test cases
• make create friends endpoint
• make more endpoints for fetching data