IFDB APIs > taggame

The taggame API

The taggame API lets applications edit tags on IFDB games.

Protocol

The taggame API is implemented as an http XML web service at https://ifdb.org/taggame?xml. All parameters are passed as POST data with the HTTP request. As typical for HTTP, there's no session state or context; the entire transaction is carried out as the single request.

Parameter names and values

username: the IFDB username for the account under which the listing will be created. Ordinary text parameter; required.

password: the user's IFDB password. Ordinary text parameter; required.

id: the TUID for the game you want to update. Ordinary text parameter; required.

t0: the content of the first tag you want to attach to the game. For example, t0=witchcraft would attach the "witchcraft" tag on the game. Ordinary text parameter; optional.

t1, t2, t3: attach additional tags in a single request using additional numbered parameters. Ordinary text parameters; optional.

The tags you add will remove/replace all tags you've previously set. If you submit a request with t0=example1 and then later submit a request with t0=example2, the API will remove your "example1" tag, replacing it with "example2". If you don't pass a t0 parameter, all of the tags you've set will be removed.

To add a tag without removing any tags, first query for your existing tags using the gametags API, with the mine_only parameter.

Reply format

The server replies to the request with an XML object describing the result. The response has this tag structure for a successful transaction:

<response>
    <label>Saved</label>
    <tag>
        <name>example</name>
        <tagcnt>1</tagcnt>
        <gamecnt>1</gamecnt>
    </tag>
</response>

The tagcnt tag shows how many users have used that tag on the currently selected game. (Normally, tagcnt will be 1, because it's unusual for a player to add a tag when the game already has that tag.)

The gamecnt tag shows how many games have used that tag.

On error, the reply has this structure:

<response>
    <label>Not Saved</label>
    <error>Please specify a valid username and password to login.</error>
</response>