Want to get your Japanese Kanji studies in your Ruby? This gem uses WaniKani's API so you can hook it into your Ruby projects.

Installation

$ gem install wanikani

Usage

To use the WaniKani gem, you need to set up client, using the API key from your account. The API key can be found in your account settings.

require 'wanikani'

Wanikani.configure do |config|
  config.api_key = "YOUR_API_KEY"
end

response = Wanikani::Subject.find_all
@subjects = response.data

By default, the gem uses the API version 2 with revision 20170710.

Check if an API key is valid

require 'wanikani'

# Using an invalid API Key:
@client = Wanikani::Client.new(api_key: "INVALID_API_KEY")
@client.valid_api_key?
  # => false

# Using a valid API key:
@client = Wanikani::Client.new(api_key: "VALID_API_KEY")
@client.valid_api_key?
  # => true

# Alternatively, you can check the validity of any
# API key without setting up a client:
Wanikani::Client.valid_api_key?("VALID_API_KEY")
  # => true

Endpoints

The gem supports all endpoints documented in WaniKani's API.

Example: User Information

Some endpoints like User, Summary and SrsStages return only a single object.

require 'wanikani'

response = Wanikani::User.fetch
# Response storing the meta data of the response.
# To access the payload, access the field `data`. It'll return a Hash

@user = response.data
  # => { "id": "5a6a5234-a392-4a87-8f3f-33342afe8a42", "username": "crabigator", "level": 25, "profile_url": "https://www.wanikani.com/users/crabigator", "started_at": "2012-05-11T00:52:18.958466Z", "current_vacation_started_at": null, "subscription": { "active": true, "type": "recurring", "max_level_granted": 60, "period_ends_at": "2018-12-11T13:32:19.485748Z" }, "preferences": { "default_voice_actor_id": 1, "lessons_autoplay_audio": false, "lessons_batch_size": 5, "lessons_presentation_order": "ascending_level_then_subject", "reviews_autoplay_audio": false, "reviews_display_srs_indicator": true } }

Example: Subjects

Most endpoints can return either a specified object or a collection of objects.

require 'wanikani'

response = Wanikani::Subject.find_all

# or filter by giving a parameter
response = Wanikani::Subject.find_by(hidden: false)

# Response storing the meta data of the response.
# To access the payload, access the field `data`. It'll return an Array for collections

response.type
  # => 'collection'

@subjects = response.data
  # => [ { "id": 440, "object": "kanji", "url": "https://api.wanikani.com/v2/subjects/440", "data_updated_at": "2018-03-29T23:14:30.805034Z", "data": {  "created_at": "2012-02-27T19:55:19.000000Z",  "level": 1,  "slug": "一",  "hidden_at": null,  "document_url": "https://www.wanikani.com/kanji/%E4%B8%80",  "characters": "一",  "meanings": [  {  "meaning": "One",  "primary": true,  "accepted_answer": true  }  ],  "readings": [  {  "type": "onyomi",  "primary": true,  "accepted_answer": true,  "reading": "いち"  },  {  "type": "kunyomi",  "primary": false,  "accepted_answer": false,  "reading": "ひと"  },  {  "type": "nanori",  "primary": false,  "accepted_answer": false,  "reading": "かず"  }  ],  "component_subject_ids": [  1  ],  "amalgamation_subject_ids": [  56,  88,  91  ],  "visually_similar_subject_ids": [],  "meaning_mnemonic": "Lying on the <radical>ground</radical> is something that looks just like the ground, the number <kanji>One</kanji>. Why is this One lying down? It's been shot by the number two. It's lying there, bleeding out and dying. The number One doesn't have long to live.",  "meaning_hint": "To remember the meaning of <kanji>One</kanji>, imagine yourself there at the scene of the crime. You grab <kanji>One</kanji> in your arms, trying to prop it up, trying to hear its last words. Instead, it just splatters some blood on your face. \"Who did this to you?\" you ask. The number One points weakly, and you see number Two running off into an alleyway. He's always been jealous of number One and knows he can be number one now that he's taken the real number one out.",  "reading_mnemonic": "As you're sitting there next to <kanji>One</kanji>, holding him up, you start feeling a weird sensation all over your skin. From the wound comes a fine powder (obviously coming from the special bullet used to kill One) that causes the person it touches to get extremely <reading>itchy</reading> (いち)",  "reading_hint": "Make sure you feel the ridiculously <reading>itchy</reading> sensation covering your body. It climbs from your hands, where you're holding the number <kanji>One</kanji> up, and then goes through your arms, crawls up your neck, goes down your body, and then covers everything. It becomes uncontrollable, and you're scratching everywhere, writhing on the ground. It's so itchy that it's the most painful thing you've ever experienced (you should imagine this vividly, so you remember the reading of this kanji).",  "lesson_position": 2 } } ]

