Skip to content

OpenianDevelopment/jikan-api.js

BranchesTags

Repository files navigation

Jikan API.js

A modern TypeScript wrapper for the Jikan API - the unofficial MyAnimeList API.

npm version License: MIT TypeScript

Features

  • 🎯 Full TypeScript support with comprehensive type definitions
  • 🚀 Modern ES modules - Tree-shakable and lightweight
  • 📚 Complete API coverage - All Jikan v4 anime, manga, and character endpoints
  • 🛡️ Built-in error handling - Graceful API error management
  • 🧪 Thoroughly tested - 100% test coverage
  • 📖 Extensive documentation - JSDoc comments for all methods

Installation

npm install jikan-api.js
yarn add jikan-api.js
pnpm add jikan-api.js

Quick Start

import Jikan from 'jikan-api.js';

// Initialize the client
const jikan = new Jikan();

// Get anime information
const anime = await jikan.anime.getAnimeByFullId(1);
console.log(anime.data.titles[0].title); // "Cowboy Bebop"

// Get manga information
const manga = await jikan.manga.getMangaByFullId(1);
console.log(manga.data.titles[0].title); // "Monster"

// Get character information
const character = await jikan.characters.getCharacterByFullId(1);
console.log(character.data.name); // "Spike Spiegel"

// Get recent anime recommendations
const animeRecs = await jikan.recommendations.getRecentAnimeRecommendations();
console.log(animeRecs.data[0].content); // Recommendation text

// Search for anime
const animeResults = await jikan.anime.searchAnime({ 
  q: 'Naruto', 
  type: 'TV' 
});

// Search for manga
const mangaResults = await jikan.manga.searchManga({ 
  q: 'One Piece', 
  type: 'Manga' 
});

API Reference

Constructor

new Jikan(baseUrl?: string)

Creates a new Jikan API client instance.

// Using default Jikan API URL
const jikan = new Jikan();

// Using custom base URL (for testing or proxies)
const jikan = new Jikan('https://custom-api.example.com/v4');

Anime Endpoints

Basic Information

getAnimeByFullId(id: number)

Retrieves complete anime information by MyAnimeList ID.

const anime = await jikan.anime.getAnimeByFullId(1);
console.log({
  title: anime.data.titles[0].title,
  score: anime.data.score,
  episodes: anime.data.episodes,
  status: anime.data.status
});
searchAnime(params?: SearchParams)

Search for anime with various filters.

// Basic search
const results = await jikan.anime.searchAnime({ q: 'Attack on Titan' });

// Advanced search with filters
const filteredResults = await jikan.anime.searchAnime({
  q: 'Demon Slayer',
  type: 'TV',
  status: 'Finished Airing',
  min_score: 8.0,
  order_by: 'score',
  sort: 'desc',
  limit: 10
});

Search Parameters:

  • q?: string - Search query
  • type?: string - Anime type (TV, Movie, OVA, Special, ONA, Music)
  • score?: number - Score filter
  • min_score?: number - Minimum score
  • max_score?: number - Maximum score
  • status?: string - Airing status
  • rating?: string - Age rating
  • sfw?: boolean - Safe for work filter
  • genres?: string - Comma-separated genre IDs
  • order_by?: string - Field to order by
  • sort?: string - Sort direction (asc, desc)
  • page?: number - Page number
  • limit?: number - Results per page

Characters & Staff

getAnimeCharacters(id: number)

Get character information for an anime.

const characters = await jikan.anime.getAnimeCharacters(1);
characters.data.forEach(char => {
  console.log({
    name: char.character.name,
    role: char.role,
    voiceActors: char.voice_actors.map(va => va.person.name)
  });
});
getAnimeStaff(id: number)

Get staff information for an anime.

const staff = await jikan.anime.getAnimeStaff(1);
staff.data.forEach(member => {
  console.log({
    name: member.person.name,
    positions: member.positions
  });
});

Episodes

getAnimeEpisodes(id: number, page?: number)

Get episode list for an anime.

// Get first page of episodes
const episodes = await jikan.anime.getAnimeEpisodes(1);

// Get specific page
const episodesPage2 = await jikan.anime.getAnimeEpisodes(1, 2);

episodes.data.forEach(episode => {
  console.log({
    number: episode.mal_id,
    title: episode.title,
    filler: episode.filler,
    recap: episode.recap
  });
});
getAnimeEpisodeById(id: number, episodeId: number)

Get specific episode information.

