API V2 Beta Documentation


Hehe, I’m looking forward to it :smile:


Pretty much what @rfindley said. The updated_after filter is the key to success for all the queries. Subsequent request should be small and infrequent. People do a lot of reviews, but only in human terms. For the API, those are small, quick requests.

The initial load is what it is — you’ll have to make a bunch of requests to grab the data for a user. Because of the cursor based pagination and a (frustrating) SSL-based increase in request time, you’ll probably be under the rate limit even if you’re hammering away at it. That is, unless you’re doing the load for a bunch of users at the same time, in parallel. Then you’ll need to make sure you accommodate those limits.


Let us know when you think that’s going to happen so we can keep an eye on things. We think the rate limits should keep everything happy, and I’ve been doing some performance tweaks lately, but, you know, best laid plans and all that. :wink:


Yep, will do :slight_smile:


How close are you guys to going into a beta?


Pretty close. I’ll hedge my bets and not say anything specific about timing, but we’re close.

We’re happy on the technical side with structure and performance. We’re working on documentation. We’re also working on some updates to our terms to make sure the use of API data is explicitly called out — it’s nothing restrictive or even new, really, but we want to be super clear with everyone.

We’re working on some additional endpoints, but we’re not going to hold up the beta for those.


Hi, I’m currently working on a little project that requires a type of query present in the older api.

which is meerly level progression
which returns the necessary information of
"radicals_progress": 22, "radicals_total": 22, "kanji_progress": 33, "kanji_total": 33

Is there an easy way to do this with the new api. I’m quite stumped.
As the way I was thinking was to get the assignments for the level and then count them based on passed or not, but since a user does not have access to not unlocked data this wont work. The next scenario means I will have the query the server many times to get the kanji and radicals, then get the assignments, then compare to the two, seems a bit overkill and i think there’s a better way i’m not seeing.

Thanks in advanced.


I think you just need two queries: /subjects with a level filter, and /assignments with a level filter. Then count by item type (and passed / not passed) in the returned results of each.

Of course, the number of items on WK doesn’t change that often. You could hard-code an array of item-type count for each level. But I guess you’d still need the /subjects data to see the item-type of each assignment.

I’m assuming you’re not doing this as an on-site userscript?


I think the hard coding thing is a good idea.
Your suggestion I thought the same however as state in the ‘docs’ if a user doesn’t have an item unlocked (including ones inside ones level) they cant even have access to its statistics.
This results in me checking for “passed” and “not passed” on the data I do have (the unlocked stuff) and I guess marking the data as not passed.

Current thinking.

  1. grab all the level data with /subjects with level filter (and count) or use hard-coded numbers for levels (gotta search that up)
  2. use /assignments with a level filter, check subject type and count number of passed. (guess it doesn’t matter if the user doesn’t have the data since it counts as not passed anyway)

I’m building vue front end and firebase database backend to store the data (and not kill the servers with queries unless necessary). Not keeping the data I take would easily hit the limit of refreshes if many people use it at once. Thats bad!


I keep a copy of the hard-coded numbers in the wkstats.com code. It’s at the top:

If you cache the /subjects data, then you don’t need to hard-code the count-per-level. I’m planning to do that for the stats site eventually, and all of my userscripts will be doing that through the Open Framework.


@viet さん、 sorry if I missed something from the docs, but is it possible to retrieve example sentences for an item from the API?


Example sentences aren’t in there yet, but…

I know that at least part of the “things we need to have in place first” was the license / terms of use.


Thank you! Sorry for missing that. I was planning to parse the HTML to grab the sentences from each item, but doing an API call is a cleaner and more efficient way. Have they provided any timeline yet?


Nope, no timeline yet.

When you say ‘parse the html’… do you mean on-the-fly, or as a one-time thing for an external project?


I’ve just started using sentences to study Kanji and vocabulary and the one’s provided by WaniKani are a great source for sentence mining. I found myself doing the same thing over and over again and though it would be nice to have a script to get sentences from the API to create Anki cards (or store them inside a CSV file to use them later). Because it’s not possible to do it with the API, the best thing would be to parse the HTML and extract the content. It doesn’t look like a difficult thing to do. All sentences are wrapped inside a .context-sentence-group element, I think. So yeah, it would be a user/shell script connected to the API. Is there anything similar already?


Yeah, that’s exactly what I did: a set of scripts to fetch and extract all of the info from the item pages, which then gets stored in an sqlite database. I ran an update last week to gather the audio file links, then realized the URLs could be generated from just the item ID in the API. But anyway, all of the sentences were updated in the process.


What’s the difference between the API and the https://www.wanikani.com/json endpoint? I can see the endpoint already returns sentences:

    "stroke": 51,
    "meaning_explanation": "The [kanji]point[/kanji] at which something starts to [kanji]boil[/kanji] is the [vocabulary]boiling point[/vocabulary].",
    "reading_explanation": "This is a jukugo word that uses the on'yomi readings of the kanji. You should be able to read this on your own.",
    "en": "Boiling Point",
    "kana": "ふってん",
    "sentences": [
            "How many degrees is the boiling point?"


/json is for internal use.


I’ve been running some tests with Postman and it seems I can get a response from that endpoint by sending the remember_user_token parameter on the Cookie header. I also haven’t seen any rate limiting response and I could run more than 60 calls per minute. Is that okay? Is it “legal” to call that endpoint?


Internal likely means that there are no promises. They could change the internal API at any point without notice, so you rely on it at your own risk.