Skip to content

Latest commit

 

History

History
407 lines (302 loc) · 9.06 KB

Map.pod

File metadata and controls

407 lines (302 loc) · 9.06 KB

Map Data

An export of the public map data (ie the Stars), is available to download in an easy to use CSV format. The URL is

http://gameservername.lacunaexpanse.com.s3.amazonaws.com/stars.csv

So if the server name is "us-east-1", then the the URL would be

http://us-east-1.lacunaexpanse.com.s3.amazonaws.com/stars.csv

Map Methods

These methods are accessible via the /map URL.

get_star_map

This takes a hashref of named arguments.

{
  "session_id" : "session-id-here",
  "left" : -900,
  "top" : 50,
  "right" : -850,
  "bottom" : 30
}

This is the preferred call to obtain star data. It is a 'lite' version of get_stars which just returns enough data to draw the starmap.

Where left, top, right, bottom represent the sides of the bounding rectangle.

The maximum area that can be returned is 1001 units (e.g 50 x 20 or 1001 x 1)

Returns a chunk of the map as an array of hashes.

{
  "stars" : [
    {
      "name"       : "Sol",
      "color"      : "yellow",
      "x"          : -41,
      "y"          : 27,
      "id"         : 99,
      "station" : {
        "id"       : 2001,
        "x"        : 143,
        "y"        : -27,
        "name"     : "The Death Star",
        "alliance" : {
          "name"     : "The Borg Collective",
          "id"       : 23,
          "image"    : 'my_logo_v001',
        }
      }
      "bodies" : [
        {
          "name"   : "Mercury",
          "id"     : 345,
          "orbit"  : 1,
          "x"      : -40,
          "y"      : 29,
          "type"   : "habitable planet",
          "image"  : "p13",
          "size"   : 58,
          "empire" {
            "id"     : 945,
            "name"   : "Earthlings",
            "alignment"  : "ally",
            "is_isolationist" : 1
          }
        },
        {
          "name"   : "Vesta",
          "id"     : 346,
          "orbit"  : 2,
          "x"      : -39,
          "y"      : 28,
          "type"   : "asteroid",
          "image"  : "p33",
          "size"   : 3,
          "body_has_fissure"  : 1,
        },
        ...
      ]
    },
    {
      ...
    }
    ...
  ]
}

Note. This data is a cut-down version of that returned by get_stars, in particular it does not return most of the data for planets you occupy (ore, water etc.), does not return the 'station' data if the planet in under the influence of a space-station and does not return the water or ore for the planet. You can make separate calls to the /body get_status for that information.

The station section is only returned if the star is under the influence of a Space station.

The empire section is only returned if the body is occupied by an empire.

get_stars ( session_id, x1, y1, x2, y2 )

Retrieves a chunk of the map and returns it as an array of hashes. Note: Coordinates without a star will not be returned in the results.

{ 
   "stars" : [
       {
           "name"          : "Sol",
           "color"         : "yellow",
           "x"             : -41,
           "y"             : 27,
           "zone"          : "0|0",
           "id"            : "99",
           "station" : { # only shows up if this star is under the influence of a space station
               "id" : "id-goes-here",
               "x" : 143,
               "y" : -27,
               "name" : "The Death Star"
           },
           "bodies"        : [     # only added if a probe is present
               {
                   same data as get_status() on /body
               },
               ...
           ]
       },
       {
           "name"          : "X143S",
           "color"         : "green",
           "x"             : -42,
           "y"             : 27
           "zone"          : "0|0",
           "id"            : "99",
           "station" : { ... }
       }
    ],
   "status" : { ... }
}

The data you retrieve will allow you to draw a standard cartesian plane like the following.

y

|
|
     (-3,3)   |  (3,3)
|
 -x ----------+---------- x
|
     (-3,-3)  |  (3,-3)
|
|

             -y

The requested area can be no larger than 900 spaces (30x30). Throws 1003 when the area is too large.

session_id

A session id.

x1

The top left x coord.

y1

The top left y coord.

x2

The bottom right x coord.