const episode = await jikan.anime.getAnimeEpisodeById(1, 1);
console.log({
  title: episode.data.title,
  synopsis: episode.data.synopsis,
  filler: episode.data.filler
});

Community Content

getAnimeNews(id: number, page?: number)

Get news articles related to an anime.

const news = await jikan.anime.getAnimeNews(1);
news.data.forEach(article => {
  console.log({
    title: article.title,
    author: article.author_username,
    date: article.date,
    excerpt: article.excerpt
  });
});
getAnimeReviews(id: number, page?: number)

Get user reviews for an anime.

const reviews = await jikan.anime.getAnimeReviews(1);
reviews.data.forEach(review => {
  console.log({
    reviewer: review.user.username,
    overallScore: review.scores.overall,
    review: review.review.substring(0, 100) + '...',
    episodesWatched: review.episodes_watched
  });
});
getAnimeForum(id: number)

Get forum topics related to an anime.

const forum = await jikan.anime.getAnimeForum(1);
forum.data.forEach(topic => {
  console.log({
    title: topic.title,
    author: topic.author_username,
    comments: topic.comments,
    lastComment: topic.last_comment?.date_posted
  });
});

Media & Content

getAnimeVideos(id: number)

Get video content (trailers, promotional videos) for an anime.

const videos = await jikan.anime.getAnimeVideos(1);
console.log({
  promoVideos: videos.data.promo.length,
  episodes: videos.data.episodes.length,
  musicVideos: videos.data.music_videos.length
});
getAnimePictures(id: number)

Get picture gallery for an anime.

const pictures = await jikan.anime.getAnimePictures(1);
pictures.data.forEach(picture => {
  console.log({
    large: picture.large_image_url,
    small: picture.small_image_url
  });
});

Statistics & Related Content

getAnimeStatistics(id: number)

Get viewing statistics for an anime.

const stats = await jikan.anime.getAnimeStatistics(1);
console.log({
  watching: stats.data.watching,
  completed: stats.data.completed,
  onHold: stats.data.on_hold,
  dropped: stats.data.dropped,
  planToWatch: stats.data.plan_to_watch,
  total: stats.data.total
});
getAnimeRecommendations(id: number)

Get anime recommendations.

const recommendations = await jikan.anime.getAnimeRecommendations(1);
recommendations.data.forEach(rec => {
  console.log({
    title: rec.entry.title,
    votes: rec.votes,
    url: rec.entry.url
  });
});
getAnimeRelations(id: number)

Get related anime (sequels, prequels, etc.).

const relations = await jikan.anime.getAnimeRelations(1);
relations.data.forEach(relation => {
  console.log({
    relation: relation.relation,
    entries: relation.entry.map(e => ({ name: e.name, type: e.type }))
  });
});

Additional Information

getAnimeThemes(id: number)

Get opening and ending themes.

const themes = await jikan.anime.getAnimeThemes(1);
console.log({
  openings: themes.data.openings,
  endings: themes.data.endings
});
getAnimeExternal(id: number)

Get external links.

const external = await jikan.anime.getAnimeExternal(1);
external.data.forEach(link => {
  console.log({
    name: link.name,
    url: link.url
  });
});
getAnimeStreaming(id: number)

Get streaming platform information.

const streaming = await jikan.anime.getAnimeStreaming(1);
streaming.data.forEach(platform => {
  console.log({
    name: platform.name,
    url: platform.url
  });
});
getAnimeMoreInfo(id: number)

Get additional information.

const moreInfo = await jikan.anime.getAnimeMoreInfo(1);
console.log(moreInfo.data.moreinfo);
getAnimeUserUpdates(id: number, page?: number)

Get recent user updates.

const updates = await jikan.anime.getAnimeUserUpdates(1);
updates.data.forEach(update => {
  console.log({
    user: update.user.username,
    status: update.status,
    episodesSeen: update.episodes_seen,
    score: update.score,
    date: update.date
  });
});

Manga Endpoints

Basic Information

getMangaByFullId(id: number)

Retrieves complete manga information by MyAnimeList ID.

const manga = await jikan.manga.getMangaByFullId(1);
console.log({
  title: manga.data.titles[0].title,
  score: manga.data.score,
  chapters: manga.data.chapters,
  volumes: manga.data.volumes,
  status: manga.data.status
});
getMangaById(id: number)

Retrieves basic manga information by MyAnimeList ID.

