Not logged in | Log in
Pirates of the Burning Sea logo
 
 
 

Data API

,

The Pirates of the Burning Sea Data API can be used for creating a webpage where players can check the status of the Pirates of the Burning Sea without logging into the game. See Other Pages Using Data API for examples of these pages.

Contents

Obtaining Credentials

"Developer Program Access"
After logging-in go to burningsea.com/pages/developer to receive your Private Key and User ID.

The Pirates of the Burning Sea Data API relies on retrieving XML fragments via the HTTP POST protocol. As a parameter in the POST, you must provide your API key in a field called apikey which contains the API Key assigned to your account and userid which contains the User ID for your account. To obtain your credentials follow these steps:

  1. Go to burningsea.com and click the Log in button in the upper-left corner. You will be redirected to the login page.
  2. Login using your Station login information.
  3. Go to burningsea.com/pages/developer to receive your credentials.

Example Code

"Sample code and XML result."
Above is sample code you may use to create a very basic interaction with the API. Replace A with your Private Key and B with your User ID.
Below is an example of the result from that sample code; the exact values will vary.

If you've never used an API, this page might be a little difficult to understand. Here is a simple example to get you started experimenting with the API.

  1. Open up a text editor such as Notepad or TextPad. This is where you will write the HTML that communicates with http://data.burningsea.com.
  2. Copy and paste the below text, but replace the XXXX-XXXX-XXXX-XXXX in value="XXXX-XXXX-XXXX-XXXX" with your Private Key and replace the 111111 in value="111111" with your User ID.

    <html>
    <body>
    <form action="http://data.burningsea.com/servers" method="post">
       <input type="hidden" name="apikey" value="XXXX-XXXX-XXXX-XXXX">
       <input type="hidden" name="userid" value="111111">
       <input type="submit" value="Show Server List">
    </form>
    </body>
  3. Save this file with a .html extension; e.g., save the file as test.html.
  4. To view the file, open it in a web browser. You should see a blank page with a button labeled Show Server List.
  5. Click on the Show Server List button. The button should disappear and you will see either some text (similar to 2010-05-03T16:48:45-07:00) or a blank page. You are now looking at an XML file, but your browser is having a hard time viewing the file, because the file does not include any formatting information.
  6. To see the actual file, right click on that page and click on View Page Source. This will bring up a window with the XML. The numbers as in ENGLAND="1" are explained below under Server Status Information.

About the Data API

There are a number of URLs from which you can retrieve data. Each is explained below, along with information on the XML fragment returned by the URL and an explanation of the fields in that fragment. The following APIs are available:

The documentation below shows the URL to retrieve the information, a description and sample of the XML fragment and use, and a detailed description of the elements and fields in the XML fragment.

In order to not strain our data servers, you are required to cache the results of a given call for the Timeout length as given for each call (each call has a different duration). In any case, the web service caches each call's results for the time listed below, so you will not receive updated data if you retrieve the data faster than that.

Server Status Information

The Server Status Information URL retrieves information about server status for each server. It contains a ServerList element containing a series of server elements. Each server element contains the following parameters:

  • name
  • status
  • version

And the following optional parameters:

  • ENGLAND
  • SPAIN
  • FRANCE
  • PIRATE

URL: http://data.burningsea.com/servers

Cache Duration: 1 minute

<ServerList>

<server name="serverA" status="Offline" version="1.02.20.00" />
<server name="serverB" status="Online" version="1.02.22.00" ENGLAND="0" SPAIN="2" FRANCE="3" PIRATE="0" />
<server name="serverC" status="Online" version="1.02.17.00" ENGLAND="1" SPAIN="0" FRANCE="3" />
<server name="serverD" status="Locked" version="1.02.20.00" ENGLAND="0" />
<server name="serverE" status="Online" version="1.00.44.00" PIRATE="2" />

</ServerList>

Field Descriptions

  • name—The name ID of the server
  • status—The status of the server, either Offline, Online, or Locked
  • version—The version number of the game server running on this cluster
  • ENGLAND—(optional) The current English population on this server; either 0 (Light), 1 (Moderate), 2 (Heavy), or 3 (Very Heavy)
  • SPAIN—(optional) The current Spanish population on this server; either 0 (Light), 1 (Moderate), 2 (Heavy), or 3 (Very Heavy)
  • FRANCE—(optional) The current French population on this server; either 0 (Light), 1 (Moderate), 2 (Heavy), or 3 (Very Heavy)
  • PIRATE—(optional) The current Pirate population on this server; either 0 (Light), 1 (Moderate), 2 (Heavy), or 3 (Very Heavy)

Server Status (Individual) Information

The Server Status (Individual) URL retrieves information about server status for the server given by server ID. It contains a single server element as described in Server Status Information above.

URL: http://data.burningsea.com/servers/serverName

Cache Duration: 1 minute

<server name="serverC" status="Online" version="1.02.17.00" ENGLAND="1" SPAIN="0" FRANCE="3" />

Landmark Status Information

The port state XML contains PortList element, which in turn contains zero or more Port elements. The port elements detail information about a port on that server, including PvP state, server victory state, its location in the world, and so on. The Port element has a resources element containing one or more e elements, each of which contains the Resource ID of the resource.

