Game Jolt API for Python - Reference

This module is a single threaded Python interface for the Game Jolt API running through HTTP requests. It contains all Game Jolt API endpoints and aims to simplify its use where it’s possible. The source code of this module can be found here.

Installing

This module is available on the Python Package Index. To install it on your Python distribution, simply run on the console:

pip install gamejoltapi

Or if you want to download it manually, just download the latest gamejoltapi.py from the source code repository.

Basic Usage

To instance the main class just provide the required data and you’re ready to call any of the API methods.

import gamejoltapi

GAME_ID = "602381"
PRIVATE_KEY = "de7ac4c81d064cdc1121b495e2165b53"
USERNAME = "bgempire"
TOKEN = "bgempire"

api = gamejoltapi.GameJoltAPI(
   GAME_ID,
   PRIVATE_KEY,
   username=USERNAME,
   userToken=TOKEN,
   responseFormat="json",
   submitRequests=True
)

Classes

class gamejoltapi.GameJoltAPI(gameId, privateKey, username=None, userToken=None, responseFormat='json', submitRequests=True)

The main Game Jolt API class. Aside from the required arguments, most of the optional arguments are provided to avoid asking for them in every single method.

Parameters

  • gameId (int) – The game ID. Required in all requests.

  • privateKey (str) – The API private key. Required in all requests.

  • username (str) – Username used in some requests. Optional.

  • userToken (str) – User access token used in some requests. Optional.

  • responseFormat (str) – The response format of the requests. Can be "json", "xml", "keypair" or "dump". Optional, defaults to "json".

  • submitRequests (bool) – If submit the requests or just get the generated URLs from the method calls. Useful to generate URLs for batch requests. Optional, defaults to True.

gameId: int

The game ID. Required in all requests.

privateKey: str

The API private key. Required in all requests.

username: str

Username used in some requests. Optional.

userToken: str

User access token used in some requests. Optional.

responseFormat: str

The response format of the requests. Can be "json", "xml", "keypair" or "dump". Optional, defaults to "json".

submitRequests: bool

If submit the requests or just get the generated URLs from the method calls. Useful to generate URLs for batch requests. Optional, defaults to True.

batch(requests=[], parallel=None, breakOnError=None)

A batch request is a collection of sub-requests that enables developers to send multiple API calls with one HTTP request.

Parameters

  • requests (list of str) – An list of sub-request URLs. Each request will be executed and the responses of each one will be returned in the payload.

  • parallel (bool) – By default, each sub-request is processed on the servers sequentially. If this is set to True, then all sub-requests are processed at the same time, without waiting for the previous sub-request to finish before the next one is started.

  • breakOnError (bool) – If this is set to True, one sub-request failure will cause the entire batch to stop processing subsequent sub-requests and return a value of "false" for success.

Note

  • The maximum amount of sub requests in one batch request is 50.

  • Dump format is not supported in batch calls.

  • The parallel and breakOnError parameters cannot be used in the same request.

# Disable request submitting to get URLs from methods
api.submitRequests = False

# Generate list of request URLs
requests = [
    api.usersFetch(),
    api.sessionsCheck(),
    api.scoresTables(),
    api.trophiesFetch(),
    api.dataStoreGetKeys("*", globalData=True),
    api.friends(),
    api.time()
]

# Enable request submitting again
api.submitRequests = True

# Submit batch request and get all results
result = api.batch(requests=requests)
dataStoreFetch(key, globalData=False)

Returns data from the data store.

Parameters

  • key (str) – The key of the data item you’d like to fetch.

  • globalData (bool) – If set to True, ignores username and userToken set in constructor and processes global data instead of user data.

# Get "some_global_value" from global data store
result = api.dataStoreFetch("some_global_value", globalData=True)
dataStoreGetKeys(pattern=None, globalData=False)

Returns either all the keys in the game’s global data store, or all the keys in a user’s data store.

