External Services and Tools/API Documentation

All scripts are located at http://battlemaster.org/data/. So, for example, to get the region data of Akesh Temple, you would access the URL

http://battlemaster.org/data/region.php?World=1&ID=1.

API Change Requests

If you want changes to the API, especially new data disclosed, please post to the talk page. Include what you need it for. We follow the X-Window Manifesto: "Do not add new functionality unless you know of some real application that will require it."

listrealms.php

Parameter	Type	Meaning
World	integer	Game world ID you access, see #World IDs

Output:

<listing>
  <realm-ids> comma-seperated list of integers </realm-ids>
  <realm-names> comma-seperated list of strings </realm-names>
</listing>

Note that these two lists are not sorted relative to each other, so you can not take entry #x from one list and think it corresponds to entry #x from the other. IDs are listed numerically, names are listed alphabetically.

Example

Realms on the East Island 

http://battlemaster.org/data/listrealms.php?World=1

listregions.php

Parameter	Type	Meaning
World	integer	Game world ID you access, see #World IDs

Output:

<listing>
  <region-ids> comma-seperated list of integers </region-ids>
  <region-names> comma-seperated list of strings </region-names>
</listing>

Note that these two lists are not sorted relative to each other, so you can not take entry #x from one list and think it corresponds to entry #x from the other. IDs are listed numerically, names are listed alphabetically.

Example

Regions on the East Island 

http://battlemaster.org/data/listregions.php?World=1

region.php

Parameter	Type	Meaning
World	integer	Game world ID you access, see #World IDs
ID	integer	ID number of the region in question. You can find this through the listregions.php script, or by examining the URL of the "Details" link on the Region List page, or (if the page is already set up correctly) on the region's page here in the wiki. Can be replaced by Name
Name	text/string	Can replace ID. Name of the Region being queried.

Output:

<regiondata>
   <continent> string </continent>
   <id> integer </id>
   <name> string </name>
   <type> string </type>
   <area> string </area>
   <population> number </population>
   <economy> comma-seperated list of strings </economy>
   <realm> string </realm>
   <duchy> string </duchy>
   <lord> string </lord>
   <xpos> integer </xpos>
   <ypos> integer </ypos>
</regiondata>

Example

The City of Libidizedd by ID 

http://battlemaster.org/data/region.php?World=8&ID=200

The City of Eidulb by name 

http://battlemaster.org/data/region.php?World=8&Name=Eidulb

realm.php

Parameter	Type	Meaning
World	integer	Game world ID you access, see #World IDs
ID	integer	ID number of the realm in question. You can find this for example by examining the URL of the "Details" link on the Realm List page, or (if the page is already set up correctly) on the realm's page here in the wiki. Can be replaced by Name.
Name	text/string	Can replace ID. Name of the Realm being queried.
WithRegions	boolean	optional - if given, a list of region IDs (for use in the region.php script) and region names is included. only use this if you need them, it is considerably more expensive on the database than without

Output:

<realmdata>
   <continent> string </continent>
   <id> integer </id>
   <name> string </name>
   <colour> HTML colour value </colour>
   <system> string </system>
   <rulertitle> string </rulertitle>
   <rulername> string </rulername>
   <generaltitle> string </generaltitle>
   <generalname> string </generalname>
   <judgetitle> string </judgetitle>
   <judgename> string </judgename>
   <bankertitle> string </bankertitle>
   <bankername> string </bankername>
   <capital> integer </capital>
</realmdata>

Example

The Realm of Darka by ID 

http://battlemaster.org/data/realm.php?World=2&ID=14

The Realm of Arcaea by name, with regions 

http://battlemaster.org/data/realm.php?World=7&Name=Arcaea&WithRegions=True

character.php

Parameter	Type	Meaning
World	integer	Game world ID you access, see #World IDs
ID	integer	ID number of the character in question. This is usually only found in the source code of some pages. Name is more logical in this case.
Name	text/string	Can replace ID. Name of the Noble being queried.

Output:

<nobledata>
   <continent> string </continent>
   <id> integer </id>
   <name> string </name>
   <family> string </family>
   <mainclass> string </mainclass>
   <subclass> string </subclass>
   <age> integer </age>
   <honour> integer </honour>
   <prestige> integer </prestige>
   <rank> string </rank>
   <gender> string </gender>
   <region>string</region>
   <duchy> string </duchy>
   <realm> string </realm>
</nobledata>

Example

The character Brance Indirik by ID 

http://battlemaster.org/data/character.php?World=8&ID=34

The character Taylin Indirik by name 

http://battlemaster.org/data/character.php?World=7&Name=Taylin

family.php

Parameter	Type	Meaning
ID	integer	ID number of the family in question. This is identical to the User ID that can be found on the user details page.
Name	text/string	Can replace ID. Name of the family being queried.

Output:

<familydata>
   <id> integer </id>
   <name>  string </name>
   <fame>integer </fame>
   <wealth> integer </wealth>
</familydata>

Example

The Indirik family by ID 

http://battlemaster.org/data/family.php?ID=14094

The Anaris family by name 

http://battlemaster.org/data/family.php?Name=Anaris

Additional Information

World IDs

The various game worlds of BattleMaster are internally accessed through ID numbers. Here is the mapping:

ID	World
1	East Island
2	Atamara
4	Beluaterra
6	Colonies
7	Far East
8	Dwilight

Yes, 3 and 5 are missing. They used to be the IDs of South-West and South-East Island.

Other IDs

You can query most data sets by ID number or by name. Querying by name is considerably more expensive on our database, so we strongly encourage you to locally cache the ID/Name associations that you learn. That is why all datasets return the ID.

Output Values

Many values can be empty, e.g. when the realm currently has no banker, or if a region does not belong to a duchy (i.e. an imperial region). Empty values are always returned as empty strings, e.g.:

<bankername></bankername>

Nevertheless, external tools should fail gracefully if an expected tag is missing.

XML Tree

These data scripts were written with MediaWiki's External Data extension in mind. The extension does not parse an XML tree, but simply scans for key/value pairs. Therefore, we do not generate tree structures in our output. For example, in a pure XML environment, the output for realm governments would instead be something like

<ruler>
   <name> string </name>
   <title> string </title>
</ruler>

However, since the extension does not parse the tree, the next occurrance, say within the general tag would overwrite the variables "name" and "title".

Your application must, however, recognize and parse the XML tags. We can and will change the order of the tags as we see fit without notice, so do not use an approach like "ok, 2nd entry is the name..." - always do parse the tags.