);
}
```
## TypeScript Interfaces
### JikanAnime
```typescript theme={null}
export interface JikanAnime {
mal_id: number;
url: string;
images: {
jpg: JikanImage;
webp: JikanImage;
};
title: string;
title_english: string | null;
title_japanese: string | null;
type: string;
episodes: number | null;
status: string;
score: number | null;
synopsis: string | null;
background: string | null;
season: string | null;
year: number | null;
}
```
The unique MyAnimeList ID
Direct URL to the anime on MyAnimeList
Contains JPG and WebP image variants with multiple sizes
The main title of the anime
English translated title (may be null)
Original Japanese title (may be null)
Anime type: TV, Movie, OVA, Special, ONA, Music
Total number of episodes (null for ongoing/unknown)
Current airing status
MyAnimeList user score (0-10 scale)
Anime description/synopsis
Airing season: spring, summer, fall, winter
Year of airing
### JikanImage
```typescript theme={null}
export interface JikanImage {
image_url: string;
small_image_url: string;
large_image_url: string;
}
```
### JikanEpisode
```typescript theme={null}
export interface JikanEpisode {
mal_id: number;
url: string;
title: string;
title_japanese: string | null;
title_romanji: string | null;
duration: number | null;
aired: string | null;
filler: boolean;
recap: boolean;
forum_url: string | null;
}
```
Indicates if the episode is filler content (not from source material)
Indicates if the episode is a recap episode
Episode duration in seconds
### JikanResponse\
```typescript theme={null}
export interface JikanResponse {
data: T;
pagination?: {
last_visible_page: number;
has_next_page: boolean;
current_page: number;
items: {
count: number;
total: number;
per_page: number;
};
};
}
```
## Rate Limiting & Error Handling
The Jikan API has rate limits. The service automatically handles rate limit errors:
```typescript theme={null}
// src/services/jikan.ts:48
if (response.status === 429) {
throw new Error('Jikan API rate limit exceeded. Please try again later.');
}
```
When you receive a 429 error, the Jikan API is temporarily unavailable. The application should display a user-friendly message and retry the request after a delay.
## Caching Strategy
All Jikan API calls use Next.js ISR (Incremental Static Regeneration) for caching:
| Function | Cache Duration | Reason |
| -------------------- | -------------- | ------------------------------- |
| `getTopAnime` | 1 hour | Top lists change frequently |
| `searchAnime` | 1 hour | Search results may update |
| `getAnimeById` | 24 hours | Individual anime data is stable |
| `getAnimeCharacters` | 24 hours | Character lists rarely change |
| `getAnimeEpisodes` | 24 hours | Episode data is stable |
```typescript theme={null}
// src/services/jikan.ts:43
async function jikanFetch(endpoint: string, revalidate = 3600): Promise {
const response = await fetch(`${JIKAN_API_BASE}${endpoint}`, {
next: { revalidate: revalidate }
});
// ...
}
```
You can adjust cache durations by modifying the `revalidate` parameter in each function call.
## Best Practices
Always show loading states when fetching data from the Jikan API:
```typescript theme={null}
'use client';
import { useState, useEffect } from 'react';
import { getTopAnime } from '@/services/jikan';
export default function TopAnimeList() {
const [anime, setAnime] = useState([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
getTopAnime().then(response => {
setAnime(response.data);
setLoading(false);
});
}, []);
if (loading) return
Loading...
;
return
{/* render anime */}
;
}
```
Always wrap API calls in try-catch blocks:
```typescript theme={null}
try {
const response = await getAnimeById(id);
return response.data;
} catch (error) {
if (error.message.includes('rate limit')) {
// Show rate limit message
} else {
// Show generic error
}
}
```
Always use the provided TypeScript interfaces:
```typescript theme={null}
import type { JikanAnime, JikanResponse } from '@/services/jikan';
function processAnime(anime: JikanAnime) {
// TypeScript will ensure type safety
console.log(anime.mal_id);
}
```
## API Base URL
```typescript theme={null}
const JIKAN_API_BASE = 'https://api.jikan.moe/v4';
```
All requests are made to the Jikan API v4 endpoint. No API key is required.
## Related Resources
Official Jikan API v4 documentation
Source data for all anime information