const manga = await jikan.manga.getMangaById(1);
console.log({
  title: manga.data.titles[0].title,
  type: manga.data.type,
  publishing: manga.data.publishing
});
searchManga(params?: SearchParams)

Search for manga with various filters.

// Basic search
const results = await jikan.manga.searchManga({ q: 'One Piece' });

// Advanced search with filters
const filteredResults = await jikan.manga.searchManga({
  q: 'Attack on Titan',
  type: 'Manga',
  status: 'Finished',
  min_score: 8.0,
  order_by: 'score',
  sort: 'desc',
  limit: 10
});

Search Parameters:

  • q?: string - Search query
  • type?: string - Manga type (Manga, Light Novel, One-shot, Doujinshi, Manhwa, Manhua, Novel)
  • score?: number - Score filter
  • min_score?: number - Minimum score
  • max_score?: number - Maximum score
  • status?: string - Publishing status
  • sfw?: boolean - Safe for work filter
  • genres?: string - Comma-separated genre IDs
  • order_by?: string - Field to order by
  • sort?: string - Sort direction (asc, desc)
  • magazines?: string - Comma-separated magazine IDs
  • page?: number - Page number
  • limit?: number - Results per page

Characters & Staff

getMangaCharacters(id: number)

Get character information for a manga.

const characters = await jikan.manga.getMangaCharacters(1);
characters.data.forEach(char => {
  console.log({
    name: char.character.name,
    role: char.role
  });
});

Community Content

getMangaNews(id: number, page?: number)

Get news articles related to a manga.

const news = await jikan.manga.getMangaNews(1);
news.data.forEach(article => {
  console.log({
    title: article.title,
    author: article.author_username,
    date: article.date,
    excerpt: article.excerpt
  });
});
getMangaReviews(id: number, page?: number, preliminary?: boolean, spoilers?: boolean)

Get user reviews for a manga.

const reviews = await jikan.manga.getMangaReviews(1);
reviews.data.forEach(review => {
  console.log({
    reviewer: review.user.username,
    overallScore: review.scores.overall,
    review: review.review.substring(0, 100) + '...',
    chaptersRead: review.chapters_read
  });
});

// Get reviews with filters
const filteredReviews = await jikan.manga.getMangaReviews(1, 1, true, false);
getMangaForum(id: number)

Get forum topics related to a manga.

const forum = await jikan.manga.getMangaForum(1);
forum.data.forEach(topic => {
  console.log({
    title: topic.title,
    author: topic.author_username,
    comments: topic.comments,
    lastComment: topic.last_comment?.date_posted
  });
});

Media & Content

getMangaPictures(id: number)

Get picture gallery for a manga.

const pictures = await jikan.manga.getMangaPictures(1);
pictures.data.forEach(picture => {
  console.log({
    large: picture.large_image_url,
    small: picture.small_image_url
  });
});

Statistics & Related Content

getMangaStatistics(id: number)

Get reading statistics for a manga.

const stats = await jikan.manga.getMangaStatistics(1);
console.log({
  reading: stats.data.reading,
  completed: stats.data.completed,
  onHold: stats.data.on_hold,
  dropped: stats.data.dropped,
  planToRead: stats.data.plan_to_read,
  total: stats.data.total
});
getMangaRecommendations(id: number)

Get manga recommendations.

const recommendations = await jikan.manga.getMangaRecommendations(1);
recommendations.data.forEach(rec => {
  console.log({
    title: rec.entry.title,
    votes: rec.votes,
    url: rec.entry.url
  });
});
getMangaRelations(id: number)

Get related manga/anime (sequels, prequels, etc.).

const relations = await jikan.manga.getMangaRelations(1);
relations.data.forEach(relation => {
  console.log({
    relation: relation.relation,
    entries: relation.entry.map(e => ({ name: e.name, type: e.type }))
  });
});

Additional Information

getMangaExternal(id: number)

Get external links.

const external = await jikan.manga.getMangaExternal(1);
external.data.forEach(link => {
  console.log({
    name: link.name,
    url: link.url
  });
});
getMangaMoreInfo(id: number)

Get additional information.

const moreInfo = await jikan.manga.getMangaMoreInfo(1);
console.log(moreInfo.data.moreinfo);
getMangaUserUpdates(id: number, page?: number)

Get recent user updates.

const updates = await jikan.manga.getMangaUserUpdates(1);
updates.data.forEach(update => {
  console.log({
    user: update.user.username,
    status: update.status,
    chaptersRead: update.chapters_read,
    volumesRead: update.volumes_read,
    score: update.score,
    date: update.date
  });
});

