Latest revision as of 16:32, 23 September 2024

APIs

The Star Sonata 2 Web API is an interface that allows developers of third party programs or applications to retrieve data directly from the Star Sonata 2 servers in a secure manner.

Current endpoints are public information only and require no authentication. Authenticated requests are planned for the future to get detailed information on teams and individual character details.

Endpoints

The root url for all current endpoints is https://www.starsonata.com/webapi/.

• galaxies: Returns information on galaxies in the current universe.
• galaxies_recent: Returns information on recently changed galaxies (with a much lower cache time than galaxies).
• teams: Returns details on all the current Userteams.
• server_status: Returns information about the current status of servers.

Planned Endpoints

• items - an endpoint to retrieve the stats of "publicly known" items (items that have been on the public market at some point) is currently being developed.
• An endpoint to retrieve market data for items.
• An endpoint to retrieve basic details on past universes such as start/end times and final emperor details.
• An endpoint showing bulletin board data.
• Authenticated endpoints showing privileged information
  • Team data such as team skill data, members and their ranks, team ledger, and more.
  • Account data such as characters on the account.
  • Character data such as skills, owned assets, and more.

(Old) Data end points

Bulletin board

XML for the bulletin board can be accessed from [1]. It's updated once a minute.

Universe age and login message

Can be found in globals.xml from [2]. Note that the UNISTART value is given as an epoch since 1970-01-01 00:00:00 in the local timezone for the server (America/New York, UTC-5 and UTC-4 for DST).

Universe map data

Data for the current structure of the universe is available in JSON format from starsonata.com/ss_api/universe.json, note that currently the data here isn't automatically updated, and may be out of date currently (2016-03-04).

Please also attempt to limit accessing the file, the file for an entire universe is about 1MB, use some form of caching or retention to limit requests to the file (as well as spending up your use).

Format

The entire file is a JSON object of more objects. The keys in the root object are galaxy IDs, these are unique and persist throughout the universe. Note that the data can be in any order, as JSON objects are unordered.

Here is an extract, for Sol:

"2052387433":
{
  "w": ["2052386983","2052386984","2052386986","2052386992","2052386993","2052386999","2052387266","2052387333","2052431813","2052645243"],
  "n":"Sol",
  "a":0,
  "x":0,
  "s":0,
  "l":0,
  "y":0,
  "u":0,
  "p":1,
  "df":0,
  "b":7,
  "t":"Earthforce",
  "o":1
}

n

The is the full name of the galaxy, note that this may not be unique (but should be).

x

The x position of the galaxy on the star map, as a real number, 0.0 is the centre going to the right as it increase towards infinity.

y

The y position of the galaxy on the star map, as a real number, 0.0 is the centre going down as it increases towards infinity.

df

The danger factor of the galaxy, note that this value will be 100 times smaller than what you see in the game

l

The layer id this galaxy is on the map.

• Earthforce: 0
• Wild Space: 3
• Perilous Space: 4
• Subspace: 5
• Kalthi Depths: 6
• Nexus: 10
• Colour Empires: 11
• Serengeti: 12
• Nihilite: 13
• Absolution: 15
• Enigmatic Sector: 16
• Iq' Bana: 17
• Olympus: 18
• Liberty: 19
• Subspace instances: 20
• Arctia: 21
• Vulcan: 22
• Suqq Bana: 23
• Jungle: 24
• Kidd: 35
• Holiday (Lapland, Easter Warren): 36

w

An array of galaxies (by id) that this galaxy has wormholes to, note that this galaxy may not exist in the root object if they've not been discovered by a player yet.

a

Boolean flag (0 or 1) for whether this galaxy is an anchor galaxy. Anchor galaxies have connections to other layers, like Deep Space.

s

Boolean flag (0 or 1) for special galaxies. In game this is signified on the map by the name being coloured in purple.

u

The number of user bases that are in this galaxy.

b

The number of space stations that are in this galaxy.

t

The name of the owning/protecting team, if there is one.

o

Boolean flag (0 or 1) for whether this galaxy is owned, note that this'll still be set regardless of p.

p

Boolean flag (0 or 1) for whether this galaxy is protected.