[Scriptable] iOS Wanikani Leeches Widget

If you already know what leeches are, and you already know what Scriptable is, then you can go ahead and grab the script from here. I think it should be fairly self explanatory to anyone whose added an iOS widget using Scriptable before.

Latest Update: September 30, 2021

Changed to use the new Shin Wanikani Leech Trainer API, and switched from scraping to using the official API. This should make it more reliable overall, as well as potentially solve the problem that some people were having where the shown item did not match the shown meaning.

What Are Leeches?

The term “leech” comes from Anki. Or at least I think it does. Either way, the Anki manual has a good explanation of what they are. In short, leeches are radicals, kanji and vocabulary that for whatever reason you just can’t seem to remember. They’re the ones that you fail over and over again.

In Anki, there are various ways of dealing with this. For example, you can opt to suspend leeches automatically so that they don’t get in the way of your progress.

In Wanikani, we have no choice but to squash (learn) those leeches.

Towards that effort (and also because I wanted a Wanikani related widget on my home screen) I threw together a widget that displays leeches so that you can be reminded of them every time you look at your phone.

What Is Scriptable?

Scriptable is an automation app for iOS. It lets you write JavaScript scripts that interact with native features of iOS. You can also use it to create home screen widgets using JavaScript.

Getting Started

There are two ways to you can go about installing the script: Downloading it, or copy/pasting it. Choose the way that is easier for you.

Install By Downloading To iCloud

First install the Scriptable app. Open it so that it will create a folder within your iCloud folder.

From there, download this JavaScript file and place it inside iCloud Drive > Scriptable.

After it is downloaded, you should be able to see it from within the Scriptable app on the Scripts tab.

Install By Copy/Pasting Into The App

If the download method failed for some reason, you can copy and paste the script directly into the app. Just open this JavaScript file and copy the contents. Open the Scriptable app, click on the icon on the top right corner, and then paste the contents of the script.

After it is copied, you should be able to see it from within the Scriptable app on the Scripts tab. You will need to manually change the name of the script (by default it will be “Untitled Script”).

Adding The Widget

Add the Scriptable widget just like you would any other widget. When the widget is initially added to the home screen it will say “Select script in widget configuration.” While the home screen is still in edit mode, click on the widget again to bring up the widget configuration dialog.

You’ll see three options that you can set: “Script,” “When Interacting,” and “Parameter.” Click on “Script” and select the name of the Wanikani Leech widget script. If you followed the download method above, it will probably be called “Wanikani Leeches.”

In the “Parameter” field, add your Wanikani API token.

And after that you should be set!

Here is a video example in case that was hard to follow.

ezgif.com-gif-maker (1)

How It Works

The leeches are being pulled from the API used by the Shin Wanikani Leech Trainer Userscript by Ross Hendry. From there I hit the official Wanikani API to grab details about the items.

Known Issues

  • In situations of low internet connectivity, it will often display as “Oops, something went wrong.”

FYI Wanikani has a native API to get to the data. You may consider using this instead.


I am not sure how relevant this is in the context of IOS but there is a framework that simplifies the use of the WK API.

1 Like

is there one similar for android?

I deleted my response because I realized I didn’t respond specifically to your comment about scraping: For the official Wanikani API, you can’t look up subjects by, for example, “vocab/仲間”. Or at the very least I haven’t found a way to do it. You need to look them up by their subject IDs.

It would still be doable, but in order for me to do it that way, I would need to either find a master list of subject IDs so I could look up individual items that I get from the Leech API, or I would need to ditch the Leech API and calculate the leeches myself by fetching reviews from the offical API.

Also, unfortunately, the Wanikani Open Framework only works for userscripts.

But thanks for the suggestions!

If I have time in the future I certainly might come back and redo this using the official API. At this time though the API that the Shin Wanikani Leech Trainer uses was enough for me.

Not that I’m aware of.

You could probably make something similar using KWGT, but that’s not free, and you can’t execute scripts with it (as far as I know). You certainly couldn’t copy/paste this script directly and use it there. I think you would need to do the scraping/leech calculating on your own server or lamba endpoint, and then let KWGT access it as an API.

You can also look them up by their slugs, The slug of an item is its Japanese unicode characters for kanji and vocabulary items and the English name for radicals.

1 Like

No, it doesn’t. I don’t think that’s too much of an issue, as the radical names aren’t that important in the whole scheme of things (several of them being WK original creations after all). So, just getting vocab and kanji leeches seems quite enough.

Brittle or not, this is a noice piece of work! :durtle_noice:

The api doesn’t return radicals, I’m afraid. If you’re needing more info returned from it then I can do that. Updating the API keeps getting put on the back burner, but if I’m just adding things to the backend rather than both back and front then surely I can get to it faster!

Is it just readings and meanings that you want to get back?

Great concept but may still have some bugs. Here it seems to be showing the wrong kanji, although a very similar looking one.

1 Like

You can also look them up by their slugs

Thank you! I searched for how to do that but somehow missed it.


I had that happen once too.

I’ve also been having problems with it showing “Oops! Something went wrong…” a lot when I’m in areas with bad internet connectivity.

I’ll look into it when I have time.

1 Like

Woah. Hello! Yeah, just readings and meanings would be fantastic. If it returned both I could do all this with one request and no scrapping.

Thanks. Gonna be looking forward to the updates. This has already already helped me out with a few leeches.

It’ll be on the new API, rather than the current one, if that’s okay? Also, are you wanting it just for the request for lessons, rather than the full leech list?

Thanks for doing this! Nice to know that if I can supply the API then you can build something on it faster than me!

Which is the new API? To be honest I’m only familiar with this: https://wk-stats.herokuapp.com/leeches/lesson?api_key= which is the endpoint used when requesting lessons.

But basically all I want/need is a list of leeches I can loop through at random to display one to the user.

I’d never heard of scriptable before. Very, very interesting. Thanks!

I’m firmly in the “if you see a leech enough times you’ll eventually recognize and fix the underlying problem on your own” camp. I don’t find targeted leech training all that useful, but I love the idea of adding some WK-oriented javascript widgets to my phone.


There’s a slow rewrite underway, where I’m writing the code myself rather than the older version I took over. It’s a messy URL for now, but the lessons can be retrieved from this: https://wk-leeches-dev.pun7u6s23ol8m.eu-west-2.cs.amazonlightsail.com/leeches/lesson

The authorization has changed a little, now you need to bass the token in a header. So, an Authorization header with a value of Bearer <token goes here>.

1 Like

I just gave it a shot on Postman, and while it tells me my leech_count, too_soon_count, too_recent_count and trained_count, the lessons array is empty.

Here’s a screenshot of what it is returning with the new API.

And here’s what it was returning with the old API.

Both are using the same token.
Do I need to do something in particular to get the lessons?

Or would there be a better endpoint to hit to get leeches to loop through?
I’m not sure what API endpoints are available.

Oh, crap. I think there’s a bug when a new user hits the API. Damn. If you take the /lesson off the end of the URL then it should return everything.

I’ll try and add some documentation and fix that bug soon.

1 Like

So, if I hit the leeches endpoint I’m getting a list of all my leeches. If I hit the leeches/lesson endpoint again it is still showing up empty.