Jikan

Introduction

Jikan is an Unofficial MyAnimeList API. It's built on the Lumen microframework, uses Redis for caching and is powered by the Jikan PHP API.

API Path: https://api.jikan.moe/v3

API Version: v3.4 RC

Status | Report an Issue | Discord

Information Links

Wrappers

PHP API - JikanPHP by Contributors
Python - JikanPy by Andrew Conant & abhinavk99 (Abhinav Kasamsetty)
Ruby - Jikan.rb by Zerocchi
.NET/C# - Jikan.Net by Ervie (Bartłomiej Buchała)
JavaScript - JikanJs by zuritor (Sven)
Java - Jikan4java by Doomsdayrs
PHP - Jikan-php by Jan Vernieuwe
NodeJS - Jikan-node by xy137
Dart - Jikan-dart by Rafal Wachol
TypeScript - Jikants by Julien Broyard
TypeScript - jikan-client by Javier Blanco
Go - Jikan-go by Daren Liang

Add your wrapper here!

Rate Limiting

Daily Limit: Unlimited

30 requests / minute
2 requests / second

Note: Cached requests are NOT throttled

Bulk Requests

This API serves as a purpose for apps/projects that are user based and make a nominal amount of requests.

⚠️ If you're using the service for the sake of populating data/making your own database;

You are breaching MyAnimeList's Terms Of Service. You are responsible for what you're doing.
You MUST use a delay of 4 (FOUR) SECONDS between each request
Requesting from multiple servers/IPs is being cheeky and is NOT allowed
ABUSING THE API WILL RESULT IN GETTING BLOCKED FROM THE SERVICE

If you're not comfortable being that restrictive, consider setting up your own Jikan REST API - It's super easy.

Disclaimer

Jikan is not affiliated with MyAnimeList.net
Jikan is a free, open-source API. Use it responsibly!

JSON Notes

Any property (except arrays) whose value does not exist or is undertermined, will be null
Any array property whose value does not exist or is undetermined, will be empty
Any score property whose value does not exist or is undetermined, will be 0
All dates and timestamps are returned in ISO8601 format and in UTC

Caching

By "caching", we refer to the data parsed from MyAnimeList that is cached temporarily on our servers for performance/faster responses.

All requests by default are cached for 24 hours except for a few API endpoints which have their own unique cache expiry time.

Request	Cache TTL
All (Default)	24 hours
Meta	5 minutes
User	5 minutes
Search	120 hours (5 days)

The following Response Headers will detail cache information

Header	Remarks
`Expires`	Expiry timestamp for the cache
`X-Request-Cached`	(boolean) Is the request cached?
`X-Request-Cache-Ttl`	(integer) Cache Time-To-Live in seconds

FAQ: Why is X-Request-Cache-Ttl negative?

Jikan REST API v3.3+ uses a different caching logic. If the cache expires, it queues a job in the background to update the cache. So you're getting stale cache until the cache update completes.

Allowed HTTP(s) requests

GET: All requests are done via GET

The Jikan REST API does not provide authenticated requests for MyAnimeList. This means you can not use it to update your anime/manga lists.

Reasons:

Why on earth would you send your credentials to a 3rd party API?
MyAnimeList will block our IP after multiple failed login attempts

However, do not fret. This is possible via their own website. Read the Specification

Furthermore, JikanAuth is a PHP API which you can use to update your lists - it implements the Specification above. So feel free to come up with your own client-side solution.

HTTP Response

