Planets.Nu API

From VGA Planets Wiki
Revision as of 22:27, 27 November 2012 by HandsomeCam (talk | contribs) (→‎Load Turn Data: fixed a link typo)
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 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 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 representing the system messages (reports) for the current turn
mymessages An array of message objects representing the diplomatic messages sent and received for the player of the current game
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

Non-Public API

In addition to the publicly documented API, there are several calls available from reading the actual game code. The maintainers of Planets.Nu have stated that any API endpoint is safe to use.

Encoding

Any data sent over the non-public API is expected to be encoded to prevent & and = characters from getting mangled by the connection string.

  • & (ampersand) characters are to be replaced with ||| (3 pipe characters)
  • = (equals) characters are to be replaced with ::: (3 colon characters)

Send Message

The Send Message API allows users to send in-game messages to other players in the current game.

The send message command is a GET call to http://api.planets.nu/game/sendmessage with the following values passed on the connection string:

variable description Required Default Value
gameid The of the game in which to send the message YES n/a
playerid The player who is sending the message YES n/a
apikey The api key of the player sending the message YES n/a
to A comma separated list of all recipients of the message YES n/a
body The body of the message to be sent YES n/a

Common Data Objects

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

Beam Object

The beam object returned by Load Turn Info is a dictionary with the following keys:

key value
cost The amount of megacredits required to build the beam weapon
crewkill The number of crew the beam will kill if the shields of the target ship are down
damage The damage that the particular beam will do to the hull or shield of a ship
duranium The amount of duranium required to build the beam weapon
id The beam ID referenced by other objects, such as the Ship Object
mass The mass of the beam weapon when constructed
molybdenum The amount of molybdenum required to build the beam weapon
name The name of the beam weapon
techlevel The tech level required at the starbase to build the beam weapon
tritanium The amount of tritanium required to build the beam weapon

Engine Object

The engine object returned by Load Turn Info is a dictionary with the following keys:

key value
cost The amount of megacredits required to build the engine
duranium The amount of duranium required to build the engine
id The engine ID referenced by other objects, such as the Ship Object
molybdenum The amount of molybdenum required to build the engine
name The name of the engine
techlevel The tech level required at the starbase to build the engine
tritanium The amount of tritanium required to build the engine
warp1
warp2
warp3
warp4
warp5
warp6
warp7
warp8
warp9

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

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

Hull Object

The hull object returned by Load Turn Info is a dictionary with the following keys:

key value
advantage
beams The maximum number of beams that can be added to the hull
cancloak A boolean value indicating if the hull includes a cloaking device
cargo The amount of cargo space available in the constructed hull
cost The amount of megacredits required to build the hull
crew The maximum crew capacity in the constructed hull
description
dur
duranium The amount of duranium required to build the hull
engines The amount of engines required by the hull when building a ship
fighterbays The number of fighter bays in the constructed hull
fueltank The maximum fuel capacity in the constructed hull
id The hull ID referenced by other objects, such as the Ship Object
isbase
launchers The maximum number of torpedo launchers that can be added to the hull
mass The mass of the constructed hull
mc
mol
molybdenum The amount of molybdenum required to build the hull
name The name of the hull
parentid
special The text description of the special abilities available to the constructed hull
techlevel The tech level required at the starbase to build the hull
tri
tritanium The amount of tritanium required to build the hull

Ion Storm Object

The ion storm object returned by Load Turn Info is a dictionary with the following keys:

key value
heading
id The ID of the Ion Storm
isgrowing A boolean value indicating if the ion storm is growing (strengthening)
radius The radius of the ion storm in light years
voltage The current voltage (strength) of the ion storm
warp The speed at which the ion storm is travelling
x The x coordinate of the ion storm's current position
y The y coordinate of the ion storm's current position

Message Object

The message object returned by Load Turn Info is a dictionary with the following keys:

key value
body The body of the message. May contain HTML line breaks
headline The title of the message
id The ID of the message
messagetype The type of message.
ownerid The recipient of the message
target The ID of the subject of the message based on the context (Ship, Planet, etc) or the sender in the case of a diplomatic message
turn The game turn in which the message was received
x The x coordinate of the event described, may only be useful in certain contexts
y The y coordinate of the event described, may only be useful in certain contexts

Message Types

