API Documentation

All API routes on this page should be prefixed with https://paceman.gg/stats/api/

API routes

getSessionNethers

Description

Returns nether enter count & average for a given timeframe

Parameters

  • name: Either MC username or twitch
  • hours: How many hours of stats to include (default: 24)
  • hoursBetween: The max number of hours between runs in a session (default: 6)

Examples

  • getSessionNethers?name=meebie&hours=24&hoursBetween=2

    Returns nether enter count and average for latest session in the last 24 hours, ignoring runs behind a >2 hour break (in case there are multiple sessions in a day)

    { "count": 3, "avg": "3:36" }
  • getSessionStats?name=meebie&hours=730&hoursBetween=730

    Returns all stats for 30-ish days (any hour values are valid, e.g 999999 for "lifetime")

    { "count": 20, "avg": "5:40" }

Edge cases

  • Invalid MC username/twitch provided:
    {"error": "Unknown user"} # Status code 404
  • If no runs are found for a valid player name:
    { "count": 0, "avg": "0:00" } # Status code 200

Caching

  • 20 seconds
  • There are no rate limits currently, but don't bother spamming this endpoint more than once every 20 seconds

getSessionStats

Description

Returns counts & average for all splits in a given timeframe

Parameters

  • name: Either MC username or twitch
  • hours: How many hours of stats to include (default: 24)
  • hoursBetween: The max number of hours between runs in a session (default: 6)

Examples

  • getSessionStats?name=meebie&hours=24&hoursBetween=2

    Returns stats for latest session in the last 24 hours, ignoring runs behind a >2 hour break (in case there are multiple sessions in a day)

    { "nether": { "count": 2, "avg": "4:36" }, "bastion": { "count": 0, "avg": "0:00" }, "fortress": { "count": 0, "avg": "0:00" }, "first_structure": { "count": 0, "avg": "0:00" }, "second_structure": { "count": 0, "avg": "0:00" }, "first_portal": { "count": 0, "avg": "0:00" }, "stronghold": { "count": 0, "avg": "0:00" }, "end": { "count": 0, "avg": "0:00" }, "finish": { "count": 0, "avg": "0:00" } }
  • getSessionStats?name=meebie&hours=730&hoursBetween=730

    Returns all stats for 30-ish days (any hour values are valid, e.g 999999 for "lifetime")

    { "nether": { "count": 1818, "avg": "2:25" }, "bastion": { "count": 432, "avg": "2:32" }, "fortress": { "count": 167, "avg": "4:40" }, "first_structure": { "count": 464, "avg": "2:26" }, "second_structure": { "count": 137, "avg": "5:28" }, "first_portal": { "count": 108, "avg": "7:04" }, "stronghold": { "count": 54, "avg": "9:36" }, "end": { "count": 33, "avg": "11:06" }, "finish": { "count": 13, "avg": "10:33" } }

