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 |
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 |
| 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 |
Scores Object
The scores object is a dictionary with the following keys:
| key | value |
|---|---|
| capitalships | |
| dateadded | |
| freighters | |
| id | |
| inventoryscore | |
| militaryscore | |
| ownerid | |
| percent | |
| planets | |
| prioritypoints | |
| starbases | |
| turn |