URL: http://data.burningsea.com/servers/serverName/landmarks

Cache Duration: 10 minutes

<PortList>

<Port name="Ambrgs" currOwner="ENGLAND" defaultOwner="ENGLAND" level="20" xPosition="-3030038" zPosition="-369654" area="area_br_mid" conquerable="False" portState="LM_NORMAL" piratePvPRange="0" fullPvPRange="0" englandUnrestPoints="0" spainUnrestPoints="0" franceUnrestPoints="0" pirateUnrestPoints="0" attackerBattlePoints="0" ownerBattleConquest="0" englandConquestPoints="0" spainConquestPoints="0" franceConquestPoints="0" pirateConquestPoints="0" englandConquerCount="0" spainConquerCount="0" franceConquerCount="0" pirateConquerCount="0">
<resources />
</Port>
<Port name="BelIsl" currOwner="FRANCE" defaultOwner="FRANCE" level="20" xPosition="-3435384" zPosition="-1417884" area="area_fr_mid" conquerable="True" portState="LM_NORMAL" piratePvPRange="0" fullPvPRange="0" englandUnrestPoints="0" spainUnrestPoints="0" franceUnrestPoints="0" pirateUnrestPoints="0" attackerBattlePoints="0" ownerBattleConquest="0" englandConquestPoints="0" spainConquestPoints="0" franceConquestPoints="0" pirateConquestPoints="0" englandConquerCount="0" spainConquerCount="0" franceConquerCount="0" pirateConquerCount="0">
<resources>
<e>PUBLIC_DOCK</e>
<e>ORE_SULFUR</e>
<e>ORE_COPPER</e>
<e>ORE_SILVER</e>
<e>FERTILE_SOIL</e>
</resources>
</Port>

</PortList>

Field Descriptions

  • name—The name ID of the port
  • currOwner—The nation ID of the current owner of the port
  • defaultOwner—The nation ID of the default owner of the port
  • level—The level of the port (used for NPC spawns)
  • xPosition—The world x-position of the port, in centimeters
  • zPosition—The world z-position of the port, in centimeters
  • area—The region ID of the region this port is in
  • conquerable—True if this port is conquerable; False, otherwise
  • portState—The current unrest state ID of the port
  • piratePvPRange—The radius of the pirate PvP ring in meters. This is the smaller, or inner circle.
  • fullPvPRange—The radius of the full PvP ring in meters. This is the larger, or outer circle. This outer circle will only show during LM_CONTENTION.
  • timeOfLastUnrestChange—(optional) Timestamp of the last unrest change in the form "ddd MMM dd HH:mm:ss yyyy"
  • nationUnrestPoints—Unrest points earned by each player nation
  • timeOfLastBattle—(optional) Timestamp of last landmark battle in the form "ddd MMM dd HH:mm:ss yyyy"
  • battleStartDate—(optional) Timestamp when next (/previous) battle is (/was) scheduled in the form "ddd MMM dd HH:mm:ss yyyy"
  • attackerBattlePoints—Unrest points earned by the attacking nation while port is in contention (used in landmark battle)
  • ownerBattleConquest—Unrest points earned by the defending nation while port is in contention (used in landmark battle)
  • nationConquerCount—The number of times a player nation has conquered this port
  • nationConquestPoints—The number of NvN points each nation has earned for conquering this port
  • unrestStateEndTime—The timestamp showing how long the attacker has to continue to the next phase or have the port go into Martial Law, using the form "ddd MMM dd HH:mm:ss yyyy"
  • protectionStateEndTime—The timestamp when Martial Law will end after a port battle has taken place or after the attacker failed to continue to the next stage soon enough, using the form "ddd MMM dd HH:mm:ss yyyy"

Landmark Status (Individual) Information

URL: http://data.burningsea.com/servers/serverName/landmarks/landmarkName

Cache Duration: 10 minutes

The Landmark Status (Individual) Information URL retrieves port information about an individual port (by server ID and port ID). The format is the same as an individual Port element as described in Landmark Status Information, above.

<Port name="BelIsl" currOwner="FRANCE" defaultOwner="FRANCE" level="20" xPosition="-3435384" zPosition="-1417884" area="area_fr_mid" conquerable="True" portState="LM_NORMAL" piratePvPRange="0" fullPvPRange="0" englandUnrestPoints="0" spainUnrestPoints="0" franceUnrestPoints="0" pirateUnrestPoints="0" attackerBattlePoints="0" ownerBattleConquest="0" englandConquestPoints="0" spainConquestPoints="0" franceConquestPoints="0" pirateConquestPoints="0" englandConquerCount="0" spainConquerCount="0" franceConquerCount="0" pirateConquerCount="0">

<resources>
<e>PUBLIC_DOCK</e>
<e>ORE_SULFUR</e>
<e>ORE_COPPER</e>
<e>ORE_SILVER</e>
<e>FERTILE_SOIL</e>
</resources>

</Port>

Landmark Location

URL: http://data.burningsea.com/servers/serverName/landmarks/landmarkName/location