200 OK - the request was successful.
304 Not Modified - You have the latest data
400 Bad Request - You've made an invalid request or to an invalid endpoint.
404 Not Found - MyAnimeList responded with a 404
405 Method Not Allowed - requested method is not supported for resource.
429 Too Many Requests - You are being rate limited or Jikan is being rate-limited by MyAnimeList
500 Internal Server Error - Something broke on our end :(

JSON Error Response

This is a typical error response

{
    "status": 404,
    "type": "BadResponseException",
    "message": "Resource does not exist"
    "error": "Something Happened"
}

Property	Remarks
`status`	HTTP Status returned
`type`	`Exception` generated from the PHP API
`message`	Appropriate error message from the REST API
`error`	Error response from the PHP API
`report_url` (fatal errors only)	Clicking on this would redirect you to a generated GitHub Issue

Cache Validation

All requests return a ETag header which is an md5 hash of the content.
You can use this hash to verify if there's new or updated content by supplying it as the value for the If-None-Match header.
You will get a 304 HTTP response if your value and the data on Jikan matches.
If there's new/updated content, you'll get a normal 200 HTTP response with the updated content.

How To Use

Use the ETag value as a header value for If-None-Match for future requests
If the content has changed, you will get a 304 - Not Modified header response, otherwise 200 - OK

Reference

Anime

Attributes

A single anime object with all its details

Endpoint Path: /anime/{id}(/request)

Requests

Request	Parameter	Description
`/`	N/A	Resource object with all it's details
`/characters_staff`	N/A	List of character and staff members
`/episodes`	Page number (integer)	List of episodes
`/news`	N/A	List of Related news
`/pictures`	N/A	List of Related pictures
`/videos`	N/A	List o fPromotional Videos & episodes (if any)
`/stats`	N/A	Related statistical information
`/forum`	N/A	List of Related forum topics
`/moreinfo`	N/A	A string of more information (if any)
`/reviews`	Page number (integer)	List of Reviews written by users
`/recommendations`	N/A	List of Recommendations and their weightage made by users
`/userupdates`	Page number (integer)	List of the latest list updates made by users

Remarks

`/episodes`

The field episodes_last_page will tell you the last page of the paginated episodes list.
The episodes page on MyAnimeList get paginated after 100 episodes. If there's an anime with more than 100 episodes, you'll have to use the parameter.

`/reviews`

Only 20 items are shown per page for reviews

Examples

/anime/1/characters_staff // Returns the list of characters and staff
/anime/1/episodes // Defaults to the 1st page
/anime/1/episodes/1 // Same as above
/anime/1/episodes/2 // Returns 2nd page if there's any

Fetch Resource

Manga

Attributes

A single manga object with all its details

Requests

Request	Parameter	Description
characters	N/A	Fetches the list of characters & staff members of the manga
news	N/A	News related to the item
pictures	N/A	Pictures related to the item
stats	N/A	Statistical information related to the item
forum	N/A	Forum topics related to the item
moreinfo	N/A	More info related to the item
reviews	Page number (integer)	Reviews written by users
recommendations	N/A	Recommendations and their weightage made by users
userupdates	Page number (integer)	Latest list updates made by users

Example Calls

/manga/1/characters // Returns the list of characters and staff

Remarks

Only 20 items are shown per page for reviews

Manga Request Example+Schema

Person

Attributes

A single person object with all its details

Requests

Request	Parameter	Description
pictures	N/A	Pictures related to the item

Person Request Example+Schema

Character

Attributes

A single character object with all its details

Requests

Request	Parameter	Description
pictures	N/A	Pictures related to the item

Character Request Example+Schema

Search

Attributes

Search results for the query

NOTE: MyAnimeList only processes queries with a minimum of 3 letters. However, the search function can be used without q! Check examples below for more details.

Parameters

Parameter	Argument	Description
type	anime, manga, person, character	Specify where to search
page	INTEGER	Page number of the results

Advanced Search Parameters (Anime & Manga)

Note: These are search filters which have to be passed as GET key=value

Parameter	Argument	Description
q	STRING	For UTF8 characters, percentage encoded and queries including back slashes
page	INTEGER	Page number
type	See Enums Below	Filter type of results
status	See Enums Below	Filter status of results
rated	See Enums Below	Filter age rating of results
genre	See Enums Below	Filter by genre ID(s)
score	FLOAT : 0.0-10.0	Filter score of results
start_date	`yyyy-mm-dd`	Filter start date of results
end_date	`yyyy-mm-dd`	Filter end date of results
genre_exclude	boolean : 0/1	To exlude/include the `genre` you added in your request
limit	INTEGER	Limits item results to the number specified
order_by	See Enums Below	Order results with respect to a property
sort	See Enums Below	Sort `order_by` (Default is `descending`)
producer	INTEGER	MAL ID of the producer
magazine	INTEGER	MAL ID of the magazine
letter	UTF8 Character	Search anime or manga by the letter/character it starts with

Enums

`type`

Anime Types	Manga Types
`tv`	`manga`
`ova`	`novel`
`movie`	`oneshot`
`special`	`doujin`
`ona`	`manhwa`
`music`	`manhua`

`status`

Anime Status	Manga Status
`airing`	`publishing`
`completed`	`completed`
`complete` (alias)	`complete` (alias)
`to_be_aired`	`to_be_published`
`tba` (alias)	`tbp` (alias)
`upcoming` (alias)	`upcoming` (alias)

`rated`

Anime ratings are based on MyAnimeList's rating system. Read more about them here

Anime Search	Remarks
`g`	G - All Ages
`pg`	PG - Children
`pg13`	PG-13 - Teens 13 or older
`r17`	R - 17+ recommended (violence & profanity)
`r`	R+ - Mild Nudity (may also contain violence & profanity)
`rx`	Rx - Hentai (extreme sexual content/nudity)

`order_by`

Anime Search	Manga Search
`title`	`title`
`start_date`	`start_date`
`end_date`	`end_date`
`score`	`score`
`type`	`type`
`members`	`members`
`id`	`id`
`episodes`	`chapters`
`rating`	`volumes`

`sort`

Anime & Manga Sort
`ascending`
`asc` (alias)
`descending`
`desc` (alias)

`genre`

Anime Genre	Manga Genre
Action: `1`	Action: `1`
Adventure: `2`	Adventure: `2`
Cars: `3`	Cars: `3`
Comedy: `4`	Comedy: `4`
Dementia: `5`	Dementia: `5`
Demons: `6`	Demons: `6`
Mystery: `7`	Mystery: `7`
Drama: `8`	Drama: `8`
Ecchi: `9`	Ecchi: `9`
Fantasy: `10`	Fantasy: `10`
Game: `11`	Game: `11`
Hentai: `12`	Hentai: `12`
Historical: `13`	Historical: `13`
Horror: `14`	Horror: `14`
Kids: `15`	Kids: `15`
Magic: `16`	Magic: `16`
Martial Arts: `17`	Martial Arts: `17`
Mecha: `18`	Mecha: `18`
Music: `19`	Music: `19`
Parody: `20`	Parody: `20`
Samurai: `21`	Samurai: `21`
Romance: `22`	Romance: `22`
School: `23`	School: `23`
Sci Fi: `24`	Sci Fi: `24`
Shoujo: `25`	Shoujo: `25`
Shoujo Ai: `26`	Shoujo Ai: `26`
Shounen: `27`	Shounen: `27`
Shounen Ai: `28`	Shounen Ai: `28`
Space: `29`	Space: `29`
Sports: `30`	Sports: `30`
Super Power: `31`	Super Power: `31`
Vampire: `32`	Vampire: `32`
Yaoi: `33`	Yaoi: `33`
Yuri: `34`	Yuri: `34`
Harem: `35`	Harem: `35`
Slice Of Life: `36`	Slice Of Life: `36`
Supernatural: `37`	Supernatural: `37`
Military: `38`	Military: `38`
Police: `39`	Police: `39`
Psychological: `40`	Psychological: `40`
Thriller: `41`	Seinen: `41`
Seinen: `42`	Josei: `42`
Josei: `43`	Doujinshi: `43`
	Gender Bender: `44`
	Thriller: `45`

Examples

/search/manga/Grand%20Blue/1 (DEPRECIATED v3+)

/search/manga?q=Grand%20Blue&page=1 (RECOMMENDED)

The first way won't work due to the back slash in "Fate/Zero". It's encouraged to use the the GET method below for all queries since it responds more accurately for UTF8 characters and percentage encoding.

/search/anime?q=Fate/Zero&page=1

Furthermore, the former method is depreciated in v3+. Use q for passing queries.

/search/people/?q=Sawashiro&limit=3

Search Request Example+Schema

Season

Attributes

Anime of the specified season

Note: Both parameters are required.

Parameters

Parameter	Argument	Description
year	Integer: Year	Specify the year
season	`summer` `spring` `fall` `winter`	Specify the season

Season Request Example+Schema

Season Archive

Attributes

All the years & their respective seasons that can be parsed from MyAnimeList

Season Archive Request Example+Schema

Season Later

Attributes

Anime that have been announced for the upcoming seasons

Season Later Request Example+Schema

Schedule

Attributes

Anime schedule of the week or specified day

Note: If you don't pass the day parameter, it'll return the schedule for all days of the week

Parameters

Parameter	Argument	Description
day (optional)	`monday` `tuesday` `wednesday` `thursday` `friday` `saturday` `sunday`, `other` (v3), `unknown` (v3)	Anime scheduled for that specific day

Schedule Request Example+Schema

Top

Attributes

Top items on MyAnimeList

Note: subtype returns a filtered top list of a type type item. For example, the top Anime (type) movies (subtype) Note 2: subtype is only for anime and manga types. Note 3: Date properties are returned in string as they only consist of the month and year - which is not appropriate for ISO8601

Parameters

Parameter	Argument	Description
type	`anime` `manga`, `people` (v3+), `characters` (v3+)	Top items of this type
page (optional)	INTEGER	The Top page on MyAnimeList is paginated offers 50 items per page
subtype (optional)	Anime: `airing` `upcoming` `tv` `movie` `ova` `special` Manga: `manga` `novels` `oneshots` `doujin` `manhwa` `manhua` Both: `bypopularity` `favorite`

Top Request Example+Schema

Genre

Attributes

Anime/Manga items of the genre

Note: Genres with their respective IDs are listed here

Parameters

Parameter	Argument	Description
type	`anime` `manga`	Genre of this type
genre_id	INTEGER	Genre ID from MyAnimeList - Genre Mapping
page (optional)

Genre Request Example+Schema

Producer

Attributes

Anime by this Producer/Studio/Licensor

Parameters

Parameter	Argument	Description
producer_id	INTEGER	Producer ID from MyAnimeList
page (optional)

Producer Request Example+Schema

Magazine

Attributes

Manga by this Magazine/Serializer/Publisher

Parameters

Parameter	Argument	Description
magazine_id	INTEGER	Magazine ID from MyAnimeList
page (optional)

Magazine Request Example+Schema

User

Attributes

User related data

Note: About is returned in HTML as MyAnimeList allows custom "about" sections for users that can consist of images, formatting, etc.

Note 2: Anime & Manga Lists are paginated. Only 300 items are returned per page.

Parameters

Parameter	Argument	Description
username	string	Username on MyAnimeList
request	`profile`, `history`, `friends`, `animelist`, `mangalist`
data (optional)	Additional data for the requests

Data

Data	Argument	Description
history	`anime`, `manga`	Returns both combined if neither are passed
friends	INTEGER	Pagination support; Status 404 if there's no friends on the page
animelist	See Enums Below
mangalist	See Enums Below

User List Filter

Anime List `/animelist`	Manga List `/mangalist`
`/`	`/`
`/all` (alias)	`/all` (alias)
`/watching`	`/reading`
`/completed`	`/completed`
`/onhold`	`/onhold`
`/dropped`	`/dropped`
`/plantowatch`	`/plantoread`
`/ptw` (alias)	`/ptr`

Advanced User List Parameters (Anime & Manga)

Note: These are search filters which have to be passed as GET key=value

Parameter	Argument	Description
`search`	STRING	Return items in your list matching the string
`q` (alias)	STRING	Return items in your list matching the string
`page` (alias)	INEGER	Pass page number as a `key=value`
`sort`	See Enums Below	Sort `order_by` (Default is `descending`)

Advanced User List Parameters (ANIME)

Parameter	Argument	Description
`order_by`	See Enums Below	Order items with respect to a property
`order_by2`	See Enums Below	Order items with respect to a second property
`aired_from`	`yyyy-mm-dd`	Filter Anime that have aired from this date
`aired_to`	`yyyy-mm-dd`	Filter Anime that have aired till this date
`producer`	Integer	Filter Anime by this Producer ID
`year`	Integer: Year	Filter anime from a year
`season`	`summer` `spring` `fall` `winter`	Filter anime from a season (require `year`)
`airing_status`	See Enums Below	Filter Anime with a status

Advanced User List Parameters (MANGA)

Parameter	Argument	Description
`order_by`	See Enums Below	Order items with respect to a property
`order_by2`	See Enums Below	Order items with respect to a second property
`published_from`	`yyyy-mm-dd`	Filter Manga that have published from this date
`published_to`	`yyyy-mm-dd`	Filter Manga that have published till this date
`magazine`	Integer	Filter Manga by this Magazine ID
`publishing_status`	See Enums Below	Filter Manga with a status

Regarding yyyy-mm-dd dates, you can search for only the year or only the year and the month as well. Just pass it as yyyy-00-00 or yyyy-mm-00. e.g 2018-00-00, 2018-12-00

Enums

`order_by` & `order_by2`

Anime List	Manga List
`title`	`title`
`finish_date`	`finish_date`
`start_date`	`start_date`
`score`	`score`
`last_updated`	`last_updated`
`type`	`type`
`rated`	``
`rewatch`	``
`rewatch_value` (alias)	``
`priority`	`priority`
`progress`	`progress` (`chapters_read`)
`episodes_watched` (alias)	`chapters_read` (alias)
	`volumes_read`
`storage`	``
`air_start`	`publish_start`
`air_end`	`publish_end`
`status`	`status`

`sort`

Anime & Manga Sort
`ascending`
`asc` (alias)
`descending`
`desc` (alias)

`airing_status` & `publishing_status`

Anime Airing Status	Manga Publishing Status
`airing`	`publishing`
`finished`	`finished`
`complete` (alias)	`complete` (alias)
`to_be_aired`	`to_be_published`
`not_yet_aired` (alias)	`not_yet_published` (alias)
`tba` (alias)	`tbp` (alias)
`nya` (alias)	`nyp` (alias)

Examples

/user/nekomata1037 - Parses Profile

/user/nekomata1037/profile (alias)

/user/nekomata1037/history - Parses user history (anime+manga)

/user/nekomata1037/history/anime - Parses user history (anime only)

/user/nekomata1037/friends - Parses user friends

The request below will return 404 because I don't have that many friends on MAL to generate a second page. /user/nekomata1037/friends/2 - Parses user friends (from page 2)

Anime & Manga Lists

Lists are paginated (300 items per page).

/user/nekomata1037/animelist/all - All anime in user list

/user/nekomata1037/animelist/all/2 - Page 2

/user/nekomata1037/mangalist/reading - Manga that I'm currently reading

User Request Example+Schema

Club

Attributes

A single club object with all its details

Requests

Request	Parameter	Description
members	Page (INTEGER)	Fetches list of club members

Example Calls

/club/1 // Returns club information
/club/1/members/1 // Returns list of club members

Remarks

Only 35 items are shown per page for members

Club Request Example+Schema

Meta

Attributes

Requests related to meta information regarding the Jikan REST Instance. Such as the most requested endpoints for a specific period, or just status on the REST API.

Parameters

Parameter	Argument	Description
request	`requests` `status`
type	`anime` `manga` `character` `person` `search` `top` `schedule` `season`	This is only for the `requests` endpoint
period	`today` `weekly` `monthly`	This is only for the `requests` endpoint
offset	int	1,000 requests are shown per page, you can use the offset to show more

Meta Request Example+Schema