The message types indicated by the messagetype field in the message object are as follows:

  • 0: Outbound
  • 1 : System
  • 2 : Terraforming
  • 3 : Minelaying
  • 4 : Mine Sweep
  • 5 : Colony
  • 6 : Combat
  • 7 : Fleet
  • 8 : Ship
  • 9 : Enemy Distress Call
  • 10 : Explosion
  • 11 : Starbase
  • 12 : Web Mines
  • 13 : Meteors
  • 14  : Sensor Sweep
  • 15 : Bio Scan
  • 16 : DistressCall
  • 17 : Player
  • 18 : Diplomacy
  • 19 : MineScan
  • 20 : Dark Sense
  • 21 : Hiss

Minefield Object

The minefield object returned by Load Turn Info is a dictionary with the following keys:

key value
friendlycode The friendly code to safely pass through the minefield, if known
id The ID of the minefield
infoturn The turn the minefield information was last updated
isweb A boolean value indicating if the minefield is a web mine
ownerid The player ID that owns the minefield
radius The last known radius of the minefield
units
x The x coordinate of the center of the minefield
y The y coordinate of the center of the minefield

Nebula Object

The nebula object returned by Load Turn Info is a dictionary with the following keys:

key value
n/a This is a stub, please fill this out

Note Object

The note object returned by Load Turn Info is a dictionary with the following keys:

key value
body The text body of the note
color The hexadecimal color of the noted entity on the map
id The ID of the note
ownerid The player ID that created the note
targetid The ID of the entity the note belongs to
targettype The type of entity the note belongs to

If anyone has a clear list of what targettype IDs are possible, please add it here

Planet Object

The planet object returned by Load Turn Info is a dictionary with the following keys:

key value
buildingstarbase A boolean value indicating if the planet is currently building a starbase
builtdefense The number of defense posts being built this turn
builtfactories The number of factories being built this turn
builtmines The number of mines being build this turn
checkduranium
checkmegacredits
checkmolybdenum
checkneutronium
checksupplies
checktritanium
clans The number of clans populating the planet
colchange
colhappychange The increase or decrease of happiness points on the planet this turn
colonisthappypoints The current happiness level of the colonists on the planet
colonisttaxrate The current tax rate (from 1 to 100)
debrisdisk
defense The total number of defense posts on the planet
densityduranium
densitymolybdenum
densityneutronium
densitytritanium
duranium The amount of duranium sitting on the surface of the planet
factories The total number of factories on the planet
flag
friendlycode The planet's friendly code
groundduranium
groundmolybdenum
groundneutronium
groundtritanium
id The ID of the planet
img A url to the image of the planet
infoturn The turn in which the information of this planet was last updated
megacredits The megacredits available on the planet
mines The total number of mines on the planet
molybdenum The amount of molybdenum sitting on the surface of the planet
name The name of the planet
nativechange
nativeclans The number of clans of natives populating the planet
nativegovernment The ID representing the government type of the native life on the planet
nativegovernmentname The text name of the government type of the native life on the planet
nativehappychange The increase or decrease in happy points for the native life on the planet this turn
nativehappypoints The overall happiness points for the native life on the planet this turn
nativeracename The text name of the native race populating the planet
nativetaxrate The current tax rate (from 1 to 100) for the native race on the planet
nativetaxvalue
nativetype The ID representing the race of native life on the planet
neutronium The amount of neutronium sitting on the surface of the planet
ownerid The player ID currently in control of the planet
readystatus
supplies The amount of supplies sitting on the surface of the planet
suppliessold The number of supplies converted to megacredits on the planet this turn
targetdefense The target value for defense posts in the auto-build queue
targetfactories The target value for factories in the auto-build queue
targetmines The target value for mines in the auto-build queue
temp The temperature on the planet (from 0-100) or -1 if unknown
totalduranium
totalmolybdenum
totalneutronium
totaltritanium
tritanium The amount of tritanium sitting on the surface of the planet
x The x coordinate of the planet in space
y The y coordinate of the planet in space

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


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


Race Object

The race object returned by Load Turn Info is a dictionary with the following keys:

key value
adjective The adjective used to describe the race's ships and planets
advantages
baseadvantages
basehulls The base set of hulls (by Hull ID) available to the race
hulls
id The race ID
name The full name of the race
shortname The shorter version of the race name

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


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


Ship Object

