usc-api

A small, polite Python client for the Urban Sports Club (USC) public class-schedule API.

USC's mobile app talks to a JSON API that serves class schedules, venues, and categories without a login. usc-api wraps the read-only, public parts of that API in a typed Python client, so you can pull class times and live availability into your own scripts.

I built it because I wanted programmatic access to USC's schedule data instead of tapping through the app.

Install

pip install usc-api
# or, with uv:
uv add usc-api

Quickstart

>>> from usc_api import Client
>>> usc = Client()
>>> sessions = usc.get_venue_schedule(venue_id=12345)   # a venue id you care about
>>> s = sessions[0]
>>> s.title, s.start, s.spots.free, s.spots.max
('Some Class', '2026-04-13T18:00:00+02:00', 3, 20)

Each session is a typed ClassSession with a venue and live spots (free / max, plus a taken helper).

Usage

Find a venue's id by searching for it by name:

>>> venues = usc.search_venues("some studio name")
>>> [(v.id, v.name) for v in venues][:3]
[(12345, 'Some Studio'), ...]

Search classes across venues, optionally filtered by category id:

>>> results = usc.raw_courses(query="yoga", days=1)
>>> results["data"]["classes"][0]["title"]
'Morning Yoga'

List the category tree:

>>> tree = usc.get_categories()
>>> tree[0].name
'Aerial'

Because the search endpoints aren't city-scoped, filter results client-side:

>>> from usc_api import filter_by_city
>>> sessions = usc.get_venue_schedule(12345) + usc.get_venue_schedule(67890)
>>> local = filter_by_city(sessions, "Amsterdam")

The client is polite by default: one request at a time, a short delay between requests, an honest User-Agent, and exponential backoff on HTTP 429. Tune it via Client(min_interval=..., user_agent=..., timeout=...).

Command line

Installed as usc-api, so you can use it straight from the shell:

usc-api schedule 12345         # a venue's upcoming classes
usc-api search "yoga"          # search classes across venues
usc-api venues "some studio"   # search venues by name
usc-api categories             # print the category tree

API reference

See docs/endpoints.md for endpoints, parameters, and response shapes, and docs/notes.md for practical notes (city filtering, the capacity sentinel, website vs. API).

Limitations

• Unofficial. Not affiliated with or endorsed by Urban Sports Club. It talks to an undocumented API that can change or break without notice.
• Read-only, public data only. It reads schedules, venues, and categories. Account actions (bookings, favorites, waitlists) require authentication and are out of scope.
• Personal-scale. Built for a few venues and an occasional refresh — please keep it that way. Respect the rate limits; don't hammer the service.
• City filtering is client-side. Search endpoints return results across all USC cities; filter on venue.display_address yourself.

License

MIT — see LICENSE.