y2

The bottom right y coord.

check_star_for_incoming_probe ( session_id, star_id )

If the star has a status of "unprobed", call this method to find out if there is an incoming probe from this empire.

{
   "status" : { ... },
   "incoming_probe" : "01 31 2010 13:09:05 +0600" # date of arrival will be present if there is an incoming probe
}

session_id

A session id.

star_id

The unique id for a star.

get_star (session_id, star_id)

Retrieves info on a single star.

{ 
   "star" : {
       "name"          : "Sol",
       "color"         : "yellow",
       "x"             : -41,
       "y"             : 27,
       "zone"          : "0|0",
       "id"            : "99",
       "station" : { # only shows up if this star is under the influence of a space station
          "id" : "id-goes-here",
          "x" : 143,
          "y" : -27,
          "name" : "The Death Star"
       },
       "bodies"        : [     # only added if a probe is present
           {
               same data as get_status() on /body
           },
           ...
       ]
   }    
   "status" : { ... }
}

session_id

A session id.

star_id

The unique id of the star.

get_star_by_name (session_id, name)

Retrieves info on a single star.

{ 
   "star" : {
       "name"          : "Sol",
       "color"         : "yellow",
       "x"             : -41,
       "y"             : 27,
       "zone"          : "0|0",
       "id"            : "99",
       "station" : { # only shows up if this star is under the influence of a space station
          "id" : "id-goes-here",
          "x" : 143,
          "y" : -27,
          "name" : "The Death Star"
       },
       "bodies"        : [     # only added if a probe is present
           {
               same data as get_status() on /body
           },
           ...
       ]
   }    
   "status" : { ... }
}

session_id

A session id.

name

The exact name of a star. Case insensitive.

get_star_by_xy (session_id, x, y)

Retrieves info on a single star.

{ 
   "star" : {
       "name"          : "Sol",
       "color"         : "yellow",
       "x"             : -41,
       "y"             : 27,
       "zone"          : "0|0",
       "id"            : "99",
       "station" : { # only shows up if this star is under the influence of a space station
          "id" : "id-goes-here",
          "x" : 143,
          "y" : -27,
          "name" : "The Death Star"
       },
       "bodies"        : [     # only added if a probe is present
           {
               same data as get_status() on /body
           },
           ...
       ]
   }    
   "status" : { ... }
}

session_id

A session id.

x

The x coordinate of a star.

y

The y coordinate of a star.

search_stars (session_id, name)

If you know a partial name of a star you can search for it. Returns up to 25 results. No body data is returned with this search.

{ 
   "stars" : [
       {
           "name"          : "Sol",
           "color"         : "yellow",
           "x"             : -41,
           "y"             : 27
       },
       {
           "name"          : "Minsol",
           "color"         : "green",
           "x"             : -42,
           "y"             : 27
       }
    ],
   "status" : { ... }
}

session_id

A session id.

name

A partial name of a star. Case insensitive. Must be at least 3 characters.

probe_summary_fissures

Obtain a summary of all bodies with fissures, known to yours, or your alliances probes within a specified zone.

This takes named arguments only

{
  "session_id" : "1234-0A34-333F-21",
  "zone"       : "0|0",
}

session_id (required)

A session id.

zone (optional)

A string defining the zone, e.g "-1|0", "5|-5" or "0|0"

If not specified, all zones are searched.

RESPONSE

{
  "fissures" : {
    "345" : {
      "name"   : "Mercury",
      "id"     : 345,
      "orbit"  : 1,
      "x"      : -40,
      "y"      : 29,
      "type"   : "habitable planet",
      "image"  : "p13",
      "size"   : 58,
     },
   "735" : {
      ...
     }
   }
}

This returns a hash of body-ids and for each one a brief description of the body on which is at least one fissure;

If there are no fissures on any of the bodies which you have probed then an empty list is returned;

FAQ

These are common questions about this API.

What is a body?

A body is any object that orbits a star. In Lacuna terms this means a body is a habitable planet, gas giant planet, space station, or asteroid.