Cache Duration: 60 minutes

The Landmark Location retrieves just the xPosition and yPosition fields on a Port element.

<Port xPosition="-3435384" zPosition="-1417884" piratePvPRange="0" fullPvPRange="0" />

Landmark Location (Translated)

URL: http://data.burningsea.com/servers/serverName/landmarks/landmarkName/location/x/y

Cache Duration: 60 minutes

The Landmark Location (Translated) retrieves just the xPosition and yPosition fields on a Port element, translated such that the xPosition and yPosition coordinates translate to a maximum viewport of x,y.

<Port xPosition="-3435384" zPosition="-1417884" piratePvPRange="0" fullPvPRange="0" />

Nation Scoreboard

Each nation in Pirates of the Burning Sea is fighting for supremacy of the Caribbean. Victory for a nation is achieved by earning a set number of Server Victory Points earned through PvP and economic actions taken by members of each nation. The point totals of each nation are checked on a regular interval to see if one or more nations are above the victory threshold. Once victory is attained by one nation (or possibly two in the case of tie) there is a 24 hour PvP suppression period where no unrest can be earned. After which all of the ports are reset to their original owners and the members of the winning nation(s) receive special rewards. A full description of the PvP and server victory score board can be found in PvP and Conquest Systems. The nation score board XML contains a single NationScoreBoard tag with set of attribute fields: round state, round number, and assorted point values for each player nation.

URL: http://data.burningsea.com/servers/serverName/scoreboard

Cache Duration: 60 minutes

<NationScoreBoard roundState="RVR_NORMAL" roundNumber="0" maxPoints="300" supressContentionTime="Thu Nov 29 13:54:46 2007" nextVictoryCheckTime="Sat Dec 22 13:43:27 2007" lastVictoryResetTime="Thu Nov 29 13:54:46 2007" englandBasePoints="20" spainBasePoints="20" franceBasePoints="0" pirateBasePoints="20" englandBonusPoints="0" spainBonusPoints="0" franceBonusPoints="0" pirateBonusPoints="0" englandVictoryPoints="0" spainVictoryPoints="0" franceVictoryPoints="0" pirateVictoryPoints="0" englandOwnershipPoints="150" spainOwnershipPoints="140" franceOwnershipPoints="150" pirateOwnershipPoints="140" englandOwnedPorts="15" franceOwnedPorts="15" spainOwnedPorts="14" pirateOwnedPorts="14" englandCapturePoints="0" spainCapturePoints="0" franceCapturePoints="0" pirateCapturePoints="0" englandPortsCaptured="0" spainPortsCaptured="0" francePortsCaptured="0" piratePortsCaptured="0" englandTotalPoints="170" spainTotalPoints="160" franceTotalPoints="150" pirateTotalPoints="160" englandWonLast="False" spainWonLast="False" franceWonLast="False" pirateWonLast="False" />

Field Descriptions

  • roundState—The current server battle state; either NORMAL or SUPPRESSION
  • roundNumber—The current server round number
  • maxPoints—The number of points a nation needs to win the map
  • supressContentionTime—(optional) When PvP suppression will end, or has ended, in the form "ddd MMM dd HH:mm:ss yyyy"
  • nextVictoryCheckTime— (optional) When server victory will be checked in the form "ddd MMM dd HH:mm:ss yyyy"
  • lastVictoryResetTime— (optional) When server victory was declared in the form "ddd MMM dd HH:mm:ss yyyy"
  • nationBasePoints—Number of points each nation has
  • nationBonusPoints—Number of bonus points given to underdog nations
  • nationVictoryPoints—Number of points awarded for doing special missions and economic missions
  • nationOwnershipPoints—Number of points awarded for controlling ports
  • nationOwnedPorts—Number of ports controlled
  • nationCapturePoints—Number of points earned for winning landmark battles
  • nationPortsCaptured—Number of ports captured
  • nationTotalPoints—Total number of victory points for each nation
  • nationWonLast—True if this nation won the last round; False, otherwise
  • nationRank—The order of scoring of the last round (1-4).

String Key Translations

URL: http://data.burningsea.com/static/strings

Cache Duration: 1 day

Several fields in the XML provided by the Data API return values as string keys, rather than as strings suitable for display. In general, when you write an application using the API, you should display translated strings, rather than the string keys directly. The ID Translations URL returns a series of string translations. Using HTTP POST, you can pass in a language parameter; currently, the only values accepted are en and en-us (which return the same values). While the cache duration on this API call is set to 1 day, this file rarely changes—you should store a copy of this file locally for reference. The returned XML contains a single strings element containing a series of string elements. Each string element contains information about a single item in the system.

<strings>

<string id="FERTILE_SOIL" name="Fertile Soil" desc="The rich soil of the Caribbean is well suited to general agriculture." />

</strings>

Field Descriptions

  • id—The string key for the item
  • name—The name (translated to the requested language) for the item
  • desc—(optional) A brief description of the item (translated to the requested language)

Other Pages Using Data API

Related Links

Retrieved from "http://www.burningsea.com/wiki/index.php/Data_API"