NCard API 1.2: Auto update from the Wii [Updated]

It is now possible to auto update the NCard from the Wii or any other device. Currently the API only supports the most basic functions, retrieving the key and updating the gamercard.  For a more detailed explanation of the system read on.

This is version 1.2 of the Ncard API.

New commands in 1.2

tdbupdate: the same thing as update but uses the more accurate wiitdb. This takes the wii title Id rather than the wii message board short name of the game.  This is the preferred method of submitting games going forward and “update” is deprecated as of version 1.2

New commands in 1.1:
lastsync :returns last sync time
update : allows multiple games to be uploaded at once with count argument

Secret Key

Every user has a key. Anyone with this key can update the user’s card.  Unlike a username and password, it does not provide any other access to the user’s account.

Structure

The API is HTTP GET commands. This way any program that can make a connection on port 80 will be able to update the gamercard. All commands will take the following format:

http://www.messageboardchampion.com/ncard/API/?cmd=<comamnd>&<argument1>=xxx&<argument2>=xxx …

The output will always be plain text. Either confirming the success of the operation, returning a value or a human readable  error message.

Getting the Key

The user can either provide their key (this is shown in the users preferences page)  or if they do not want to type it, the developer can use the user’s username and password to retrieve the key.  Calling the following command will return a single line of text, which is the user’s key. This is the only time the username and password is required. This only needs to be called once. The developer should save the key value on the Wii for future use and not the username and password.

http://www.messageboardchampion.com/ncard/API/?cmd=login&username=<username>&password=<password>

Getting Last Sync Time

This is an optional command. Clients may want to check with the server to see when the last game was added.  This includes both games added from the web and the  client. Clients wishing to use this as a means of tracking which recently played games to upload should advise the user to NOT update their card from the website as it would bring the client out of sync with the server.

http://www.messageboardchampion.com/ncard/API/?cmd=lastsync&key=<key>

Updating the Card

Single game

Once the key has been acquired. The application can update the card as often as it likes. Each update will refresh the gamer card. The basic update command looks like this:

http://www.messageboardchampion.com/ncard/API/?cmd=tdbupdate&key=<key>&game=<game id>

On success this will return “OK” errors will return a single like of human readable text. This can be used for messages to the user in the application.

Multi game

If doing an update with multiple games, it is recommended for now that you use the count argument and add an index number on the game.  In multi game updates make the call in the order the games were played so the newest game has the highest number last and the card shows it at the top of the deck.

example:

http://www.messageboardchampion.com/ncard/API/?cmd=tdbupdate&key=<key>&cout=<number of games>&game1=<game1 id>&game2=<game 2 id>

On success this will return miltple  ”OK <game name>”.  errors will return a single like of human readable text. This can be used for messages to the user in the application.

example session:

http://www.messageboardchampion.com/ncard/API/?cmd=tdbupdate&key=<key>&count=2&game1=Metroid&game2=Contra

will return:

OK <game name>
OK <game name>

when using he tdbupdate command you submit the wii title ID.  The old “update” command is deprecated and will be removed in the future. Please do not use it anymore.

Since games are being added by name, it is very important that the game name passed be the proper fullname of the game. If in doubt check giantbomb.com and see what name is used since that is the database being searched. Games updated from the Wii do not have this problem. The server will match the Wii short name with the correct game name.

e.g

Mario 3  should be Super Mario Bros. 3 so it is no confused with  Super Mario Land 3

Legend of Zelda should be The Legend of Zelda so it is not confused with all the other games in the series.

Ocarina of Time should be The Legend of Zelda: Ocarina of Time