Skip to main content

​
Introduction

The AniDojo Anime API provides TypeScript functions for fetching anime data from the Jikan API (MyAnimeList). All functions include built-in rate limiting, caching, and error handling.

​
Key Features

  • Automatic Rate Limiting: 3 requests per second with queue management
  • Smart Caching: 5-minute cache with automatic expiry
  • Retry Logic: Exponential backoff for failed requests
  • Type Safety: Full TypeScript support with comprehensive interfaces
  • Zero Configuration: No API key required

​
Available Functions

Search Anime

Search for anime by query string with pagination

Top Anime

Get top-rated anime with optional filtering

Seasonal Anime

Fetch anime by season and year, or get current season

Get by ID

Retrieve detailed information for a specific anime

​
Quick Start

import { 
  searchAnime, 
  getTopAnime, 
  getSeasonalAnime,
  getCurrentSeasonAnime,
  getAnimeById,
  type JikanAnime,
  type JikanSearchResponse
} from '@/lib/animeApi';

​
Core Types

​
JikanAnime Interface

The primary data structure returned by all API functions:
​
mal_id
number
required
MyAnimeList unique identifier
​
title
string
required
Default anime title (usually romaji)
​
title_english
string
English translated title
​
title_japanese
string
Original Japanese title
​
images
object
required
Image URLs in multiple formats
​
type
string
required
Anime type: TV, Movie, OVA, Special, ONA, Music
​
episodes
number
required
Total number of episodes
​
status
string
required
Current airing status: Currently Airing, Finished Airing, Not yet aired
​
score
number
required
MyAnimeList rating score (0-10)
​
synopsis
string
required
Plot description and summary
​
genres
array
required
Array of genre objects with mal_id, name, type, and url
​
studios
array
required
Array of animation studio objects
​
year
number
Release year

​
JikanSearchResponse Interface

Wrapper for paginated API responses:
​
data
JikanAnime[]
required
Array of anime objects matching the query
​
pagination
object
required
Pagination metadata

​
Get Anime by ID

Retrieve detailed information for a specific anime using its MyAnimeList ID.

​
Function Signature

getAnimeById(id: number): Promise<{ data: JikanAnime }>
​
id
number
required
MyAnimeList anime ID (mal_id)

​
Example

import { getAnimeById } from '@/lib/animeApi';

const response = await getAnimeById(1);
const anime = response.data;

console.log(anime.title); // "Cowboy Bebop"
console.log(anime.score); // 8.78

​
Response

Returns an object with a data property containing a single JikanAnime object.

​
Utility Functions

​
convertJikanToAnime

Converts Jikan API format to AniDojo’s internal Anime interface. 
convertJikanToAnime(jikanAnime: JikanAnime): Anime

​
clearAPICache

Clears the internal API cache, forcing fresh data on next request. 
import { clearAPICache } from '@/lib/animeApi';

clearAPICache(); // All cached responses cleared

​
Rate Limiting

The API automatically handles Jikan’s rate limits:
  • Limit: 3 requests per second (~350ms between calls)
  • Queue: Automatic request queuing when limit reached
  • Retry: Up to 3 retries with exponential backoff on 429 errors
  • Cache: 5-minute cache to reduce API calls
Do not implement your own rate limiting. The built-in APIRateLimiter class handles all rate limiting automatically.

​
Error Handling

All functions may throw errors for:
  • Network failures
  • Invalid responses (non-200 status codes)
  • Rate limit exceeded (after retries)
  • Malformed API responses
try {
  const results = await searchAnime('Naruto');
  // Handle results
} catch (error) {
  if (error instanceof Error) {
    console.error('API Error:', error.message);
  }
}

​
React Hooks

For React applications, use the provided hooks from /hooks/useAnime.ts:
  • useAnimeSearch(query, page) - Search with loading/error states
  • useTopAnime(page) - Top anime with automatic updates
  • useSeasonalAnime(year, season) - Seasonal anime data
These hooks are defined in src/hooks/useAnime.ts and handle loading states, error handling, and data caching automatically.

​
API Source

All anime data is provided by the Jikan API, an unofficial MyAnimeList API.
  • Base URL: https://api.jikan.moe/v4/
  • Documentation: docs.api.jikan.moe
  • Rate Limit: 3 requests/second, 60 requests/minute
  • Authentication: None required

​
Next Steps

Search Function

Learn about searchAnime() parameters and usage

Top Anime Function

Explore getTopAnime() with filters

Seasonal Function

Get seasonal and current anime data

Database Schema

Explore the database structure and tables

Build docs developers (and LLMs) love

Get started for freeTalk to us