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>

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 for example 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>
</regiondata>

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>
</realmdata>

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>

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>

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.