This is part two of what is now a three part series on accessing the D&D Insider Compendium API (Application Programming Interface). In the first article I discussed the methods for using the querystring parameters to return a set of search results as formatted HTML. Now we will move a step deeper and call the web service directly to return the XML that is used to format those results. The Compendium utilizes a .Net web service called CompendiumSearch.asmx. Because it is .Net it can be called utilizing SOAP 1.1 or 1.2 and HTTP POST and GET methods. The web service is located at www.wizards.com/dndinsider/compendium/co... and has four public methods. You can open the address in a web browser to see a list of the methods and gain access to the calling syntax for each. The invoke buttons on the method pages won't work if you click them as the WSDL doesn't have all of address information (this is due to how our routers and servers are set up). I'll put the full address for each method in my descriptions below. The first listed method: GetFilterSelect is used to populated the drop down lists present in the database.aspx filters. This method has no parameters and returns an XML document that the JavaScript uses to build the lists. The full address for this method is www.wizards.com/dndinsider/compendium/co.... You probably won't have a lot of use for this method as it is more meta information than actual game info. The next two methods: KeywordSearch and KeywordSearchWithFilters are the main search methods and the ones most useful to API developers. KeywordSearch has two parameters: string Keyword, string Tab. KeywordSearchWithFilters has the same two parameters with a third: string Filters. The address for KeywordSearch is www.wizards.com/dndinsider/compendium/co... and for KewyordSearchWithFilters is www.wizards.com/dndinsider/compendium/co....
- Keywords: The Keywords parameter is the same as the text you type in the search box in the Compendium. For the KeywordSearch method this parameter is required, otherwise you will get 0 results. For KeywordSearchWithFilters it is optional allowing you to search based only on the filter values.
- Tab: The Tab parameter allows you to specify which category has focus when the results return. By default the category that has the most results gets focus, but this option allows you to overide it. The parameter is optional on KeywordSearch but required on KeywordSearchWithFilters. Valid values are: Race, Class, Power, Feat, Item, Skill, Ritual, ParagonPath, EpicDestiny, Monster, Deity, Glossary.
- Filters: Filters are passed to the method as a pipe (|) delimited list of values for each filter option in a category. Whenever an option is blank or the drop-down is set to "Select All", the word NULL should be passed instead of a value. The list of values differ between each category, but must be placed in a specific order for all categories. The following table has the filters and acceptable values for each category:
| Category | Order | Option | Value |
|---|---|---|---|
| Power | 1 | Action Type | Name of action (free, minor, move, etc.) |
| Power | 2 | Class | Name of class power is for (Fighter, Cleric, Warlock, etc.) |
| Power | 3 | Kind | What kind of power it is (Utility, Attack, Cantrips, etc.) |
| Power | 4 | Level Min | Number between 1 and 30 |
| Power | 5 | Level Max | Number between 1 and 30 |
| Power | 6 | Source Book | Number representing the internal ID of the source book. ID numbers can be found using the GetFilterSelect method. |
| Power | 7 | Usage | How often the power can be used (At-Will, Daily, etc.) |
| Item | 1 | Category | Category or item slot keyword (Weapon, Neck, Companion, etc.) |
| Item | 2 | Level Min | Number between 1 and 30 |
| Item | 3 | Level Max | Number between 1 and 30 |
| Item | 4 | Cost Min | Minimum cost of item (must be a number or null) |
| Item | 5 | Cost Max | Maximum cost of item (must be a number or null) |
| Item | 6 | Enhancement Min | Number between 1 and 6 |
| Item | 7 | Enhancement Max | Number between 1 and 6 |
| Item | 8 | Source Book | Number representing the internal ID of the source book. |
| Creature | 1 | Level Min | Number between 1 and 30 |
| Creature | 2 | Level Max | Number between 1 and 30 |
| Creature | 3 | Keyword | Specific keywords associated with the creature (Elf, Air, Natural, etc.) |
| Creature | 4 | Main Role | Name of role (Lurker, Soldier, Artillery, etc.) |
| Creature | 5 | Group Role | Name of role (Minion, Solo, Elite, Standard, etc.) |
| Creature | 6 | XP Min | Minimum XP value of the creature |
| Creature | 7 | XP Max | Maximum XP value of the creature |
| Creature | 8 | Source Book | Number representing the internal ID of the source book. |
| Glossary | 1 | Category | Monsters, Weapons, Powers or Rules |
| Glossary | 2 | Type | Name of the type (Damage Type, Keyword, Power Source, etc.) |
| Glossary | 3 | Source Book | Number representing the internal ID of the source book. |
| Feat | 1 | Tier/Category | Heroic, Paragon, Epic or Other |
| Feat | 2 | Source Book | Number representing the internal ID of the source book. |
| Ritual | 1 | Level Min | Number between 1 and 30 |
| Ritual | 2 | Level Max | Number between 1 and 30 |
| Ritual | 3 | Key Skill | Name of skill required to perform ritual (Arcana, Religion, Nature, etc.) |
| Ritual | 4 | Cost Min | Minimum cost of item (must be a number or null) |
| Ritual | 5 | Cost Max | Maximum cost of item (must be a number or null) |
| Ritual | 6 | Source Book | Number representing the internal ID of the source book. |
| ParagonPath | 1 | Class | Name of class required for path (Fighter, Cleric, Warlock, etc.) |
| ParagonPath | 2 | Race | Name of race required for pathaction (Human, Dragonbord, Drow, etc.) |
| ParagonPath | 3 | Source Book | Number representing the internal ID of the source book. |
| Deity | 1 | Alignment | Deities alignment (Lawful Good, Evil, Unaligned, etc.) |
| Deity | 2 | Source Book | Number representing the internal ID of the source book. |
The final method is ViewAll. As it sounds, this is used to view all entries for one category at a time. It has one parameter: string Tab. This is a required parameters and may be any of the values as listed for KeywordSearch's Tab parameter. All three of these methods return an XML Document. The document has several nodes in it the number of which and format of vary depending on the parameters passed in. In essence though, all have a similar basic structure:
- A root node of
- A child node of
which contains a child node data set of the actual results broken down by category - A child node of
which is used by the compendium to show the result counts
In the third and final article I will talk about accessing individual data entries and security issues and concerns.
This is very good stuff. Any chance that part 3 will see the light of day? Any chance we'll see other WotC API's? ThanX much!
awmyhr04:52 PM PST