Load Turn Data

The Load Turn Data API returns all the data for a single complete turn given a game id and player id. 

For publicly viewable turns from completed games you can do a GET request to:

http://api.planets.nu/game/loadturn?gameid=815&playerid=3

(Click the above link to see a complete turn package in JSON format)

You can also request historic data from the time machine by specifying the turn:

http://api.planets.nu/game/loadturn?gameid=815&playerid=3&turn=80

For running games you must be authorized to get the data and include an apikey instead of a playerid:

http://api.planets.nu/game/loadturn?gameid=20000&apikey=API KEY FROM LOGIN

This will ensure you have been permitted access to the turn before requesting it. The turn package contains all data required to display the current map as the player sees it and all their ships/planets/starbases/relationships/notes and messages.  

Use the forsave=true option if you want to modify the data and save it back using the Save API:

http://api.planets.nu/game/loadturn?gameid=20000&apikey=API KEY FROM LOGIN&forsave=true

The forsave option will prevent saving in any other client window which is open to prevent saving overlaps.

Important note: The response is GZIP compressed and must be decompressed after downloading. (Browsers do this automatically but most code libraries do not)


The outline of the format of the turn data is as follows:

  • settings: list of host settings for this game
  • game: the game information record for this game
  • player: the player record for the loaded player
  • players: an array of the player records for all players
  • scores: an array of score records for each player
  • maps: an array with a link to an image of the current starmap for this player
  • planets: an array of all the planets that this player sees and the data they see
  • ships: an array of all the ships that this player sees and the data they see
  • nebulas: an array of all the nebulas in the system (note: each nebula is made up of a set of overlapping circles)
  • stars: an array of all the star clusters in this system
  • starbases: an array of all the starbases this player knows about or owns
  • stock: an array of the ship parts and torpedos currently in stock at each starbase
  • minefields: an array of all the minefields this player knows about
  • relations: an array of records indicating the relationship this player has with each other player
  • messages: an array of all the system messages this player has received this turn
  • mymessages: an array of all the player to player messages and diplomatic messages this player has sent or received for all turns
  • notes: an array of all the notes or colors this player has attached to ships or planets
  • races: an array of the race information for all the races
  • hulls: an array of all the ship hulls in use in this game
  • racehulls: an array of ids of the hulls this player can build
  • beams: an array of the beam weapons in use in this game
  • engines: an array of the engines in use in this game
  • torpedos: an array of the torpedos in use in this game
  • accountsettings: custom settings for this players account (colors etc)
  • savekey: a key value which must be submitted to save data (prevents overlapping saves)
  • ispremium: true or false value representing whether this player is a premium member or not