RMRKMon JSON API

[Roph]

Not sure if anyone will use this, but whatever. Here's a method to retreive a user's data from RMRKMon in JSON format.

JSON Encoder/Decoders for RMVXA exist, maybe someone would like to make a pokemon themed game for the next GIAW that lets RMRK users play with their own pokemon? 

Download RMRKMon Images (including pokemon graphics etc) here.

[edit]
Dat documentation:

Pokemon Data Dump

Attached to this post you'll find a .json dump of RMRKMon's pokemon info. This includes each pokemon's name, type (fire, steel etc), appearance chance rate, evolution from/to paths and version affinity. It also includes a description of the type array we use (1:Bug all the way to 18:Water), as well as the IDs, names and colours for our Versions (tyria/lisera).

This data is static so you should simply download it and reference it alongside your project. However, occasionally we may tweak chances and eventually we'll add newer generations of pokemon. If you care to be up to date after such changes, you can grab a fresh dump ( ) right here.

Notes On Data

Pokemon IDs / Shininess
As a collecting / trading minigame, RMRKMon stores pokemon in a trainer's profile literally as a list of pokemon IDs - comparable to a list of trading cards owned. Pokemon do not have unique entries and cannot have unique attributes assigned to them (as if they were real pokemon with levels, names, moves, genders, forms and so on). The only exception to this is shiny status. A shiny pokemon is represented by an additional decimal point. So for example, Pikachu is 25. Shiny pikachu is 25.3.

I would suggest creating a function in your script/app that simply uses floor, intval, round, or some other similar function and compares the result to the input to check if a pokemon is shiny or not. In PHP, RMRKMon's boolean is_shiny() function is this:

[spoiler]function is_shiny($v) {
    $shinytest = floor($v);
   if ($shinytest != $v) return true;
   else return false;
}[/spoiler]

Data that may not exist
While all trainers are RMRK members, not every RMRK Member is a trainer. Members automatically get a trainer profile created for them upon their first encounter with a pokemon. A trainer profile is created also in the event that a pokemon is gifted to a user with no profile. Because of this, even if a trainer profile exists, you cannot be sure that it has any owned pokemon or pokedex entries.

Trainers always have a trainer picture set (by default, 1.gif), but favourite pokemon are optional. As are the additional favourite pokemon. A user is not forced to choose 5 extra favourites either, they may choose just one if they wish. However, a user cannot choose extra favourite pokemon until they have a main favourite pokemon.

Inventories
Assuming an active trainer, the trainer will have three similar but distinct inventories. First is pokemon, which is simply the pokemon they own. Duplicates are allowed, as are shiny pokemon.

Next is seen, which uniquely logs each pokemon encountered. Shiny pokemon are counted seperate to their normal variants, but no duplicates are allowed.

Dex is only made up of pokemon the user owns or has owned at some point. As in the games, the dex ignores shiny status. Capturing or receiving a shiny Mewtwo will place a 150 in a user's pokedex.

Discrepancies
Capture and encounter events were not always logged, thus some trainers who were quite active at the start may have total_encounters and total_catches that are impossibly low compared to their current inventories. As time goes on this becomes less of an issue - especially with the introduction of trading (which increases neither tally).

Querying User Data

Identifying which user's data you want can can be done through two methods - either their RMRK account ID, or their username. The request parameter is different depending on each one.

A little note for JSON decoders that don't quite meet the spec (such as the RMVXA one by game_guy) - while JSON allows whitespace to make it human readable, some decoders don't account for this and only properly decode json if it's all on a single line. You can force such output from the RMRKMon API with a raw parameter. e.g. http://rmrk.net/pokemon/api.php?trainer=273;raw

ID Request: trainer parameter
http://rmrk.net/pokemon/api.php?trainer=273
Name Request: user parameter
http://rmrk.net/pokemon/api.php?user=Roph

While it's more user friendly to ask a user for their name than give their ID, inside your game/application you should try to avoid making user requests. This is because usernames may change, or new users may exist with conflicting display names (the API selects the first match found). If your game or app is making a one off request then fine, but if you plan to pull updates in the future, save the id from the response and then use it for subsequent trainer requests.

Response Structure

Error Responses
You should check for the existence of an "error" key before proceeding. If an error is encountered, ONLY the error key is returned and no extra information is (or can be) output. The error key has 2 entries, [error][code] (Integer) and [error][description] (String).

1: Missing Parameters, e.g. you made no request or your misspelled one.

2: Trainer Does Not Exist. All trainers are RMRK Members, but not all RMRK Members are trainers.

3: Email Lookup Forbidden. Usernames only are allowed for user requests.


Normal Response

response_time (Integer) | Always SetUNIX Timestamp of when this response was generated. Use it for caching, or to make sure your data is within a certain age boundry.


