API FAQ

What is this?

A web service that allows programs to retrieve server information for the PC version of Jedi Academy.

How is this?

A backend service periodically gets server details and updates the API. The list of servers to check is retrieved from multiple master servers (Raven, JKHub, MBII) and the unique are combined into one comprehensive list. The results are the same as what you would see in-game, with some enhancement.

Why is this?

An unpublished barebones version of this (just spat out all the data) was quickly setup for tracking Movie Battle's server statistics. While functional, it had some issues due to inherent limitations of the the old version of the q3serverlist script and the glue that was added to move data around and display it (rsync, more php...). When I decided to rewrite everything myself, it was the perfect time to also implement this properly.

How do I use this?

Any programming language capable of making HTTP requests and parsing JSON responses should work (so practically everything). You could even use cURL and jq from a shell environment if you really wanted.

Previewing and testing the endpoints can be done quickly from any browser (though you may want an extension to format the JSON if not using Firefox). You could also use a dedicated development tool like Postman.

• Terms of Use:
• Please do not make an unreasonable number of requests. There are rate limits in place, though they should be generous enough for typical use. If you hit them enough for it to be a problem, consider altering how your app works (such as caching responses for a short time).
• Privacy Policy:
• The API does not send or store any information except that which is made publicly available on Jedi Academy servers that list themselves with commonly used master servers. Only currently online servers will be returned in queries.
• If you are the owner of a public server that you later decide to make hidden (not sending heartbeats to a public master server), you may make a request here to have it removed from the API. In most cases this should not be necessary if the server is simply taken offline for a short time.
• Terms of Service:
• This service is offered as-is with no warranty or promise of availability.

Endpoints

/api/get/list

Returns a list of servers with basic information. Ordered by numplayers and sv_hostname_nocolor.

• game
• hostname
• max_age
• min_age
• max_players
• min_players
• other_cvar
• player
• (any cvar or meta properties)

/api/get/detail

Returns a list of servers with all cvar and player details. Ordered by numplayers and sv_hostname_nocolor.

• game
• hostname
• max_age
• min_age
• max_players
• min_players
• other_cvar
• player
• (any cvar or meta properties)

/api/get/stats

Returns some statistics for the selected game.

• game

Filter Details

All filters (usable as query strings) are optional.

• game (str)
• all – Get all Jedi Academy servers.
• jka – Get all servers that are not running Movie Battles II.
• mb2 (default) – Get all Movie Battles II servers.
• hostname (str) – Returns any servers where part of sv_hostname_nocolor matches the query string.
• max_age (str) – Returns any servers where first_seen is newer than the query string.
• min_age (str) – Returns any servers where first_seen is older than the query string.
• max_players (int) – Returns any servers with equal or fewer numplayers than the query string.
• min_players (int) – Returns any servers with equal or greater numplayers than the query string.
• other_cvar (str) – Returns any servers where part of extcvars matches the query. Because this checks against stringified JSON, you should always minify the query string (no spaces).
• player (str) – Returns any servers where part of players matches the query.

Cvar Properties

All validated game cvars. Bools will be 0 or 1 and integers and strings are bounded. Use filter other_cvar to search against non-validated ones. Missing cvars (depends on server config) are not returned.

• Universal
• bg_fighteraltcontrol (bool as int)
• bot_minplayers (int)
• capturelimit (int)
• discord (str) – Discord invite code. Set in server config (with your 7 digit code):
• sets discord "AbCd123"
• dmflags (int)
• duel_fraglimit (int)
• fraglimit (int)
• g_duelweapondisable (bool as int)
• g_forcebasedteams (bool as int)
• g_gametype (int)
• g_gravity (int)
• g_jedivmerc (int)
• g_maxforcerank (int)
• g_maxholocroncarry (int)
• g_needpass (bool as int)
• g_privateduel (bool as int)
• g_saberlocking (bool as int)
• g_siegeteam1 (str)
• g_siegeteam2 (str)
• gamename (str)
• mapname (str)
• players (array of objects)
• name (str)
• ping (int)
• score (int)
• sv_allowdownload (bool as int)
• sv_autodemo (bool as int)
• sv_floodprotect (bool as int)
• sv_floodprotectslow (bool as int)
• sv_fps (int)
• sv_hostname (str)
• sv_maxclients (int)
• sv_maxping (int)
• sv_maxrate (int)
• sv_minping (int)
• sv_minrate (int)
• sv_privateclients (int)
• sv_privateclients (int)
• timelimit (int)
• version (str)
• game: jka
• g_allownpc (bool as int)
• g_debugmelee (bool as int)
• g_forcepowerdisable (int)
• g_forceregentime (int)
• g_maxgameclients (int)
• g_nospecmove (bool as int)
• g_saberwalldamagescale (float)
• g_showduelhealths (bool as int)
• g_siegerespawn (int)
• g_siegeteamswitch (bool as int)
• g_stepslidefix (bool as int)
• g_weapondisable (int)
• game: mb2
• g_anticheat (bool as int)
• g_authenticity (int)
• g_competitive (int)
• g_duelfriendlyteam (bool as int)
• g_dueltimelimit (int)
• g_hidehudfromspecs (bool as int)
• g_shuffletimer (int)
• g_spin (bool as int)
• g_teamswap (bool as int)
• tk_kick (int)
• tk_spec (int)
• rtvrtm (str)

Meta Properties

These are non-cvar properties generated by the API or calculated based on the server's cvars. Availability may depend on the selected game. Geolocation information is generated using a GeoLite2 database.

• Universal
• address (str) – IPv4 address of the server.
• architecture (str) – Engine's architecture (e.g. x86, x86_x64).
• extcvars (obj) – Object containing all non-validated cvars.
• country (str) – Country based on server's IP.
• country_code (str) – ISO country code.
• engine (str) – Engine binary, only really checks if JAMP (if not then it is OpenJK).
• engine_date (str) – Engine build date.
• first_seen (str) – When the server was initially added to the list in YYYY-MM-DD format.
• id (str) – MD5 hash generated from server's IP and port.
• numbots (int) – Number of bot clients (ping = 0).
• numplayers (int) – Number of player clients (ping > 0).
• platform (str) – Engine's operating system.
• players (array of objects)
• name_nocolor (str) – Player name stripped of Q3 color markup.
• port (int) – Network port of the server.
• region (str) – The country's continent.
• region_code (str) – ISO continent code.
• sv_hostname_nocolor (str) – Server name stripped of Q3 color markup.
• game: all
• ismb (bool as int) – Whether or not the server is running Movie Battles II.
• (all mb2-only properties)
• game: mb2
• mbmode (str) – Human friendly version of the g_authenticity cvar.
• mbversion (str) – The Movie Battles II version.
• rtvrtm_state (str) – Human friendly version of the rtvrtm cvar.