Planets.Nu API

From VGA Planets Wiki
Revision as of 23:44, 20 November 2012 by HandsomeCam (talk | contribs) (→‎Common Data Objects: Added the Player Object)
Jump to navigationJump to search

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 user's general settings as a dictionary

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 can return 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

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

References

Official API Documentation