name (String) | Always SetTheir RMRK Username


id (Integer) | Always SetTheir RMRK Account ID


gender (String) | Always Set, Default: nullTheir RMRK Account's gender setting. Male/Female/null


member_since (Integer) | Always SetUNIX Timestamp of their RMRK registration


trainer_since (Integer) | Always SetUNIX Timestamp of their first sighting (and thus when they became a trainer)


last_login (Integer) | Always SetUNIX Timestamp of when they were last active on either RMRKMon or RMRK (whichever is most recent)


last_caught (Integer) | Always Set, Default: 0UNIX Timestamp of last pokemon capture receival of a gift


is_online (Boolean) | Always SetOnline status, duh


page (String) | Always SetURL of their RMRKMon trainer page, eg http://rmrk.net/pokemon/?trainer=273


profile (String) | Always SetThe URL of their RMRK profile, eg http://rmrk.net/index.php?action=profile;u=273


picture (Array) | Always SetImages related to this user


                                        id (Integer) | Always Set, Default: 1                                        The number of which trainer pic they are using


                                        href (String) | Always Set                                        URL to said trainer picture (though you should display a local copy)


                                        avatar_href (String) | Always Set, Default: (RMRK's "no avatar" image)                                        URL to their forum avatar. Typically 105x150, though may be smaller or in some cases larger.


fave (Numeric) | OptionalThe ID of their favourite pokemon, if any.


extrafave (Numeric Array) | OptionalAn array of up to 5 extra favourite pokemon. Again optional, though a user cannot choose extra faves without first having a main fave.


total_trades (Integer) | Always Set, Default: 0A tally of the trainer's completed trades


total_encounters (Integer) | Always Set, Default: 0A tally of the trainer's encounters on the forum.


total_catches (Integer) | Always Set, Default: 0A tally of the trainer's successful catch events.


total_pokemon (Integer) | Always Set, Default: 0A tally of the trainer's pokemon inventory


badges (Incremental Array) | Always Set, Default: Empty ArrayContains as many sub-arrays as the user has badges, each having 2 entries. [0] being the badge's "ID" (aka its filename without the .png),[1] being its description.


total_seen (Integer) | Always Set, Default: 0The number of unique pokemon the trainer has seen. For instance, seeing a blastoise for the first time and then seeing 5 more blastoises would still only increase this by 1.


total_dex (Integer) | Always Set, Default: 0How many pokedex entries this trainer has.


pokemon (Array) | OptionalThe user's current pokemon inventory


                                        string (String) | Always Set                                        A comma separated string of their inventory.


                                        raw (Numeric Array) | Always Set                                        An array of their inventory by ID


                                        named (Associative Array) | Always Set                                        An ID => Name array of their inventory. For example, [pokemon][named][25.3] = Pikachu (Shiny).


seen (Array) | OptionalPokemon this user has seen


                                        string (String) | Always Set                                        A comma separated string of their sighted pokemon.


                                        raw (Numeric Array) | Always Set                                        An array of their sighted pokemon by ID


                                        named (Associative Array) | Always Set                                        An ID => Name array of their sighted pokemon. For example, [seen][named][9] = Blastoise.


dex (Array) | OptionalPokedex entries for this trainer.


                                        string (String) | Always Set                                        A comma separated string of their dex.


                                        raw (Numeric Array) | Always Set                                        An array of their dex by ID.


                                        named (Associative Array) | Always Set                                        An ID => Name array of their dex pokemon. For example, [dex][named][151] = Mew.


                                        percentage (Numeric) | Optional                                        Their pokedex completion against all pokemon in RMRKMon as a percentage, represented to 2 decimal places. e.g. 29.41

Response Structure Notes

[dex][percentage] is calculated based on all pokemon that exist in RMRKMon, even those that are disabled. So as of this writing, pokedex percentages are based on 720 pokemon in total, even though gens 5 and 6 (#494 and beyond) are disabled.

the [named] parts of the [pokemon], [dex] and [seen] arrays, by being associative, cannot represent duplicate pokemon. This is only an issue with [pokemon][named], as a trainer's seen/dex entries forbid duplicates. If a user owns 10 charizards, only one is in this array as charizard's key ([6]) is in use. Thus, don't iterate or foreach( key=>value ) through the [pokemon][named] array thinking you will be showing their full inventory. Use it for reference.

[Roph]

Reference PHP Implementation

Find attached to this post a .zip containing a PHP based reference implementation. Just unzip this and upload it to a PHP-compatible web-server and then visit in your browser. I've uploaded a copy here:

http://rose.roph.eu/rmrkmon/?trainer=Roph

The link above is on a seperate server to the one that RMRK and RMRKMon runs on. It gets its data through the JSON API. All the files and source code behind it are in the .zip Feel free to use it to learn more about using such data.

[Roph]

RMRKMon Data

Here you can get all the required images you might want to use. RMRKMon specific images (badges, trainers etc) and pokemon image collections in general. RMRKMon has many sets of images, and they are:

RMRKMon Specific: Badges, Bases, Trainers, Types - Grab all of them here

Pokemon Image archives:
Animated BW style (Normal+Shiny 96x96 gif)
Animated XY style (Normal+Shiny, various resolution transparent gifs)
Global Link Art, SVG - auto-generated .svg vector graphics
Various pre-rendered resolutions of the above global link art, all transparent png: 300x300, 900x900, 2000x2000
Ken Sugomori Art (Various resolutions, transparent png)
CSS Sprite Sheets + required .css - basic instructions are included in the .css file
Icons (Normal+Shiny 32x32 transparent png)
Named cards (Normal+Shiny 96x110 png)
Static back sprites (Normal+Shiny 96x96 transparent png)
Static front sprites (Normal+Shiny 96x96 transparent png)

Alternatively, you can grab ALL the above images in one giant file.

[exhydra]

I am tinkering with something, yes. I barely have any knowledge of Pokemon, and no real desire to create a Pokemon game by myself ... but creating a script to communicate with the backend seems fun. I wish the HTTP API was available natively for Ruby within RPG Maker ... ah well. Time to do everything by hand.

Also, kind of a minor aspect, but could the gender of the trainer be made available through JSON data as well (to preemptively answer the 'are you a boy or girl' question, perhaps)?

[strike]

careful or roph will call you cis scum.

[Roph]

Hmm. I could go from the RMRK account's gender selection (if any), or it could be figured out from the trainer picture. Some users have conflicting entries.

[Roph]

Also wow, passing RMRKMon's PNGs through one of those optimizer tools (followed link in your sig), on average they're all being shrunk by ~35%

[exhydra]

Yeah, surprised me how much metadata and other information could be stripped and still maintain the quality of the PNG.      Can save quite a bit of space.

[Roph]

I should add, picture => id refers to the trainer picture they've chosen in RMRKMon. Always set, 1 by default. I did start on a fancy documentation post on my local copy of RMRK, but it started to look wrong with longer descriptions, and SMF's bbcode tables aren't so fun.

Trainerpics aren't included in that RMRKmon image archive, so here they are attached:

[Roph]

Added some proper documentation to the first post

[exhydra]

Awsomeness. Now, if I can just cobble together a front end ...

[PhoenixFire]

hmm... this really could be an interesting idea if done properly..

[exhydra]

Success! Now to tinker around some more ...

[exhydra]

What is the proper content type for JSON? I have been trying 'application/json' and 'application/javascript', but neither seem to be working (or I am doing something incorrect). I keep getting JSON in HTML format.

[Roph]

application/json: http://en.wikipedia.org/wiki/JSON#MIME_type

This is what's sent from RMRK:



I can try changing it to something else if you like?

[exhydra]

No, just means that the content type is not being passed along as it should be. Bah ...

[Roph]

Hmm. Either way, it's just plain text. That RMVXA JSON script just appears to interpret a given string as JSON. What would content-type have to do with that?

[Roph]

Just added a gender entry to the response

[exhydra]

Hmm. Either way, it's just plain text. That RMVXA JSON script just appears to interpret a given string as JSON. What would content-type have to do with that?

Well, what happens is that extra line feeds and padding is added to the JSON, and the JSON decoding script chokes. For the script to work, everything needs to be on a single line, basically ... no formatting. Now, I am not entirely sure ... is that because of the content type, or is that something that is done for human readability?

EDIT: Now, I could just lop off the line feeds and probably remove the padding ... but I figured something was wrong on my end to make that happen in the first place.

[Roph]

Ah, that's on my end. I'm using an option in PHP's json encoder to make it human readable. Whitespace shouldn't interfere with anything though

Blame game_guy for his non-JSON-compliant script

I just added an option to disable any whitespace formatting with a raw parameter. Just add ;raw on the end.

http://rmrk.net/pokemon/api.php?trainer=273;raw
http://rmrk.net/pokemon/api.php?pokedump;raw

[exhydra]

Is there any upper limit on characters allowed for user names on the forums?

[Roph]

Somewhere yes. I made a user with the longest name possible on my local SMF install, and it ended up as "the really long named user derp dongs ham sandwiches with mu"

[exhydra]

Hmm, the outputted error messages are ignoring the 'raw' option and coming out formatted.

[Roph]

Ah, of course. I do those manually. Will fix =o

[Roph]

Fixed http://rmrk.net/pokemon/api.php?trainer=99999999