Parameters

  • pattern (str) – The pattern to apply to the key names in the data store.

  • globalData (bool) – If set to True, ignores username and userToken set in constructor and processes global data instead of user data.

Note

  • If you apply a pattern to the request, only keys with applicable key names will be returned. The placeholder character for patterns is *.

  • This request will return a list of the key values. The key return value can appear more than once.

# Get keys from global data store starting with "some_global"
result = api.dataStoreGetKeys("some_global_*", globalData=True)
dataStoreRemove(key, globalData=False)

Removes data from the data store.

Parameters

  • key (str) – The key of the data item you’d like to remove.

  • globalData (bool) – If set to True, ignores username and userToken set in constructor and processes global data instead of user data.

# Remove "some_global_value" from global data store
result = api.dataStoreRemove("some_global_value", globalData=True)
dataStoreSet(key, data, globalData=False)

Sets data in the data store.

Parameters

  • key (str) – The key of the data item you’d like to set.

  • data (str) – The data you’d like to set.

  • globalData (bool) – If set to True, ignores username and userToken set in constructor and processes global data instead of user data.

Note

You can create new data store items by passing in a key that doesn’t yet exist in the data store.

# Store on the key "some_global_value" the data "500" in the global data store
result = api.dataStoreSet("some_global_value", "500", globalData=True)
dataStoreUpdate(key, operation, value, globalData=False)

Updates data in the data store.

Parameters

  • key (str) – The key of the data item you’d like to update.

  • operation (str) – The operation you’d like to perform.

  • value (str) – The value you’d like to apply to the data store item. (See values below.)

  • globalData (bool) – If set to True, ignores username and userToken set in constructor and processes global data instead of user data.

Note

Valid Values for operation:

  • "add": Adds the value to the current data store item.

  • "subtract": Substracts the value from the current data store item.

  • "multiply": Multiplies the value by the current data store item.

  • "divide": Divides the current data store item by the value.

  • "append": Appends the value to the current data store item.

  • "prepend": Prepends the value to the current data store item.

Note

You can only perform mathematic operations on numerical data.

# Adds "100" to "some_global_value" in the global data store
result = api.dataStoreUpdate("some_global_value", "add", "100", globalData=True)
friends()

Returns the list of a user’s friends.

scoresAdd(score, sort, tableId=None, guest=None, extraData=None)

Adds a score for a user or guest.

Parameters

  • score (str) – This is a string value associated with the score. Example: "500 Points"

  • sort (int) – This is a numerical sorting value associated with the score. All sorting will be based on this number. Example: 500

  • tableId – The ID of the score table to submit to.

  • guest (str) – The guest’s name. Overrides the username set in the constructor.

  • extraData – If there’s any extra data you would like to store as a string, you can use this variable.

Note

  • You can either store a score for a user or a guest. If you’re storing for a user, you must pass in the username and userToken parameters in the class constructor and leave guest as None. If you’re storing for a guest, you must pass in the guest parameter.

  • The extraData value is only retrievable through the API and your game’s dashboard. It’s never displayed publicly to users on the site. If there is other data associated with the score such as time played, coins collected, etc., you should definitely include it. It will be helpful in cases where you believe a gamer has illegitimately achieved a high score.

  • If tableId is left blank, the score will be submitted to the primary high score table.

scoresFetch(limit=None, tableId=None, guest=None, betterThan=None, worseThan=None, thisUser=False)

Returns a list of scores either for a user or globally for a game.

Parameters

  • limit (int) – The number of scores you’d like to return.

  • tableId (int) – The ID of the score table.

  • guest (str) – A guest’s name.

  • betterThan (int) – Fetch only scores better than this score sort value.

  • worseThan (int) – Fetch only scores worse than this score sort value.

  • thisUser (bool) – If True, fetch only scores of current user. Else, fetch scores of all users.