The ship object returned by Load Turn Info is a dictionary with the following keys:

key value
ammo The number of Torpedos or Fighters present on the ship
bays The number of fighter bays on the ship
beamid The type of beam weapons installed on the ship. This corresponds to an entry in the beam object array
beams The number of installed beam weapons on the ship
clans The number of clans in the ship's cargo hold
crew The number of active crew members aboard the ship
damage The amount of damage sustained on the ship
duranium The amount of duranium in the ship's cargo hold
enemy The primary enemy assigned to the ship
engineid The type of engine installed on the ship
experience The experience of the crew on the ship
friendlycode The friendly code assigned to the ship
heading
history An array of (x,y) coordinates (as a dictionary) indicating the previous positions of the ship
hullid The hull used in the ship
id The ID of the ship
infoturn The last turn the information about the ship was updated
iscloaked A boolean value indicating if the ship is cloaked or not
mass The total mass of the ship including all cargo
megacredits The amount of megacredits on board the ship
mission The current mission being performed on the ship
mission1target
mission2target
molybdenum The amount of molybdenum in the ship's cargo hold
name The name of the ship
neutronium The amount of neutronium (fuel) in the ship's fuel tank
ownerid The player ID of the owner of the ship
readystatus
supplies The amount of supplies in the ship's cargo hold
targetx The x coordinate of the flight path target for the ship
targety The y coordinate of the flight path target for the ship
torpedoid The ID of the torpedo launchers installed in the ship
torps The number of torpedo launchers installed in the ship
transferammo
transferclans
transferduranium
transfermegacredits
transfermolybdenum
transferneutronium
transfersupplies
transfertargetid
transfertargettype
transfertritanium
tritanium The amount of tritanium in the ship's cargo hold
turn
turnkilled
warp The current warp speed of the ship
waypoints
x The x coordinate of the ship's current position in space
y The y coordinate of the ship's current position in space

Star Object

The star object returned by Load Turn Info is a dictionary with the following keys:

key value
n/a This is a stub, please fill this out

Starbase Object

The starbase object returned by Load Turn Info is a dictionary with the following keys:

key value
beamtechlevel The tech level for beam weapons on the starbase
beamtechup The level raised of the beam tech in the current turn
buildbeamcount
buildbeamid
buildengineid
buildhullid
buildtorpcount
buildtorpedoid
builtdefense The number of starbase defense points added this turn
builtfighters The number of fighters built this turn
damage The current damage level of the starbase
defense The total defense points on the starbase
enginetechlevel The tech level for engines on the starbase
enginetechup The level raised of the engine tech in the current turn
fighters The number of fighters currently on the starbase
hulltechlevel The tech level for hulls on the starbase
hulltechup The level raised of the hull tech in the current turn
id The ID of the starbase
infoturn The last turn the information on this starbase was updated
isbuilding
mission
planetid The planet this starbase belongs to
raceid
readystatus
shipmission
starbasetype
targetshipid The ship targeted by the current mission (if applicable)
torptechlevel The tech level for torpedos on the starbase
torptechup The level raised of the torpedo tech in the current turn


Stock Item Object

The stock item object returned by Load Turn Info is a dictionary with the following keys:

key value
amount The quantity of the stock item on the starbase
builtamount
id The ID of the stock item
starbaseid The ID of the starbase that the stock item belongs to
stockid The ID of the type of item in stock (looked up in the table corresponding to stocktype)
stocktype The type of item in stock


Torpedo Object

The torpedo object returned by Load Turn Info is a dictionary with the following keys:

key value
crewkill The number of crew the torpedo will kill if the shields of the target ship are down
damage The damage that the particular torpedo will do to the hull or shield of a ship
duranium The amount of duranium required to build the torpedo
id The torpedo ID referenced by other objects, such as the Ship Object
launchercost The amount of megacredits required to build the torpedo launcher
mass The mass of the torpedo when constructed
molybdenum The amount of molybdenum required to build the torpedo
name The name of the torpedo
techlevel The tech level required at the starbase to build the torpedo laucher and ammo
torpedocost The amount of megacredits required to build the torpedo ammo
tritanium The amount of tritanium required to build the torpedo


VCR Object

The vcr (visual combat recording) object returned by Load Turn Info is a dictionary with the following keys:

key value
n/a This is a stub, please fill this out

References

Official API Documentation