Characters Endpoints

Basic Information

getCharacterByFullId(id: number)

Retrieves complete character information by MyAnimeList ID.

const character = await jikan.characters.getCharacterByFullId(1);
console.log({
  name: character.data.name,
  nameKanji: character.data.name_kanji,
  nicknames: character.data.nicknames,
  favorites: character.data.favorites,
  about: character.data.about
});
getCharacterById(id: number)

Retrieves basic character information by MyAnimeList ID.

const character = await jikan.characters.getCharacterById(1);
console.log({
  name: character.data.name,
  favorites: character.data.favorites,
  url: character.data.url
});

Appearances & Media

getCharacterAnime(id: number)

Get anime appearances for a character.

const animeAppearances = await jikan.characters.getCharacterAnime(1);
animeAppearances.data.forEach(appearance => {
  console.log({
    title: appearance.anime.title,
    role: appearance.role,
    url: appearance.anime.url
  });
});
getCharacterManga(id: number)

Get manga appearances for a character.

const mangaAppearances = await jikan.characters.getCharacterManga(1);
mangaAppearances.data.forEach(appearance => {
  console.log({
    title: appearance.manga.title,
    role: appearance.role,
    url: appearance.manga.url
  });
});
getCharacterVoices(id: number)

Get voice actor information for a character.

const voices = await jikan.characters.getCharacterVoices(1);
voices.data.forEach(voice => {
  console.log({
    voiceActor: voice.person.name,
    language: voice.language,
    url: voice.person.url
  });
});
getCharacterPictures(id: number)

Get picture gallery for a character.

const pictures = await jikan.characters.getCharacterPictures(1);
pictures.data.forEach(picture => {
  console.log({
    large: picture.large_image_url,
    small: picture.small_image_url
  });
});

Error Handling

The library throws errors for failed API requests:

try {
  const anime = await jikan.anime.getAnimeByFullId(999999);
} catch (error) {
  console.error('API Error:', error.message);
  // Handle the error appropriately
}

TypeScript Support

This library is written in TypeScript and provides comprehensive type definitions:

import Jikan, { AnimeResponse, MangaResponse, CharacterResponse, JikanResponse } from 'jikan-api.js';

const jikan = new Jikan();

// Full type safety for anime
const anime: JikanResponse<AnimeResponse> = await jikan.anime.getAnimeByFullId(1);

// Full type safety for manga
const manga: JikanResponse<MangaResponse> = await jikan.manga.getMangaByFullId(1);

// Full type safety for characters
const character: JikanResponse<CharacterResponse> = await jikan.characters.getCharacterByFullId(1);

// TypeScript will provide autocomplete and type checking
console.log(anime.data.titles[0].title);
console.log(anime.data.score);
console.log(anime.data.episodes);

console.log(manga.data.titles[0].title);
console.log(manga.data.score);
console.log(manga.data.chapters);

console.log(character.data.name);
console.log(character.data.nicknames);
console.log(character.data.favorites);

Pagination

Many endpoints support pagination:

// Check if more pages are available
const episodes = await jikan.anime.getAnimeEpisodes(1);
if (episodes.pagination?.has_next_page) {
  const nextPage = await jikan.anime.getAnimeEpisodes(1, 2);
}

// Get pagination info
console.log({
  currentPage: episodes.pagination?.current_page,
  lastPage: episodes.pagination?.last_visible_page,
  itemsPerPage: episodes.pagination?.items.per_page,
  totalItems: episodes.pagination?.items.total
});

Rate Limiting

The Jikan API has rate limits. It's recommended to:

  1. Add delays between requests if making many calls
  2. Implement retry logic for failed requests
  3. Cache responses when possible