Note

  • The default value for limit is 10 scores. The maximum amount of scores you can retrieve is 100.

  • If tableId is left blank, the scores from the primary score table will be returned.

  • Only pass in thisUser=True if you would like to retrieve scores for just the user set in the class constructor. Leave thisUser=False and guest=None to retrieve all scores.

  • guest allows you to fetch scores by a specific guest name. Only pass either the thisUser=True or the guest (or none), never both.

  • Scores are returned in the order of the score table’s sorting direction. e.g. for descending tables the bigger scores are returned first.

scoresGetRank(sort, tableId=None)

Returns the rank of a particular score on a score table.

Parameters

  • sort (int) – This is a numerical sorting value that is represented by a rank on the score table.

  • tableId (int) – The ID of the score table from which you want to get the rank.

Note

  • If tableId is left blank, the ranks from the primary high score table will be returned.

  • If the score is not represented by any rank on the score table, the request will return the rank that is closest to the requested score.

scoresTables()

Returns a list of high score tables for a game.

sessionsCheck()

Checks to see if there is an open session for the user. Can be used to see if a particular user account is active in the game.

Note

This endpoint returns "false" for the "success" field when no open session exists. That behaviour is different from other endpoints which use this field to indicate an error state.

sessionsClose()

Closes the active session.

sessionsOpen()

Opens a game session for a particular user and allows you to tell Game Jolt that a user is playing your game. You must ping the session to keep it active and you must close it when you’re done with it.

Note

You can only have one open session for a user at a time. If you try to open a new session while one is running, the system will close out the current one before opening the new one.

sessionsPing(status=None)

Pings an open session to tell the system that it’s still active. If the session hasn’t been pinged within 120 seconds, the system will close the session and you will have to open another one. It’s recommended that you ping about every 30 seconds or so to keep the system from clearing out your session.

You can also let the system know whether the player is in an active or idle state within your game.

Parameters

status (str) – Sets the status of the session.

Note

Valid Values for status:

  • "active": Sets the session to the "active" state.

  • "idle": Sets the session to the "idle" state.

time()

Returns the time of the Game Jolt server.

trophiesAddAchieved(trophyId)

Sets a trophy as achieved for a particular user.

Parameters

trophyId (int) – The ID of the trophy to add for the user.

trophiesFetch(achieved=None, trophyId=None)

Returns one trophy or multiple trophies, depending on the parameters passed in.

Parameters

  • achieved (bool) – Pass in True to return only the achieved trophies for a user. Pass in False to return only trophies the user hasn’t achieved. Leave blank to retrieve all trophies.

  • trophyId (str, int or list) – If you would like to return just one trophy, you may pass the trophy ID with this parameter. If you do, only that trophy will be returned in the response. You may also pass multiple trophy IDs here if you want to return a subset of all the trophies. You do this as a list or a string with comma-separated values in the same way you would for retrieving multiple users (example: "13,89,35"). Passing a trophyId will ignore the achieved parameter if it is passed.

trophiesRemoveAchieved(trophyId)

Remove a previously achieved trophy for a particular user.

Parameters

trophyId (int) – The ID of the trophy to remove from the user.

usersAuth()

Authenticates the user’s information. This should be done before you make any calls for the user, to make sure the user’s credentials (username and token) are valid.

usersFetch(username=None, userId=None)

Returns a user’s data.

Parameters

  • username (str) – The username of the user whose data you’d like to fetch.

  • userId (str, int or list) – The ID of the user whose data you’d like to fetch.

Note

  • Only one parameter, username or userId, is required.

  • You can pass in multiple user ids by providing a list or separating them with commas in a string (example: "13,89,35").

Exceptions

class gamejoltapi.GameJoltDataRequired(key)

Exception raised when not all required data is provided in the request call.

Parameters

key (str) – The data field name which is required.

class gamejoltapi.GameJoltDataCollision(keys)

Exception raised when a value cannot be provided along with another.

Parameters

keys (list) – The data field names which collided.