Whoopy

A Python library for interacting with the Whoo location-sharing app API.

Note: This library is for educational purposes only and is not intended for bot operations.

Table of Contents

• Installation
• Quick Start
• Authentication
• API Reference
  • Account Management
  • Friend Management
  • Location
  • Messaging
  • Status
• Enums
• Error Handling
• Examples

Installation

pip install -e .

Or install dependencies only:

pip install -r requirements.txt

Quick Start

from whoopy import Whoopy, BatteryState

# Login with access token
cl = Whoopy(access_token='your_token_here')

# Get your profile
print(cl.info())

# Update your location
cl.update_location(
    location={"latitude": 35.6762, "longitude": 139.6503},
    level=80,
    state=BatteryState.DISCHARGING
)

# Get friends' locations
locations = cl.get_locations()
for name, data in locations.items():
    print(f"{name}: {data['map']}")

Authentication

Whoopy supports three authentication methods:

1. Token Authentication

cl = Whoopy(access_token='your_token_here')

2. Email/Password Authentication

cl = Whoopy(email='user@example.com', password='your_password')

3. No Authentication (for account creation only)

cl = Whoopy()
account = cl.create_account(...)

Disable Login Message

cl = Whoopy(access_token='your_token', verbose=False)

API Reference

Account Management

info()

Get current user's profile information.

user = cl.info()
print(user['display_name'])
print(user['username'])

Returns: dict - User profile data

---

email_login(email, password)

Login with email and password.

Parameter	Type	Description
email	str	Email address
password	str	Password

cl = Whoopy()
result = cl.email_login('user@example.com', 'password')
token = result['access_token']

Returns: dict - Contains access_token

---

create_account(email, password, name, profile_image, username, location=None)

Create a new account.

Parameter	Type	Description
email	str	Email address
password	str	Password
name	str	Display name
profile_image	str	Profile image URL
username	str	Username (unique ID)
location	dict	Optional. Initial location {"latitude": float, "longitude": float}

cl = Whoopy()
account = cl.create_account(
    email='new@example.com',
    password='secure_password',
    name='John Doe',
    profile_image='profile_images/images/default.jpeg',
    username='johndoe123',
    location={"latitude": 35.6762, "longitude": 139.6503}
)

Returns: dict - Account information with access_token

---

update_account(name=None, profile_image=None, username=None)

Update account information. All parameters are optional.

Parameter	Type	Description
name	str	New display name
profile_image	str	New profile image URL
username	str	New username

cl.update_account(name='New Name', username='newusername')

Returns: dict - Updated account information

---

delete_account(alert=True)

Delete the account.

Parameter	Type	Description
alert	bool	Show confirmation prompt (default: True)

cl.delete_account(alert=False)  # Delete without confirmation

Returns: str - 'Success' or 'Cancel'

---

Friend Management

get_friends()

Get your friends list.

friends = cl.get_friends()
for friend in friends['friends']:
    print(friend['display_name'], friend['id'])

Returns: dict - Friends list

---

get_requested()

Get pending friend requests you received.

requests = cl.get_requested()

Returns: dict - Friend request list

---

get_user(user_id, friends=False)

Get information about a specific user.

Parameter	Type	Description
user_id	int	Target user ID
friends	bool	Include user's friends list (default: False)

# Basic info only
user = cl.get_user(12345)

# Include friends list (handles pagination automatically)
user = cl.get_user(12345, friends=True)
print(f"Friends count: {len(user['friends'])}")

Returns: dict - User information

---

find_user(user_name)

Search for a user by display name.

Parameter	Type	Description
user_name	str	Display name to search

user = cl.find_user('John')
print(user['id'], user['display_name'])

Returns: dict - First matching user

Raises: ValueError if no user found

---

request_friend(user_id)

Send a friend request.

Parameter	Type	Description
user_id	int	Target user ID

cl.request_friend(12345)

Returns: dict - Response information

---

delete_requested(user_id)

Cancel a sent friend request.

Parameter	Type	Description
user_id	int	Target user ID

cl.delete_requested(12345)

Returns: dict - Response information

---

Location

update_location(location, level=100, state=BatteryState.UNKNOWN, speed=0.0, stayed_at=None, horizontal_accuracy=None)

