R Interface to the WaniKani API • rwanikani

R interface to the WaniKani API v2 for accessing Japanese learning data.

Overview

rwanikani provides a comprehensive R interface to the WaniKani API v2. WaniKani is a popular spaced repetition system for learning Japanese kanji, vocabulary, and radicals. This package allows you to programmatically access your learning data, progress statistics, and study materials.

Installation

You can install the development version of rwanikani from GitHub:

devtools::install_github("jonocarroll/rwanikani")

Getting Started

Authentication

First, you need to get your WaniKani API token:

Log in to your WaniKani account
Go to Settings > API Tokens
Generate a new API token
Set it in R:

library(rwanikani)

# Set your API key
wk_set_api_key("your-api-token-here")

# Or set as environment variable (recommended)
Sys.setenv(WANIKANI_API_KEY = "your-api-token-here")
wk_set_api_key()

# Preferably defined in your `.Renviron` file

Basic Usage

# Get user information
user_info <- wk_user()
cat("Level:", user_info$level, "\n")
#> Level: 8

# Get subjects for current level
subjects <- wk_subjects(levels = user_info$level)
cat("Subjects at current level:", length(subjects$data), "\n")
#> Subjects at current level: 180

Main Functions

Function	Description
`wk_user()`	Get user account information
`wk_subjects()`	Get subjects (radicals, kanji, vocabulary)
`wk_assignments()`	Get assignment progress data
`wk_reviews()`	Get review history
`wk_review_statistics()`	Get review performance statistics
`wk_study_materials()`	Get personal notes and synonyms
`wk_level_progressions()`	Get level progression history
`wk_resets()`	Get level reset history
`wk_get_mistakes()`	Get subjects with lowest accuracy percentages
`wk_print_mistakes()`	Print formatted summary of subjects needing practice
`wk_format_review_statistics()`	Format raw review statistics into readable data frame
`wk_print_review_stats_summary()`	Print comprehensive review statistics summary
`wk_format_level_progressions()`	Format raw level progressions with timing calculations
`wk_print_level_progression_summary()`	Print comprehensive level progression summary with statistics

Kanji Analysis Functions

Function	Description
`wk_get_kanji_table()`	Extract formatted table of kanji with similarity data
`wk_extract_kanji()`	Process kanji subjects into structured data
`wk_resolve_similarity_details()`	Resolve similarity IDs to kanji characters and meanings
`wk_add_similarity()`	Add custom similarity mappings to kanji data
`wk_kanji_network()`	Create interactive network diagrams of kanji similarity
`wk_create_character_card()`	Generate HTML cards for WaniKani characters

Caching Functions

Function	Description
`wk_load_subjects_cache()`	Load subjects data from local cache or API
`wk_clear_subjects_cache()`	Clear cached subjects data
`wk_cache_info()`	Get information about current cache status

Features

Complete API Coverage: Access all WaniKani API v2 endpoints
Flexible Filtering: Filter data by levels, types, dates, and more
Pagination Support: Automatically handle paginated responses
Environment Variable Support: Secure API key management
Comprehensive Tests: Full test coverage with mocked API responses
Detailed Documentation: Extensive help pages and vignettes

Advanced Usage

Get All Subjects with Filtering

# Get all kanji from levels 1-10
kanji <- wk_subjects(
  types = "kanji",
  levels = 1:10,
  all_pages = TRUE
)

# Get subjects updated in the last week
recent_subjects <- wk_subjects(
  updated_after = Sys.time() - 7*24*60*60,
  all_pages = TRUE
)

Analyze Review Performance

# Get 5 subjects with lowest accuracy (most mistakes)
wk_print_mistakes(5)
#> ℹ Fetching review statistics...
#> ℹ Loading subjects data from cache
#> ℹ Processing 1194 review statistics...
#> ✔ Found 5 subjects with lowest accuracy
#> === Subjects That Need More Practice ===
#> 
#> 1. 向こう (Over There, Opposite Side, Other Side, Far Away) - Meaning: 67% [Level 8 Vocabulary]
#> 2. 全く (Completely, Entirely, Truly, Really, Wholly) - Meaning: 67% [Level 8 Vocabulary]
#> 3. この前 (The Other Day, Recently, In Front of This) - Meaning: 67% [Level 8 Vocabulary]
#> 4. 者 (Someone, Somebody) - Meaning: 69% [Level 8 Kanji]
#> 5. 行う (To Carry Something Out, To Perform Something) - Meaning: 70% [Level 6 Vocabulary]

# Get subjects with accuracy below a specific threshold
bad_subjects <- wk_get_mistakes(20, percentage_threshold = 70)
#> ℹ Fetching review statistics...
#> ℹ Loading subjects data from cache
#> ℹ Processing 4 review statistics...
#> ✔ Found 4 subjects with lowest accuracy
bad_subjects[, c("characters", "meaning_percentage")]
#>   characters meaning_percentage
#> 2     向こう                 67
#> 3       全く                 67
#> 4     この前                 67
#> 1         者                 69

