Planets.Nu API

On December 21, 2011, Planets.Nu opened up an API for developers.

Public API

The public API calls consist of:

• Login - Use this to acquire the apikey of a given player.
• List Games - List the games on the Planets Nu platform in various ways
• Load Game Info - Load the publicly available data about a single game
• Load Turn Data - Load a single players complete turn package

Errors

API calls return a JSON dictionary. In the event of an API call failure, the following dictionary will be returned:

{"success":false,"error":"This is the error message."}

on occasion, instead of a JSON dictionary the following text is returned:

Error: Error Description Here

Login

The login API returns an API key which can be used along with a username for subsequent API calls.

The login command is an HTTP GET to http://api.planets.nu/login with the following values passed on the connection string:

variable	description	Required	Default Value
username	account username	YES	n/a
password	account password	YES	n/a

Example:

http://api.planets.nu/login?username=user12345&password=straightouttagalibor

The response is a JSON dictionary with the following keys:

key	value
success	Indicates if the call was successful (true or false)
apikey	The API key used in other requests. An API key is formatted as: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where any x is a hexadecimal value.
settings	The current player's settings object

The API key is used for subsequent API calls for the given account. This is the API Key of the account and will only change if the user changes their account password.

List Games

The list games API returns detailed information about all games on the Planets Nu website or for an individual player. This API is a public API and does not require authentication.

The list games command is a GET call to http://api.planets.nu/games/list

The following variables are all optional:

variable	description	Required	Default Value
status	Current status of games to return, with multiple values joined by commas. Possible values are: 1 : Joining 2 : Running 3 : Finished 4 : Hold	NO	1,2
type	The type of games to return, with multiple values joined by commas. Possible values are: 1 : Training 2 : Standard 3 : Team 4 : Melee 5 : Blitz	NO	2,3,4
scope	Current scope of games to return, with multiple values joined by commas. Possible values are: 0 : Public 1 : Custom (private games)	NO	0
ids	IDs of games to return, comma separated	NO	n/a
username	Username of the account to list games. Will list all games for this user regardless of other settings	NO	n/a
limit	The maximum number of records to return. A value of 0 (zero) will return all records.	NO	0

Each game record will be returned in a JSON array of game objects:

[{game 1},{game 2},{game 3}]

Load Game Info

The Load Game Info API returns all the publicly available information about a game including its historical game records.

The load game info command is a GET call to http://api.planets.nu/game/loadinfo with the following values passed on the connection string:

variable	description	Required	Default Value
gameid	The of the game being loaded	YES	n/a

On success, the following JSON dictionary is returned:

key	value
game	A game object dictionary
players	An array of player object dictionaries
relations	An array of relation object dictionaries
schedule	A text description of the host schedule
settings	A game settings object dictionary
timetohost	A text description of the time until the next scheduled host
wincondition	A text description of the condition required to win the game
yearfrom	The Planets.NU year that the game began
yearto	The Planets.NU year the game ended

Load Turn Data