// Example with delay
async function getMultipleAnime(ids: number[]) {
  const results = [];
  for (const id of ids) {
    const anime = await jikan.anime.getAnimeByFullId(id);
    results.push(anime);
    
    // Add delay to respect rate limits
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
  return results;
}

Examples

Get Top Anime

const topAnime = await jikan.anime.searchAnime({
  order_by: 'score',
  sort: 'desc',
  limit: 10
});

console.log('Top 10 Anime:');
topAnime.data.forEach((anime, index) => {
  console.log(`${index + 1}. ${anime.titles[0].title} (Score: ${anime.score})`);
});

Find Anime by Genre

// Get action anime (genre ID 1)
const actionAnime = await jikan.anime.searchAnime({
  genres: '1',
  order_by: 'popularity',
  sort: 'asc',
  limit: 5
});

console.log('Popular Action Anime:');
actionAnime.data.forEach(anime => {
  console.log(`${anime.titles[0].title} - Episodes: ${anime.episodes}`);
});

Get Anime with Full Details

async function getAnimeDetails(id: number) {
  // Get all information about an anime
  const [
    anime,
    characters,
    staff,
    episodes,
    reviews,
    stats
  ] = await Promise.all([
    jikan.anime.getAnimeByFullId(id),
    jikan.anime.getAnimeCharacters(id),
    jikan.anime.getAnimeStaff(id),
    jikan.anime.getAnimeEpisodes(id),
    jikan.anime.getAnimeReviews(id),
    jikan.anime.getAnimeStatistics(id)
  ]);

  return {
    basic: anime.data,
    characters: characters.data,
    staff: staff.data,
    episodes: episodes.data,
    reviews: reviews.data,
    statistics: stats.data
  };
}

// Usage
const fullDetails = await getAnimeDetails(1);
console.log('Full anime details:', fullDetails);

Get Top Manga

const topManga = await jikan.manga.searchManga({
  order_by: 'score',
  sort: 'desc',
  limit: 10
});

console.log('Top 10 Manga:');
topManga.data.forEach((manga, index) => {
  console.log(`${index + 1}. ${manga.titles[0].title} (Score: ${manga.score})`);
});

Find Manga by Genre

// Get romance manga (genre ID 22)
const romanceManga = await jikan.manga.searchManga({
  genres: '22',
  order_by: 'popularity',
  sort: 'asc',
  limit: 5
});

console.log('Popular Romance Manga:');
romanceManga.data.forEach(manga => {
  console.log(`${manga.titles[0].title} - Chapters: ${manga.chapters || 'Ongoing'}`);
});

Get Manga with Full Details

async function getMangaDetails(id: number) {
  // Get all information about a manga
  const [
    manga,
    characters,
    news,
    reviews,
    stats,
    recommendations
  ] = await Promise.all([
    jikan.manga.getMangaByFullId(id),
    jikan.manga.getMangaCharacters(id),
    jikan.manga.getMangaNews(id),
    jikan.manga.getMangaReviews(id),
    jikan.manga.getMangaStatistics(id),
    jikan.manga.getMangaRecommendations(id)
  ]);

  return {
    basic: manga.data,
    characters: characters.data,
    news: news.data,
    reviews: reviews.data,
    statistics: stats.data,
    recommendations: recommendations.data
  };
}

// Usage
const fullMangaDetails = await getMangaDetails(1);
console.log('Full manga details:', fullMangaDetails);

Compare Anime and Manga

async function compareAnimeAndManga(animeId: number, mangaId: number) {
  const [anime, manga] = await Promise.all([
    jikan.anime.getAnimeByFullId(animeId),
    jikan.manga.getMangaByFullId(mangaId)
  ]);

  console.log('Comparison:');
  console.log(`Anime: ${anime.data.titles[0].title} - Score: ${anime.data.score}`);
  console.log(`Manga: ${manga.data.titles[0].title} - Score: ${manga.data.score}`);
  
  return {
    anime: anime.data,
    manga: manga.data,
    animeScore: anime.data.score,
    mangaScore: manga.data.score
  };
}

// Usage
const comparison = await compareAnimeAndManga(1, 1);

Get Character Details with Appearances

async function getCharacterDetails(id: number) {
  // Get all information about a character
  const [
    character,
    animeAppearances,
    mangaAppearances,
    voices,
    pictures
  ] = await Promise.all([
    jikan.characters.getCharacterByFullId(id),
    jikan.characters.getCharacterAnime(id),
    jikan.characters.getCharacterManga(id),
    jikan.characters.getCharacterVoices(id),
    jikan.characters.getCharacterPictures(id)
  ]);

  return {
    basic: character.data,
    animeAppearances: animeAppearances.data,
    mangaAppearances: mangaAppearances.data,
    voiceActors: voices.data,
    pictures: pictures.data
  };
}

// Usage
const characterDetails = await getCharacterDetails(1);
console.log('Character details:', characterDetails);

Find Character Voice Actors

async function getCharacterVoiceActors(characterId: number) {
  const voices = await jikan.characters.getCharacterVoices(characterId);
  
  const voiceActorsByLanguage = voices.data.reduce((acc, voice) => {
    if (!acc[voice.language]) {
      acc[voice.language] = [];
    }
    acc[voice.language].push({
      name: voice.person.name,
      url: voice.person.url
    });
    return acc;
  }, {} as Record<string, Array<{name: string, url: string}>>);

  return voiceActorsByLanguage;
}

// Usage
const voiceActors = await getCharacterVoiceActors(1);
console.log('Japanese VAs:', voiceActors.Japanese);
console.log('English VAs:', voiceActors.English);

Character Appearance Analysis

async function analyzeCharacterAppearances(characterId: number) {
  const [animeAppearances, mangaAppearances] = await Promise.all([
    jikan.characters.getCharacterAnime(characterId),
    jikan.characters.getCharacterManga(characterId)
  ]);

  const stats = {
    totalAnime: animeAppearances.data.length,
    totalManga: mangaAppearances.data.length,
    mainRoles: {
      anime: animeAppearances.data.filter(a => a.role === 'Main').length,
      manga: mangaAppearances.data.filter(m => m.role === 'Main').length
    },
    supportingRoles: {
      anime: animeAppearances.data.filter(a => a.role === 'Supporting').length,
      manga: mangaAppearances.data.filter(m => m.role === 'Supporting').length
    }
  };

  return {
    stats,
    animeList: animeAppearances.data.map(a => ({ title: a.anime.title, role: a.role })),
    mangaList: mangaAppearances.data.map(m => ({ title: m.manga.title, role: m.role }))
  };
}

// Usage
const analysis = await analyzeCharacterAppearances(1);
console.log('Character appeared in', analysis.stats.totalAnime, 'anime and', analysis.stats.totalManga, 'manga');

Recommendations Endpoints

Recent Recommendations

getRecentAnimeRecommendations(page?: number)

Get recent anime recommendations from the community.

const recommendations = await jikan.recommendations.getRecentAnimeRecommendations();
recommendations.data.forEach(rec => {
  console.log(`${rec.entry[0].title} recommended with ${rec.entry[1].title}`);
  console.log(`Recommendation: ${rec.content}`);
  console.log(`By: ${rec.user.username} on ${rec.date}`);
});

// Get specific page
const page2 = await jikan.recommendations.getRecentAnimeRecommendations(2);
getRecentMangaRecommendations(page?: number)

Get recent manga recommendations from the community.

const recommendations = await jikan.recommendations.getRecentMangaRecommendations();
recommendations.data.forEach(rec => {
  console.log(`${rec.entry[0].title} recommended with ${rec.entry[1].title}`);
  console.log(`Recommendation: ${rec.content}`);
  console.log(`By: ${rec.user.username} on ${rec.date}`);
});

// Get specific page
const page3 = await jikan.recommendations.getRecentMangaRecommendations(3);

Recommendation Structure:

  • Each recommendation contains exactly 2 entries for comparison
  • entry[0] and entry[1] contain the recommended content with basic information
  • content contains the user's recommendation text
  • user contains information about who made the recommendation
  • date contains when the recommendation was created

Users Endpoints

Basic User Information

getUserByUsername(username: string)

Retrieves basic user profile information.

const user = await jikan.users.getUserByUsername('username');
console.log({
  username: user.data.username,
  joined: user.data.joined,
  lastOnline: user.data.last_online,
  url: user.data.url
});
getUserFullProfile(username: string)

Retrieves complete user profile information including extended details.

const user = await jikan.users.getUserFullProfile('username');
console.log({
  username: user.data.username,
  about: user.data.about,
  joined: user.data.joined,
  location: user.data.location
});
getUserAbout(username: string)

Retrieves user's profile description/about section.

const about = await jikan.users.getUserAbout('username');
console.log(about.data.about);

User Statistics

getUserStatistics(username: string)

Get user's anime and manga viewing/reading statistics.

const stats = await jikan.users.getUserStatistics('username');
console.log({
  animeCompleted: stats.data.anime.completed,
  animeWatching: stats.data.anime.watching,
  daysWatched: stats.data.anime.days_watched,
  meanScore: stats.data.anime.mean_score,
  
  mangaCompleted: stats.data.manga.completed,
  mangaReading: stats.data.manga.reading,
  daysRead: stats.data.manga.days_read,
  chaptersRead: stats.data.manga.chapters_read
});

User Lists

getUserAnimeList(username: string, params?: object)

Get user's anime list with optional filtering.

// Get all anime
const animeList = await jikan.users.getUserAnimeList('username');

// Filter by status
const completed = await jikan.users.getUserAnimeList('username', { 
  status: 'completed' 
});

const watching = await jikan.users.getUserAnimeList('username', { 
  status: 'watching' 
});

// With pagination
const page2 = await jikan.users.getUserAnimeList('username', { 
  status: 'completed',
  page: 2 
});

Available status filters:

  • watching - Currently watching
  • completed - Completed
  • on_hold - On hold
  • dropped - Dropped
  • plan_to_watch - Plan to watch
getUserMangaList(username: string, params?: object)

Get user's manga list with optional filtering.

// Get all manga
const mangaList = await jikan.users.getUserMangaList('username');

// Filter by status
const reading = await jikan.users.getUserMangaList('username', { 
  status: 'reading' 
});

const completed = await jikan.users.getUserMangaList('username', { 
  status: 'completed' 
});

Available status filters:

  • reading - Currently reading
  • completed - Completed
  • on_hold - On hold
  • dropped - Dropped
  • plan_to_read - Plan to read

User Favorites

getUserFavorites(username: string)

Get user's favorite anime, manga, characters, and people.

const favorites = await jikan.users.getUserFavorites('username');
console.log({
  favoriteAnime: favorites.data.anime,
  favoriteManga: favorites.data.manga,
  favoriteCharacters: favorites.data.characters,
  favoritePeople: favorites.data.people
});

Social Features

getUserFriends(username: string, page?: number)

Get user's friends list.

const friends = await jikan.users.getUserFriends('username');
friends.data.forEach(friend => {
  console.log({
    username: friend.username,
    url: friend.url,
    friendsSince: friend.friends_since
  });
});

// Get specific page
const friendsPage2 = await jikan.users.getUserFriends('username', 2);
getUserClubs(username: string, page?: number)

Get clubs the user is a member of.

const clubs = await jikan.users.getUserClubs('username');
clubs.data.forEach(club => {
  console.log({
    name: club.name,
    url: club.url,
    members: club.members
  });
});

User Content

getUserReviews(username: string, page?: number)

Get reviews written by the user.

const reviews = await jikan.users.getUserReviews('username');
reviews.data.forEach(review => {
  console.log({
    anime: review.entry.title,
    overallScore: review.scores.overall,
    review: review.review.substring(0, 100) + '...',
    date: review.date
  });
});
getUserRecommendations(username: string, page?: number)

Get recommendations made by the user.

const recommendations = await jikan.users.getUserRecommendations('username');
recommendations.data.forEach(rec => {
  console.log({
    content: rec.content,
    entry1: rec.entry[0].title,
    entry2: rec.entry[1].title,
    date: rec.date
  });
});
getUserUpdates(username: string)

Get user's recent activity (anime/manga progress updates).

const updates = await jikan.users.getUserUpdates('username');
updates.data.forEach(update => {
  console.log({
    title: update.entry.title,
    status: update.status,
    progress: update.episodes_seen || update.chapters_read,
    score: update.score,
    date: update.date
  });
});

User Search

searchUsers(params?: object)

Search for users by username.

// Basic search
const users = await jikan.users.searchUsers({ q: 'username' });

// With pagination and limit
const searchResults = await jikan.users.searchUsers({
  q: 'user',
  page: 1,
  limit: 10
});

users.data.forEach(user => {
  console.log({
    username: user.username,
    joined: user.joined,
    lastOnline: user.last_online
  });
});

Search Parameters:

  • q?: string - Search query (username)
  • page?: number - Page number for pagination
  • limit?: number - Results per page (max 25)

People Endpoints

Basic Person Information

getPersonById(id: number)

Retrieves basic person information.

const person = await jikan.people.getPersonById(1);
console.log({
  name: person.data.name,
  birthday: person.data.birthday,
  favorites: person.data.favorites
});
getPersonFullById(id: number)

Retrieves complete person information.

const person = await jikan.people.getPersonFullById(1);
console.log({
  name: person.data.name,
  about: person.data.about,
  alternateNames: person.data.alternate_names
});

Person Work & Roles

getPersonAnime(id: number)

Get anime work for a person.

const animeWork = await jikan.people.getPersonAnime(1);
animeWork.data.forEach(work => {
  console.log(`${work.position} for ${work.anime.title}`);
});
getPersonManga(id: number)

Get manga work for a person.

const mangaWork = await jikan.people.getPersonManga(1);
mangaWork.data.forEach(work => {
  console.log(`${work.position} for ${work.manga.title}`);
});
getPersonVoices(id: number)

Get voice acting roles for a person.

const voices = await jikan.people.getPersonVoices(1);
voices.data.forEach(voice => {
  console.log(`${voice.character.name} in ${voice.anime.title} (${voice.role})`);
});

Person Media

getPersonPictures(id: number)

Get pictures for a person.

const pictures = await jikan.people.getPersonPictures(1);
pictures.data.forEach(picture => {
  console.log(picture.large_image_url);
});
getPersonExternal(id: number)

Get external links for a person.

const external = await jikan.people.getPersonExternal(1);
external.data.forEach(link => {
  console.log(`${link.name}: ${link.url}`);
});

Person Search

searchPeople(params?: object)

Search for people.

const people = await jikan.people.searchPeople({ q: 'Hayao Miyazaki' });
people.data.forEach(person => {
  console.log(person.name);
});

// Advanced search
const results = await jikan.people.searchPeople({
  q: 'director',
  order_by: 'favorites',
  sort: 'desc',
  limit: 10
});

Genres Endpoints

getAnimeGenres()

Get all available anime genres.

const genres = await jikan.genres.getAnimeGenres();
genres.data.forEach(genre => {
  console.log(`${genre.name} (${genre.count} anime)`);
});
getMangaGenres()

Get all available manga genres.

const genres = await jikan.genres.getMangaGenres();
genres.data.forEach(genre => {
  console.log(`${genre.name} (${genre.count} manga)`);
});

Schedules Endpoints

getSchedules(params?: object)

Get anime schedule information.

// Get all scheduled anime
const schedule = await jikan.schedules.getSchedules();

// Get Monday anime only
const mondayAnime = await jikan.schedules.getSchedules({ 
  filter: 'monday' 
});

// Get safe-for-work anime with pagination
const sfwSchedule = await jikan.schedules.getSchedules({
  sfw: true,
  page: 2,
  limit: 10
});

schedule.data.forEach(anime => {
  console.log(`${anime.title} - ${anime.broadcast.string}`);
});

Day-specific methods:

  • getMondaySchedule(page?: number)
  • getTuesdaySchedule(page?: number)
  • getWednesdaySchedule(page?: number)
  • getThursdaySchedule(page?: number)
  • getFridaySchedule(page?: number)
  • getSaturdaySchedule(page?: number)
  • getSundaySchedule(page?: number)

Random Endpoints

getRandomAnime()

Get a random anime.

const randomAnime = await jikan.random.getRandomAnime();
console.log(`Random anime: ${randomAnime.data.titles[0].title}`);
console.log(`Score: ${randomAnime.data.score}`);
getRandomManga()

Get a random manga.

const randomManga = await jikan.random.getRandomManga();
console.log(`Random manga: ${randomManga.data.titles[0].title}`);
console.log(`Score: ${randomManga.data.score}`);
getRandomCharacter()

Get a random character.

const randomCharacter = await jikan.random.getRandomCharacter();
console.log(`Random character: ${randomCharacter.data.name}`);
console.log(`Favorites: ${randomCharacter.data.favorites}`);
getRandomPerson()

Get a random person.

const randomPerson = await jikan.random.getRandomPerson();
console.log(`Random person: ${randomPerson.data.name}`);
console.log(`Favorites: ${randomPerson.data.favorites}`);
getRandomUser()

Get a random user.

const randomUser = await jikan.random.getRandomUser();
console.log(`Random user: ${randomUser.data.username}`);
console.log(`Joined: ${randomUser.data.joined}`);

Characters Search

searchCharacters(params?: object)

Search for characters.

const characters = await jikan.characters.searchCharacters({ q: 'Spike' });
characters.data.forEach(character => {
  console.log(character.name);
});

// Advanced search
const results = await jikan.characters.searchCharacters({
  q: 'main character',
  order_by: 'favorites',
  sort: 'desc',
  limit: 10
});

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development

# Clone the repository
git clone https://github.com/OpenianDevelopment/jikan-api.js.git
cd jikan-api.js

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Run tests in watch mode
npm run test:watch

# Build in watch mode
npm run dev

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Related Projects

Made with ❤️ by Rohan Kumar

About

Jikan api v4 wrapper

Topics

nodejs typescript myanimelist hacktoberfest jikan

Resources

Readme
Activity
Custom properties

Stars

4 stars

Watchers

2 watching

Forks

2 forks
Report repository

Releases 2

2.0.0 Latest
Jul 6, 2025
+ 1 release

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages