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.

Files for splitsio, version 0.1.1
Filename, size File type Python version Upload date Hashes
Filename, size splitsio-0.1.1-py3-none-any.whl (9.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size splitsio-0.1.1.tar.gz (9.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page