Edge cases

  • Invalid MC username/twitch provided:
    {"error": "Unknown user"} # Status code 404
  • If no runs are found for a valid player name:
    { "nether": { "count": 0, "avg": "0:00" }, # etc, other splits with 0's here } # Status code 200

Caching

  • 20 seconds
  • There are no rate limits currently, but don't bother spamming this endpoint more than once every 20 seconds

Notes

  • first_structure and second_structure are recommended instead of bastion and fortress
  • second_structure requires either a rod if fort first, or >50 seconds between structures if bastion first

getSplitStats

Description

Returns count & average for a given split in a given timeframe

Parameters

  • name: Either MC username or twitch
  • hours: How many hours of stats to include (default: 24)
  • hoursBetween: The max number of hours between runs in a session (default: 6)
  • split: The split to get stats for (nether, bastion, fortress, first_structure, second_structure, first_portal, stronghold, end, finish)
  • maxTime: The slowest run to include in the average, in milliseconds

Examples

  • getSplitStats?name=meebie&split=bastion&maxTime=300000&hours=24&hoursBetween=2

    Returns number of sub 5 bastions for latest session in the last 24 hours, ignoring runs behind a >2 hour break (in case there are multiple sessions in a day)

    { "count": 2, "avg": "4:36" }

Edge cases

  • Invalid MC username/twitch provided:
    {"error": "Unknown user"} # Status code 404
  • If no runs are found for a valid player name:
    { "count": 0, "avg": "0:00" } # Status code 200

Caching

  • 20 seconds
  • There are no rate limits currently, but don't bother spamming this endpoint more than once every 20 seconds

Notes

  • first_structure and second_structure are recommended instead of bastion and fortress
  • second_structure requires either a rod if fort first, or >50 seconds between structures if bastion first

getWorld

Description

Returns data for a given run

Parameters

  • worldId: Either a numerical run ID, or the world ID hash

Examples

  • getWorld/?worldId=31aad8ee0540af3a0573ac959e85f8b81f3941010d8cd20a33b67d04b29a0237
  • getWorld/?worldId=251471
    { "data": { "id": 251471, # run id from stats db "worldId": "31aad8ee0540af3a0573ac959e85f8b81f3941010d8cd20a33b67d04b29a0237", # world id from paceman api (hash of world file path) "nickname": "dfanm", # mc username "uuid": "4990072b-252e-42f2-aef9-45cd765f2425", # mc uuid "twitch": "dfanm", # twitch account (or null) "nether": 146952, # IGT in ms "bastion": 200037, # IGT in ms (or null) "fortress": null, # IGT in ms (or null) "first_portal": null, # IGT in ms (or null) "stronghold": null, # IGT in ms (or null) "end": null, # IGT in ms (or null) "finish": null, # IGT in ms (or null) "netherRta": 152614, # RTA in ms "bastionRta": 211353, # RTA in ms (or null) "fortressRta": null, # RTA in ms (or null) "first_portalRta": null, # RTA in ms (or null) "strongholdRta": null, # RTA in ms (or null) "endRta": null, # RTA in ms (or null) "finishRta": null, # RTA in ms (or null) "insertTime": 1715824744, # unix timestamp (secs) of nether enter "updateTime": 1715824800, # unix timestamp (secs) of last split update "vodId": 2146675569, # twitch VOD id (or null) "vodOffset": 14503, # seconds from VOD start to run start (or null) }, "time": 1715929618254, # unix timestamp (ms) when this data was last cached "isLive": false # whether the run is currently in liveruns }

Edge cases

  • Invalid world/run ID:
    null # Status code 200

Caching

  • 5 seconds
  • There are no rate limits currently, but don't bother spamming this endpoint more than once every 5 seconds

Notes

  • If you need to constantly update splits for a run, consider liveruns instead

getRecentRuns

Description

Returns recent runs for a user

Parameters

  • name: Either MC username or twitch
  • hours: How many hours of stats to include (default: 24)
  • hoursBetween: The max number of hours between runs in a session (default: 6)
  • limit: Max number of runs to return (default: 10)

Examples

  • getRecentRuns?name=meebie&hours=24&limit=1

    Returns the most recent run for user "meebie" in the last 24 hours

    [ { "id": 252315, # run id from stats db "nether": 128750, # IGT in ms "bastion": 167565, # IGT in ms (or null) "fortress": null, # IGT in ms (or null) "first_portal": null, # IGT in ms (or null) "stronghold": null, # IGT in ms (or null) "end": null, # IGT in ms (or null) "finish": null, # IGT in ms (or null) "lootBastion": null, # IGT in ms (or null) "obtainObsidian": null, # IGT in ms (or null) "obtainCryingObsidian": null, # IGT in ms (or null) "obtainRod": null, # IGT in ms (or null) "time": 1715912736 # unix timestamp (secs) of nether enter } ]

Edge cases

  • Invalid MC username/twitch provided:
    {"error": "Unknown user"} # Status code 404
  • If no runs are found for a valid player name:
    [] # Status code 200

Caching

  • 20 seconds
  • There are no rate limits currently, but don't bother spamming this endpoint more than once every 20 seconds

Notes

  • If you need more details, such as RTA splits and VOD info, pass the run ID to getWorld

getLeaderboard

Description

Returns the leaderboard for a given category and type

Parameters

  • days: How many days of stats to include (default: 30)
    Valid values: 1, 7, 30, 9999
  • category: Which split to get results for (default: nether)
    Valid values: nether, bastion, fortress, first_structure, second_structure, first_portal, second_portal, stronghold, end, finish
  • type: Method of comparing values (default: count)
    Valid values: count, average, fastest, conversion
  • limit: Max number of players to return (default: 10, max: 999999)

Examples

  • getLeaderboard?category=nether&type=count&days=7&limit=1

    Returns the player with the most nether entries in the last 7 days

    [ { "uuid": "eb77c626-a8ff-4d25-b095-7918a5d19b59", # mc uuid "name": "Pjoes", # mc username "value": 50, # value for given type (nether enter count) "qty": 50, # qty (always present) "avg": 112957.62 # avg (always present) } ]

Caching

  • 10 minutes
  • There are no rate limits currently, but don't bother spamming this endpoint more than once every 10 minutes

Notes

  • Avoid using this if you can use getSessionStats instead.
  • getLeaderboard requires parsing all runs from all users during the given timeframe

getRecentTimestamps

Description

Returns unix timestamps for splits in recent runs

Parameters

  • name: Either MC username or twitch
  • limit: Max number of runs to return (default: 20, max: 50)
  • onlyFort: Whether to only include runs that have 2 structures (default: false)

Examples

  • getRecentTimestamps/?name=jojoe_77777&limit=1

    Returns timestamps for most recent run from player

    [ { "id": 123456, # run id "runName": "3:23 Bastion", # last split of run "start": 1714048026.945, # timestamp of run start (with decimals) "nether": 1714048131, # no decimals sorry "bastion": 1714048207.958, # with decimals (or null) "fortress": null, # with decimals (or null) "first_portal": null, # with decimals (or null) "stronghold": null, # with decimals (or null) "end": null, # with decimals (or null) "finish": null, # with decimals (or null) "realUpdate": null # more accurate but nullable, no decimals "lastUpdated": 1714048207 # always exists but affected by db patches, no decimals } ]

Edge cases

  • Invalid MC username/twitch provided:
    {"error": "Unknown user"} # Status code 404
  • If no runs are found for a valid player name:
    {"error": "No data found for this user"} # Status code 404

Caching

  • 10 seconds
  • There are no rate limits currently, but don't bother spamming this endpoint more than once every 10 seconds

Notes

  • Intended use case is clipping runs from local recordings
  • If you want IGT/RTA split info, use getRecentRuns instead.

getAllData

Description

Secret API to get all runs from all users for a given timeframe, DM jojoe77777 on Discord for access
Warning: This endpoint can be very slow and take a long time to return data