The load turn API returns all the data for a single complete turn given a game id and player id. This API requires the api key from [[#Login|Login] as authentication when loading a turn for a game in progress.

The load turn command is a GET call to http://api.planets.nu/game/loadturn

The following variables may be passed as arguments in the connection string:

variable	description	Required	Default Value
apikey	The api key from the login API call. Only required for turns in active games	NO	n/a
forsave	Indicates if the client intends to make a call to the save data APIs	NO	false
gameid	The game ID for which to request the turn	YES	n/a
playerid	The player to request a turn for. In an active game this value must match the player for the supplied api key, otherwise an error will be returned	NO	n/a
turn	The turn to request	NO	The latest turn

The response is a JSON dictionary with the following keys:

key	value
success	Indicates if the call was successful (true or false)
accountsettings	A player settings object for the player whose turn was fetched
ispremium	Indicates if the player is/was a registered subscriber when the turn was generated
rst	A result object which contains the bulk of the turn information
savekey	A unique, dynamically generated key for saving data back to the API. If forsave was false, this value is empty

Turn Result Object

The turn result object returned by Load Turn is a dictionary with the following keys:

key	value
settings	A game settings object for the current game
game	A game object for the current game
player	A player object for the player the turn data belongs to
players	An array of player objects for all players in the current turn
scores	An array of score objects for all players in the current turn
maps	A url to a pre-rendered image of the game map for the given player for the current turn
planets	An array of planet objects for the game
ships	An array of ship objects representing the ships controlled by the given player for the current turn
ionstorms	An array of ion storm objects for the storms currently active in the cluster
nebulas	An array of nebula objects
stars	An array of star objects
starbases	An array of starbase objects for the starbases under the control of the given player
stock	An array of stock item objects of the loose parts the player has at their starbases
minefields	An array of minefield objects for all minefields known to the player
relations	An array of relation objects for all diplomatic relations as of the current turn
messages	An array of message objects
mymessages	An array of message objects
notes	An array of note objects for notes attached to planets, starbases and ships
vcrs	An array of visual combat recording objects for any combat known to the player for the current turn
races	An array of race objects representing all races participating in the current game
hulls	An array of hull objects for the attributes of every hull possible for the current game
racehulls	An array of the hull IDs available to the current player's race
beams	An array of beam objects for the attributes of every beam weapon possible for the current game
engines	An array of engine objects for the attributes of every engine possible for the current game
torpedos	An array of torpedo objects for the attributes of every torpedo possible for the current game

Common Data Objects

The following objects are used or returned by the API calls:

Game Object

The game object returned by List Games or Load Game Info is a dictionary with the following keys:

key	value
allturnsin	Indicates if all turns have been submitted
createdby
datecreated	The date the game was created
dateended	The date the game ended
deletedate	The date the game was deleted
description	The text description of the game
difficulty
faststart
gametype
hostdays	The days of the week the host will run in the format SMTWTFS. An underscore will replace days the host will not run. eg. _M___F_ indicates the host will run on mondays and fridays
hosttime	The scheduled time of day for the host to run on scheduled host days
id	The ID of the game
ishosting
isprivate
lastbackuppath
lastloadeddate
lastnotified
maptype
masterplanetid
maxlevelid	The maximum level for captains to participate in the game
name	The name of the game / system
nexthost	The datetime of the next scheduled host run
quadrant
requiredlevelid	The required level for captains to participate in the game
scenarioid
shortdescription
slots	The number of player slots available in the game
slowhostdays
status
turn	The current game turn
turnsperweek	The number of scheduled turns per week
turnstatus	A set of characters indicating which players have submitted their turns. An underscore indicates the turn is not yet viewed.
tutorialid
wincondition
yearstarted

Player Object

The player object returned by Load Game Info is a dictionary with the following keys:

key	value
activeadvantages
activehulls	The hulls (by ID) allowed for use by the player
email
finishrank
id	The ID of the player for the current game
isregistered	Indicates if the player is registered (paid subscription)
levelhullid
levelid
planets	The number of planets the player controls in the current game
prioritypoints	The number of priority points the player has at their disposal
raceid	The race ID of the player in the current game
savekey
score	The score object for the player in the current game
ships	The number of ships (war ships and freighters) the player currently controls
starbases	The number of starbases the player controls in the current game
status
statusturn
teamid
turnjoined	The turn at which the player joined the current game
turnready	Indicates if the players turn is ready (finished)
turnsmissed
turnstatus
username	The Planets.NU username of the player

Relation Object

The relation object returned by Load Game Info is a dictionary with the following keys:

key	value
color
conflictlevel
id
playerid
playertoid
relationfrom
relationto

Game Settings Object

The game settings object returned by Load Game Info is a dictionary with the following keys:

key	value
allowchunneltowdropbug
averagedensitypercent
buildqueueplanetid
campaignmode
cloakfail
closeplanets
deadradius
debrisdiskpercent
developmentfactor
discussionid
duraniumlevel
fixedstartpositions
hideraceselection
hostcompleted
hoststart
hwdistribution
id
killrace
mapheight	The height of the map in pixels / lightyears. The upper limit is 4000
mapshape
mapwidth	The width of the map in pixels / lightyears. The upper limit is 4000
maxallies	The maximum number of allies a player can have in the current game
maxioncloudsperstorm
maxions
militaryscorepercent
molybdenumlevel
name	The name of the current game
nativeprobability
ncircles
ndebrisdiscs
nebulas
neutroniumlevel
nexthost
nuionstorms
numplanets	The number of planets in the game
planetscanrange
playerselectrace
roundmap
runningstart
shipscanrange
showallexplosions
stars
structuredecayrate
teamsize
tritaniumlevel
turn	The current game turn
uniqueraces
verycloseplanets
victorycountdown

Player Settings Object

The player settings object returned by Login and Load Turn is a dictionary with the following keys:

key	value
allymines	A hex RGB color code for allied minefields
allyplanetfrom
allyplanetto
allyshipfrom
allyshipto
assistanton
battletaskid
battletutorialid
enemymines	A hex RGB color code for enemy minefields
enemyplanetfrom
enemyplanetto
enemyshipfrom
enemyshipto
id
infoplanetfrom
infoplanetto
ionstorms	A hex RGB color code for ion storms
musicon
mymines	A hex RGB color code for the current player's minefields
myplanetfrom
myplanetto
myshipfrom
myshipto
soundon
unknownplanetfrom
unknownplanetto
webmines	A hex RGB color code for webmines

Score Object

The score object is a dictionary with the following keys:

key	value
capitalships
dateadded
freighters
id
inventoryscore
militaryscore
ownerid
percent
planets
prioritypoints
starbases
turn

References

Official API Documentation