Skip to main content

A Python implementation of the REST API.

Project description


A Python implementation of the REST API.

splitsio currently supports read-only access. To upload runs, use the REST API directly.

Requires Python 3.7 or greater.

To install: pip3 install splitsio

Then to access the main data types in Python:

from splitsio import *



Get information about a game

>>> sms = Game.from_id('sms')
>>> sms
Game(id='15', name='Super Mario Sunshine', shortname='sms')
>>> sms.created_at

NOTE: for games, the identifier for querying is the shortname (here 'sms'), not the numerical id.

Get all games in the database

>>> games = Game.all()  # this can take a minute or so
>>> len(games)
>>> games[0]
Game(id='2206', name='007: Agent Under Fire', shortname='auf')

Search games by name/keyword

>>> mario_games ='mario')
>>> len(mario_games)
>>> mario_games[0]
Game(id='2524', name='Super Mario Advance 4: Super Mario Bros. 3', shortname='sma4')


Get the speedrun categories for a game

>>> oot = Game.from_id('oot')
>>> oot.categories[0]
Category(id='86832', name='No ACE')

Get category from id

>>> no_ace = Category.from_id('86832')
>>> no_ace
Category(id='86832', name='No ACE')


Get runners for a game or category

>>> oot_runners = Game.from_id('oot').runners()
>>> len(oot_runners)
>>> oot_runners[0]
Runner(id='35', twitch_id='31809791', twitch_name='cma2819', display_name='cma2819', name='cma2819')
>>> no_ace_runners = Category.from_id('86832').runners()
>>> no_ace_runners[0]
Runner(id='32189', twitch_id='63370787', twitch_name='bigmikey_', display_name='bigmikey_', name='bigmikey_')

Get runner from id

>>> bigmikey = Runner.from_id('bigmikey_')
>>> bigmikey
Runner(id='32189', twitch_id='63370787', twitch_name='bigmikey_', display_name='bigmikey_', name='bigmikey_')

NOTE: for runners, the identifier for querying is the name all lowercased (here 'bigmikey_'), not the numerical id.


Get runs for a game, category, or runner

>>> oot_runs = Game.from_id('oot').runs()
>>> run = oot_runs[0]
>>> run.realtime_duration_ms
>>> run.program
>>> run.attempts
>>> len(Category.from_id('86832').runs())
>>> len(Runner.from_id('bigmikey_').runs())

Get attempt histories for a run and its segments

>>> run = Game.from_id('oot').runs()[0]
>>> run = Run.from_id(, historic = True)
>>> len(run.histories)
>>> run.histories[1]
History(attempt_number=89, realtime_duration_ms=1507300, gametime_duration_ms=None, started_at='2020-03-10T20:06:08.000Z', ended_at='2020-03-10T20:31:15.000Z')
>>> run.segments[0].name
'Sword Get'
>>> len(run.segments[0].histories)
>>> run.segments[0].histories[0]
History(attempt_number=2, realtime_duration_ms=271832, gametime_duration_ms=0, started_at=None, ended_at=None)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

splitsio-0.1.1.tar.gz (9.8 kB view hashes)

Uploaded Source

Built Distribution

splitsio-0.1.1-py3-none-any.whl (9.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page