# Print comprehensive review statistics summary
wk_print_review_stats_summary(wk_review_statistics(), n = 10)
#> ℹ Formatting 500 review statistics...
#> ℹ Loading subjects data from cache
#> ✔ Formatted 500 review statistics
#> === Review Statistics Summary ===
#> 
#> Total subjects with reviews: 500 
#> Average meaning accuracy: 91.9% 
#> Average reading accuracy: 89.4% 
#> 
#> Meaning Accuracy Distribution:
#>   0-50%: 0 subjects
#>   51-70%: 0 subjects
#>   71-80%: 46 subjects
#>   81-90%: 161 subjects
#>   91-100%: 293 subjects
#> 
#> Subjects That Need Most Practice:
#>   1. 出 (Exit) - 72% [Level 2 Kanji]
#>   2. 少女 (Girl, Young Girl) - 72% [Level 3 Vocabulary]
#>   3. 年中 (Year Round, All Year, Whole Year, Throughout The Year) - 72% [Level 4 Vocabulary]
#>   4. 去年 (Last Year) - 72% [Level 4 Vocabulary]
#>   5. 村人 (Villager) - 75% [Level 4 Vocabulary]
#>   6. 正 (Correct) - 76% [Level 2 Kanji]
#>   7. 左右 (Left And Right, Both Ways, Influence, Control) - 76% [Level 2 Vocabulary]
#>   8. 少 (Few, A Little) - 76% [Level 3 Kanji]
#>   9. 去 (Past) - 76% [Level 4 Kanji]
#>   10. 町 (Town) - 76% [Level 4 Kanji]

Track Level Progress

# Get and display level progression summary
wk_print_level_progression_summary(wk_level_progressions(all_pages = TRUE))
#> ℹ Formatting 8 level progressions...
#> ✔ Formatted 8 level progressions
#> === Level Progression Summary ===
#> 
#> Total levels tracked: 8 
#> Levels completed: 0 
#> Levels passed (not completed): 7 
#> Levels in progress: 1 
#> 
#> Passing Time Statistics:
#>   Average days to pass: 25.5 
#>   Median days to pass: 21.2 
#>   Fastest level passed: 10.1 days
#>   Slowest level passed: 48.6 days
#> 
#> Individual Level Progress:
#>    Level 1 - passed in 13 days 
#>    Level 2 - passed in 10.1 days 
#>    Level 3 - passed in 24 days 
#>    Level 4 - passed in 21.2 days 
#>    Level 5 - passed in 13.7 days 
#>    Level 6 - passed in 47.8 days 
#>    Level 7 - passed in 48.6 days 
#>    Level 8 - in progress

Extract Kanji with Similarity Data

# Get subjects data for similarity resolution
subjects <- wk_load_subjects_cache(levels = 1:20, types = "kanji")
#> ℹ Loading subjects data from cache
kanji_table <- wk_get_kanji_table(levels = 1:20, include_similarity = TRUE)
#> ℹ Loading subjects data from cache
#> ℹ Processing 707 kanji subjects...

# Resolve similarity IDs to show kanji and meanings
kanji_resolved <- wk_resolve_similarity_details(kanji_table, subjects$data, format = "kanji_meaning")
kanji_resolved[67:74, c("kanji", "meanings", "similar_resolved")]
#>    kanji meanings                               similar_resolved
#> 67    水    Water 泳 (Swim), 球 (Sphere), 氷 (Ice), 求 (Request)
#> 68    火     Fire                                               
#> 69    犬      Dog                             太 (Fat), 大 (Big)
#> 70    王     King             主 (Master), 注 (Pour), 住 (Dwell)
#> 71    出     Exit                                               
#> 72    右    Right             左 (Left), 石 (Stone), 友 (Friend)
#> 73    四     Four                              匹 (Small Animal)
#> 74    左     Left                         石 (Stone), 右 (Right)

Visualise Similar Kanji

# Create interactive network visualization centered on a kanji
wk_kanji_network(kanji_resolved, center_kanji = "水", 
                 max_depth = 5, interactive = TRUE)

Display Character Details

# Generate HTML card for a character (displays like WaniKani website)
wk_create_character_card("水", view = TRUE)
wk_create_character_card("氷", view = TRUE)

API Rate Limits

The WaniKani API has a rate limit of 60 requests per minute. Be mindful of this when making many requests, especially when using all_pages = TRUE.

This package utilises a cache of the kanji data to avoid frequently requesting it. This cache can be reset manually with a reload=TRUE argument to most functions.

Documentation

See vignette("getting-started") for a comprehensive tutorial
Use ?function_name for detailed help on specific functions
Visit the WaniKani API documentation for API details

Contributing

Please report bugs and request features on GitHub Issues.

License

MIT License