API V2 Beta Documentation

Yalmar · January 27, 2019, 7:09am

Thank you!

Yalmar · January 31, 2019, 8:46pm

I’m playing around with the API V2 but I got stuck and I wonder if someone has a suggestion.

The following command succeeds from bash:

curl "https://api.wanikani.com/v2/study_materials?level=1" \
  -H "Wanikani-Revision: 20170710" \
  -H "Authorization: Bearer <MY_API_V2_ID>"

I then try to load it in a google sheet in tabular form.
I set A1 to =IMPORTJSON(“https://api.wanikani.com/v2/study_materials?level=1” -H “Wanikani-Revision: 20170710” -H “Authorization: Bearer <MY_API_V2_ID>”)
but I get an “Error Formula parse error.”

I used to do something similar with the API V1 and a google sheet a couple of years ago, but memory doesn’t serve me right

Does any of you have some suggestions please?

rfindley · January 31, 2019, 10:02pm

On your spreadsheet, go to [Tools->Script Editor]

Add the following function to the code window (and save):

function WanikaniApi(url) {
  var params = {
    headers: {
      "Authorization": "Bearer <your_apiv2_key>",
      "Wanikani-Revision": "20170710"
    }
  };
  
  return UrlFetchApp.fetch(url, params).getContentText();
}

Then add this to your cell:

=WanikaniAPI("https://api.wanikani.com/v2/study_materials?levels=1")

viet · January 31, 2019, 10:25pm

Want to point out to use levels instead of level

rfindley · January 31, 2019, 10:30pm

Thanks! I’ve updated it.

Is it also supposed to have levels[]=1 ?
I haven’t used the parameters (I think)…

viet · January 31, 2019, 10:33pm

The API used to take in param arrays, but we converted over to delimited comma a while back based on feedback.

For singular level request levels=1 and for multiple levels=1,2,3.

rfindley · January 31, 2019, 11:12pm

I hadn’t played with Google Spreadsheets’ scripting ability much, so this is interesting (and it’s how I learn!).
I took a moment to put together a usesful demo, rather than just putting raw API JSON in a cell:

var apiv2_key = 'your_apiv2_key';
var base_url = 'https://api.wanikani.com/v2/';

function WkApi(endpoint) {
  var params = {
    headers: {
      'Authorization': 'Bearer ' + apiv2_key,
      'Wanikani-Revision': "20170710"
    }
  };

  // Return the raw json object.
  return JSON.parse(UrlFetchApp.fetch(base_url + endpoint, params).getContentText());
}

function WkSubjects(level) {
  var json = WkApi('/subjects?levels='+level);

  // Turn the JSON content into a 2D array:
  // [[level, slug], [level, slug], ... ]
  return json.data.map(function(item){
    return [item.data.level, item.data.slug];
  });
}

and formula:

=WkSubjects("1,2")

Result:

ctmf · January 31, 2019, 11:23pm

Ohhhh, that looks handy. I’m not much of a programmer but I can DO some spreadsheet data nerdery.

Yalmar · February 1, 2019, 5:38am

Thank you @rfindley and @viet . I’m going to try your suggestions this weekend !

Yalmar · February 2, 2019, 3:21am

I’ve just had time to play with this and everything is working well. Thank you.

Yalmar · February 2, 2019, 10:54am

I’ve been playing some more with Google sheets and the API V2, but I got stuck again.

I’ve got the WkSubjects function working well (thanks to @rfindley and @viet). When I set the A2 cell to =WkSubjects(“2”), I get all radicals, kanji and vocabulary for lesson 2.

var apiv2_key = '<MY_API_V2_KEY>';
var base_url = 'https://api.wanikani.com/v2/';

function WkApi(endpoint) {
  var params = {
    headers: {
      'Authorization': 'Bearer ' + apiv2_key,
      'Wanikani-Revision': "20170710"
    }
  };

  return JSON.parse(UrlFetchApp.fetch(base_url + endpoint, params).getContentText());
}

function WkSubjects(level) {
  var json = WkApi('/subjects?levels='+level);

  return json.data.map(function(item){
    return [item.data.level
          , item.data.characters
          , item.data.meanings[0].meaning
          , item.data.meaning_mnemonic
          , item.data.meaning_hint
          , item.data.reading_mnemonic
          , item.data.reading_hint];
  });
}

You see that I have used “item.data.meanings[0].meaning” that retrieve the value of the “meaning” attribute of the first object in the “meanings” array of objects.

I would like to return the value of the “meaning” attribute for all the objects in the “meanings” array of objects and concatenate them with a comma.

This is the function I came out with. I know it’s wrong, but js is not my strong suit and an hour on google didn’t help.

function WkSubjectsType(level,subject_type) {
  var json = WkApi('/subjects?levels='+level+'&subject_types='+subject_type);

  return json.data.map(function(item){
    var joined = item.data.meanings[(meanings).join(',')];

    
    return [item.data.level
          , item.data.characters
          , joined];
  });
}

Not sure if I should use a foreach loop or perhaps there is a quicker way to do it. Do you have any suggestions for me?

tombo · February 2, 2019, 5:12pm

For example


var apiv2_key = '';
var base_url = 'https://api.wanikani.com/v2/';

function WkApi(endpoint) {
  var params = {
    headers: {
      'Authorization': 'Bearer ' + apiv2_key,
      'Wanikani-Revision': "20170710"
    }
  };

  // Return the raw json object.
  return JSON.parse(UrlFetchApp.fetch(base_url + endpoint, params).getContentText());
}

function WkSubjects(level) {
  var json = WkApi('/subjects?levels='+level);
  return json.data.map(function(item){
    return [item.data.level, item.data.slug, FormatMeanings(item.data)];
  });
}

function FormatMeanings(data) {
  return data.meanings.map(function(meaning){
    return meaning.meaning;
  }).join(', ');
}

Yalmar · February 2, 2019, 6:11pm

Thank you @Tombow ! I see what you did there.
I’ve just tried this out and it works well.

Yalmar · February 4, 2019, 10:35am

I’ve stumbled across a problem I cannot solve.

If I use a command like:

curl "https://api.wanikani.com/v2/study_materials?subject_types=kanji" \
  -H "Wanikani-Revision: 20170710" \
  -H "Authorization: Bearer <my_api_v2>" \
  | python -m json.tool \
  > study_materials-kanji.txt

I get meaning_note, meaning_synonyms,reading_note
but I don’t get level, meanings, meaning_hint, meaning_mnemonic, readings, reading_hint, reading_mnemonic.

If I use a command like:

curl "https://api.wanikani.com/v2/subjects?level=1&types=kanji" \
  -H "Wanikani-Revision: 20170710" \
  -H "Authorization: Bearer <my_api_v2>" \
  | python -m json.tool \
  > subjects-types_kanji-level_1.txt

I get level, meanings, meaning_hint, meaning_mnemonic, readings, reading_hint, reading_mnemonic
but I don’t get meaning_note, meaning_synonyms,reading_note

How do I make a “union” of these two data sets?

Is there a command to get all these attributes in one go:
level
characters
meanings
meaning_hint
meaning_mnemonic
meaning_synonyms
meaning_note
readings
reading_hint
reading_mnemonic
reading_note

Or do I have to get the two data sets individually and then “join” them with js (which I wouldn’t know how to do)?

Or do I have to do something completely different?

ejplugge · February 4, 2019, 1:12pm

They are disjoint and you’ll have to merge them yourself. The subjects are the radicals, kanji and vocab, the shared data as created and offered by WK. The study materials are your own notes and synonyms that you added for yourself. Subjects are shared, study materials are private.

Yalmar · February 4, 2019, 3:27pm

Thank you @ejplugge . I hadn’t notice that difference between subjects and study materials.

I understand that this conceptual difference is necessary for a wanikani administrator who can see a 1:many relationship between subjects and study materials.

For a wanikani user however, who can only see his/her own study materials, it may create an unnecessary complication. I wonder whether the creation of a unified set that comprises both subjects and study materials may be an improvement to a typical wanikani user’s utilisation of the API.

Do you know of a guide or documentation where I could learn the steps to join these two sets? I wouldn’t quite know where to start.

rfindley · February 4, 2019, 3:56pm

It’s a pretty standard way of setting up an API for software developers, which is who the API is intended for.

But anyway, the link between the two is the subject_id field. Do your initial search in whichever table makes the most sense for whatever you’re searching for, then extract the subject_id field from those records, and look up the additional information by subject_id in the other table(s).

ejplugge · February 4, 2019, 4:09pm

From an API design standpoint, the split chosen by the devs is the cleaner, more correct one. For example, this approach will work much more nicely with caching. I fear this is just something you’ll have to deal with

I don’t know of a ready-to-use tool you can use, although they may exist. But for this kind of thing, it generally boils down to just having to write the code yourself, reading both files, going through the study materials one by one and adding them to the subjects based on the “id” field in the subject and the “subject_id” field in the study materials. You can use whatever standard data manipulation features of whatever language you want to use (JavaScript, Python, Ruby, …) and the documentation that comes with those scripting languages. Or if you want to use a spreadsheet, loading the two data sets into different tabs and combining them with a couple of smart formulas/pivots should also work.

But you’ll have to know how to use those languages/tools, otherwise you’ll get stuck quickly, I’m afraid.

Yalmar · February 4, 2019, 10:11pm

Thank you @ejplugge

At present I’m ok with reading the /subjects or /table but I have troubles with caching it into a database table in the browser. Incidentally @rfindley has just mentioned to me the Open Framework (that I didn’t know). It seems to contain what I’m missing, so I’ll start going through its documentation.

Kumirei · February 5, 2019, 1:44pm

Is there any way to find out when a user did the lesson for a specific item? I know that you can find the unlock date with API V1, and the first review with API V2, but I can find a way to tell when the lesson was actually done.