Or if you want to access a single object.

require 'wanikani'

response = Wanikani::Subject.find(440)

# Response storing the meta data of the response.
# To access the payload, access the field `data`. It'll return a Hash

response.type
  # => 'kanji'

@kanji = response.data
  # => {  "created_at": "2012-02-27T19:55:19.000000Z",  "level": 1,  "slug": "一",  "hidden_at": null,  "document_url": "https://www.wanikani.com/kanji/%E4%B8%80",  "characters": "一",  "meanings": [  {  "meaning": "One",  "primary": true,  "accepted_answer": true  }  ],  "readings": [  {  "type": "onyomi",  "primary": true,  "accepted_answer": true,  "reading": "いち"  },  {  "type": "kunyomi",  "primary": false,  "accepted_answer": false,  "reading": "ひと"  },  {  "type": "nanori",  "primary": false,  "accepted_answer": false,  "reading": "かず"  }  ],  "component_subject_ids": [  1  ],  "amalgamation_subject_ids": [  56,  88,  91  ],  "visually_similar_subject_ids": [],  "meaning_mnemonic": "Lying on the <radical>ground</radical> is something that looks just like the ground, the number <kanji>One</kanji>. Why is this One lying down? It's been shot by the number two. It's lying there, bleeding out and dying. The number One doesn't have long to live.",  "meaning_hint": "To remember the meaning of <kanji>One</kanji>, imagine yourself there at the scene of the crime. You grab <kanji>One</kanji> in your arms, trying to prop it up, trying to hear its last words. Instead, it just splatters some blood on your face. \"Who did this to you?\" you ask. The number One points weakly, and you see number Two running off into an alleyway. He's always been jealous of number One and knows he can be number one now that he's taken the real number one out.",  "reading_mnemonic": "As you're sitting there next to <kanji>One</kanji>, holding him up, you start feeling a weird sensation all over your skin. From the wound comes a fine powder (obviously coming from the special bullet used to kill One) that causes the person it touches to get extremely <reading>itchy</reading> (いち)",  "reading_hint": "Make sure you feel the ridiculously <reading>itchy</reading> sensation covering your body. It climbs from your hands, where you're holding the number <kanji>One</kanji> up, and then goes through your arms, crawls up your neck, goes down your body, and then covers everything. It becomes uncontrollable, and you're scratching everywhere, writhing on the ground. It's so itchy that it's the most painful thing you've ever experienced (you should imagine this vividly, so you remember the reading of this kanji).",  "lesson_position": 2 }

Endpoints returning collections may have limits to the number of elements they return. The API supports access via pagination, however this needs to be implemented outside of the gem.

Please see the Wanikani's API for more details.

Handling API Request Exceptions

The gem will handle API request exceptions with the following exception classes:

• Wanikani::InvalidKey: The API response will return a 401 status code indicating that the API key used is not valid. The gem will throw this exception so you can catch errors where the API key is not valid.
• Wanikani::Exception: Any API responses with a non-successful (20x) status code or with an error key in the body will throw this exception, including additional information on the status code (if not a 20x status code) or the message in the body (if the error key is present in the response).

API Version 1

Support for Wanikani API version 1 has been removed in Version 3.0 of this gem. The API has been shut down in September 2020 and is no longer accessible.

Contributing

I'll be super-happy if you guys help giving back! If you want to do some hacking on the WaniKani gem, this is a good guideline to get started:

• Fork the repo on GitHub
• Create a branch on your clone that will contain your changes
• Hack away on your branch
• Add tests in the /spec directory relating to your changes
• Make sure all specs still pass
• If you're adding new functionality, make sure to update README.md
• Push the branch to GitHub
• Send me a pull request for your branch