Update your location and battery status.

Parameter	Type	Description
location	dict	{"latitude": float, "longitude": float}
level	int	Battery level 0-100 (default: 100)
state	BatteryState	Battery state enum (default: UNKNOWN)
speed	float	Speed in km/h (default: 0.0)
stayed_at	str	Stay timestamp (optional)
horizontal_accuracy	float	GPS accuracy in meters (optional)

from whoopy import BatteryState

cl.update_location(
    location={"latitude": 35.6762, "longitude": 139.6503},
    level=75,
    state=BatteryState.DISCHARGING,
    speed=4.5  # km/h (walking speed)
)

Note: Speed is automatically converted from km/h to m/s internally.

Returns: dict - Updated location data

---

get_locations(user_id=None)

Get friends' location information with Google Maps links.

Parameter	Type	Description
user_id	int	Filter by specific user (optional)

locations = cl.get_locations()

for username, loc in locations.items():
    print(f"{username}:")
    print(f"  Position: {loc['latitude']}, {loc['longitude']}")
    print(f"  Speed: {loc['speed']} m/s")
    print(f"  Battery: {loc['user']['battery_level']}%")
    print(f"  Map: {loc['map']}")
    print(f"  Street View: {loc['pano']}")

Returns: dict - Dictionary with usernames as keys

Each location includes:

• latitude, longitude - Coordinates
• speed - Speed in m/s
• map - Google Maps satellite view URL
• pano - Google Street View URL
• user - User info including battery level

---

reacquire_location(user_id)

Request a friend to update their location.

Parameter	Type	Description
user_id	int	Target user ID

cl.reacquire_location(12345)

Returns: dict - Response information

---

Messaging

send_message(room_id, content)

Send a text message to a chat room.

Parameter	Type	Description
room_id	str	Chat room ID
content	str	Message text

cl.send_message(room_id='abc123', content='Hello!')

Returns: dict - Sent message information

---

send_stamp(user_id, stamp_id, quantity)

Send a stamp (sticker) to a user.

Parameter	Type	Description
user_id	int	Recipient user ID
stamp_id	int	Stamp ID
quantity	int	Number of stamps to send

cl.send_stamp(user_id=12345, stamp_id=83, quantity=1)

Returns: Response - HTTP response object

---

Status

online()

Set your status to online.

cl.online()

Returns: dict - Response information

---

offline()

Set your status to offline.

cl.offline()

Returns: str - 'success'

---

Enums

BatteryState

from whoopy import BatteryState

BatteryState.UNKNOWN      # 0 - Unknown state
BatteryState.CHARGING     # 1 - Charging
BatteryState.FULL         # 2 - Fully charged
BatteryState.DISCHARGING  # 3 - On battery

HttpStatus

from whoopy import HttpStatus

HttpStatus.OK                     # 200
HttpStatus.NO_CONTENT             # 204
HttpStatus.BAD_REQUEST            # 400
HttpStatus.UNAUTHORIZED           # 401
HttpStatus.FORBIDDEN              # 403
HttpStatus.NOT_FOUND              # 404
HttpStatus.INTERNAL_SERVER_ERROR  # 500

Error Handling

All API methods raise Exception on failure:

try:
    cl = Whoopy(access_token='invalid_token')
except Exception as e:
    print(f"Authentication failed: {e}")
    # Output: Request Error[401] (auth)

Methods that require authentication will raise:

Exception: Message: Token is required.

Examples

See examples.py for more detailed usage examples.

Complete Example: Location Tracking

from whoopy import Whoopy, BatteryState

# Initialize
cl = Whoopy(access_token='your_token')

# Get current user info
me = cl.info()
print(f"Logged in as: {me['display_name']}")

# Update my location
cl.update_location(
    location={"latitude": 35.6812, "longitude": 139.7671},
    level=85,
    state=BatteryState.DISCHARGING,
    speed=0.0
)

# Get all friends' locations
locations = cl.get_locations()
for name, loc in locations.items():
    print(f"\n{name}:")
    print(f"  Coordinates: ({loc['latitude']}, {loc['longitude']})")
    print(f"  Google Maps: {loc['map']}")

# Go offline when done
cl.offline()

License

MIT License