unofficial-jisho-api

Install the module in your Node.js project using npm:

npm install unofficial-jisho-api

Use searchForExamples(query) to find example sentences containing a specific term. The result includes the kanji version, kana version, English translation, and a pieces array containing the breakdown of the sentence.

import JishoAPI from 'unofficial-jisho-api';

const jisho = new JishoAPI();

jisho.searchForExamples('日').then(result => {
  for (let i = 0; i < result.results.length; ++i) {
    let example = result.results[i];
    console.log(example.kanji);
    console.log(example.kana);
    console.log(example.english);
  }
});

Use searchForPhrase(phrase) to retrieve results from the official Jisho.org API. This is the most stable method as it does not rely on HTML scraping. It returns results identical to the official API.

import JishoAPI from 'unofficial-jisho-api';

const jisho = new JishoAPI();

jisho.searchForPhrase('日').then(result => {
  console.log(result);
});

Use searchForKanji(kanji) to get detailed information about a specific kanji. This method scrapes Jisho.org and returns properties such as JLPT level, stroke count, meaning, readings (kunyomi/onyomi), and URIs for stroke order diagrams (SVG, GIF, and PNG).

import JishoAPI from 'unofficial-jisho-api';

const jisho = new JishoAPI();

jisho.searchForKanji('語').then(result => {
  console.log('Found: ' + result.found);
  console.log('JLPT level: ' + result.jlptLevel);
  console.log('Meaning: ' + result.meaning);
  // ... other properties
});

Use scrapeForPhrase(phrase) to get data that the official API might not provide, such as JLPT levels and part-of-speech tags.

Warning: This method relies on HTML scraping and may break if Jisho.org updates its website structure.

import JishoAPI from 'unofficial-jisho-api';

const jisho = new JishoAPI();

jisho.scrapeForPhrase('谷').then((data) => {
  console.log(JSON.stringify(data, null, 2));
});

Use searchForExamples(phrase) to scrape example sentences containing a specific word or phrase from https://jisho.org/search/{phrase}%23sentences.

Returns an ExampleResults object containing:

• query: The searched phrase.
• found: Boolean indicating if results were found.
• uri: The Jisho URL for the search.
• results: Array of ExampleResultData objects. Each result includes:
  • kanji: The sentence including kanji.
  • kana: The sentence in kana (furigana where available).
  • english: English translation.
  • pieces: Array of ExampleSentencePiece (the unlifted baseline text and lifted furigana text).

const examples = await jisho.searchForExamples('食べる');
examples.results.forEach(res => {
  console.log(res.english);
  console.log(res.kanji);
});

Use searchForPhrase(phrase, page) to query the official Jisho.org API. This is the preferred method for basic word/phrase searches. The response format is the raw data returned by the official API, which is complex and not explicitly documented by this library.

• phrase: The search term.
• page (optional): The page number to retrieve.

const results = await jisho.searchForPhrase('keyword', 1);

Use scrapeForPhrase(phrase) to retrieve enriched data by scraping https://jisho.org/word/{phrase}. This method provides metadata unavailable in the official API, such as part-of-speech tags, JLPT levels, and audio files.

Returns a PhrasePageScrapeResult object containing:

• found: Boolean indicating if the term exists.
• query: The searched term.
• uri: The Jisho URL for the word.
• tags: Array of tags associated with the result.
• meanings: Array of PhraseScrapeMeaning objects (definitions, sentences, etc.).
• otherForms: Array of PhraseScrapeJapaneseWord objects (alternative kanji/kana forms).
• audio: Array of AudioFile objects (URI and mimetype).
• notes: Array of strings containing additional notes.

const details = await jisho.scrapeForPhrase('掛かる');
if (details.found) {
  console.log(details.meanings[0].definition);
}

Use searchForKanji(kanji) to scrape detailed information about a specific kanji character.

Returns a KanjiResult object containing:

• found: Boolean indicating if the kanji was found.
• query: The kanji searched.
• taughtIn: School level.
• jlptLevel: JLPT level (e.g., 'N5').
• newspaperFrequencyRank: Frequency rank.
• strokeCount: Number of strokes.
• meaning: The kanji's meaning.
• kunyomi / onyomi: Arrays of readings and their examples.
• radical: Object containing symbol, forms, and meaning of the radical.
• parts: Array of parts used in the kanji.
• strokeOrderDiagramUri: URL to a step-by-step diagram.
• strokeOrderSvgUri: URL to an SVG diagram.
• strokeOrderGifUri: URL to a GIF animation.

const kanji = await jisho.searchForKanji('学');
console.log(kanji.jlptLevel); // e.g., 'N5'

The data structure for individual example sentences returned by searchForExamples().

/**
 * @typedef {Object} ExampleResultData
 * @property {string} kanji The example sentence including kanji.
 * @property {string} kana The example sentence without kanji (only kana).
 * @property {string} english An English translation of the example.
 * @property {Array.<ExampleSentencePiece>} pieces The lifted/unlifted pairs.
 */