FORMAT: 1A HOST: https://api.jikan.moe/v3 # Jikan [Jikan](https://jikan.moe) is an **Unofficial** MyAnimeList REST-ful API. It's built on the Lumen microframework, uses Redis for caching and is powered by the [Jikan PHP API](https://github.com/jikan-me/jikan) Base URL: `https://api.jikan.moe/v3` [Bug Report](https://github.com/jikan-me/jikan/issues/new) | **[Discord](https://discordapp.com/invite/4tvCr36)** ## Announcement - 29 December, 18 REST v3.2 has been released! #### New Features - Anime/Manga **Reviews** - Anime/Manga **Recommendations** - Anime/Manga **User Updates** - [Club **Information**](https://jikan.docs.apiary.io/#reference/0/club) - [Club **Members**](https://jikan.docs.apiary.io/#reference/0/club) - [Season **later**](https://jikan.docs.apiary.io/#reference/0/season-later) - [Entity Tags - Cache validation](https://jikan.docs.apiary.io/#introduction/cache-validation) **Important Changes** - All data from user related endpoints `/v3/user/*` are now cached for 5 minutes only - **(Anime/Manga)** Bug fixed for `related` property. It's an object but returns an array when it was empty. **This is fixed now.** ## Links - [Website](https://jikan.moe) - [About](https://jikan.moe/about) - [Projects/Apps using Jikan](https://jikan.moe/showcase) - [REST API Status](https://status.jikan.moe) ## Wrappers - [JikanPHP - Parser](https://github.com/jikan-me/jikan/) by [Contributors](https://github.com/jikan-me/jikan/graphs/contributors) - [JikanPy - Wrapper](https://github.com/AWConant/jikanpy) by Andrew Conant & abhinavk99 (Abhinav Kasamsetty) - [Jikan.rb - Wrapper](https://github.com/Zerocchi/jikan.rb) by Zerocchi - [Jikan.Net - Wrapper](https://github.com/Ervie/jikan.net) by Ervie (Bartłomiej Buchała) - [JikanJs - Wrapper](https://github.com/zuritor/jikanjs) by zuritor (Sven) - [Jikan4java - Wrapper](https://github.com/Doomsdayrs/Jikan4java) by Doomsdayrs - [Jikan-php - Wrapper](https://github.com/janvernieuwe/jikan-jikanPHP) by Jan Vernieuwe - [Jikan-node - Wrapper](https://github.com/xy137/jikan-node) by xy137 # Information ## 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/bots/etc that make consistent amount of requests. **If you're using the API for making bulk requests, keep a 3 second delay between each request. Abuse of the API will result in an IP ban.** ## Response Schema 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 in **ISO8601** format and in **UTC** ## Caching User related requests are cached for **5 minutes** All other requests are cached for **6 hours** - `request_cached` (bool) will tell you whether the request is cached - `request_cache_expiry` is the cache TTL in seconds ## Allowed HTTP(s) requests 
GET: All requests are done via GET
# Response Headers - 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 # Errors If you get an error response, it'll be within the `error` field. Here's an example: ``` {"error": "Something Happened"} ``` Here's a list of errors you can get and what you could do to over come them. Appropriate status headers are sent. ### Invalid extended request / Unsupported parse request Check each method for their proper extended requests. For example `/episodes` may exist for anime, but it doesn't exist for manga. ### Invalid or incomplete endpoint The endpoint you requested either does not exist or you did not make a proper request. ### Bad Request Same as above ### Other errors If there's any 404s or the parser is unable to complete the request, you'll get the appropriate status and header for that error. # Disclaimer - Jikan is not affiliated with MyAnimeList. - Jikan is a **free**, open-source API. Use it responsibly. - **Any abuse of the REST API instance will lead to temporary IP blocks!** # 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 1. Use the `ETag` value as a header value for `If-None-Match` for future requests 2. If the content has changed, you will get a `304 - Not Modified` header response, otherwise `200 - OK` ![Cache Validation](https://i.imgur.com/925ozVn.png "Cache Validation") ## Anime [/anime/{id}/{request}/{parameter}] A single anime object with all its details ### Requests | Request | Parameter | Description | | ------------- | ------------- | ------------- | | characters_staff | N/A | Fetches the list of characters & staff members of the anime | | episodes | Page number (integer) | Fetches the list of episodes of the anime | | news | N/A | News related to the item | | pictures | N/A | Pictures related to the item | | videos | N/A | PV & episodes (if any) 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 | #### Remarks - 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. - Only 20 items are shown per page for reviews ### Example Calls - `/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 ### Anime Request Example+Schema [GET] + Parameters + id (required, Number, `1`) ... Returns the Anime details from that the ID + request (optional, String, `episodes`) ... More details such as characters, staff, episodes + parameter (optional, Number, `2`) ... Anime with more than 100 episodes are paginated, hence this parameter is required. + Response 200 (application/json) [ ] ## Manga [/manga/{id}/{request}] 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 [GET] + Parameters + id (required, Number, `1`) ... Returns the Character details from that the ID + request (optional, String, `characters`) ... More details such as characters + Response 200 (application/json) [ ] ## Person [/person/{id}/{request}] A single person object with all its details ### Requests | Request | Parameter | Description | | ------------- | ------------- | ------------- | | pictures | N/A | Pictures related to the item | ### Person Request Example+Schema [GET] + Parameters + id (required, Number, `1`) ... Returns the Person details from that the ID + request (optional, String, `pictures`) ... Pictures related to the item + Response 200 (application/json) [ ] ## Character [/character/{id}/{request}] A single character object with all its details ### Requests | Request | Parameter | Description | | ------------- | ------------- | ------------- | | pictures | N/A | Pictures related to the item | ### Character Request Example+Schema [GET] + Parameters + id (required, Number, `1`) ... Returns the Character details from that the ID + request (optional, String, `pictures`) ... Pictures related to the item + Response 200 (application/json) [ ] ## Search [/search/{type}/?q=Fate/Zero&page=1] Search results for the query **NOTE: MyAnimeList only processes queries with a minimum of 3 letters** ### Parameters | Parameter | Argument | Description | | ------------- | ------------- | ------------- | | type | anime, manga, person, character | Specify where to search | | query **(v2 only)** | STRING | Query you want 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 **(required for v3+)** | STRING | For UTF8 characters, percentage encoded and queries including back slashes | | page | INTEGER | Page number | | type | `tv` `ova` `movie` `special` `ona` `music` `manga` `novel` `oneshot` `doujin` `manhwa` `manhua` | Filter type of results | | status | `airing` `completed` `complete` (alias) `tba` `upcoming` (alias) | Filter status of results | | rated | `g` `pg` `pg13` `r17` `r` `rx` | Filter age rating of results - [View Meaning](https://jikan.moe/docs#advanced-search-rating-constants) | | genre | INTEGER : 1-43 | These values reflect the genre IDs of MyAnimeList - [View Values](https://jikan.moe/docs#advanced-search-genre-constants) | | score | FLOAT : 0.0-10.0 | Filter score of results | | start_date | ISO8601 | Filter start date of results | | end_date | ISO8601 | Filter end date of results | | genre_exclude | boolean : 0/1 | To exlude/include the `genre` you added in your request | ### Search Filters | Parameter | Argument | Description | | ------------- | ------------- | ------------- | | limit | INTEGER | Limits item results to the amount specified | #### 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 [GET] + Parameters + type (required, String, `anime`) ... Returns result from anime search + Response 200 (application/json) [ ] ## Season [/season/{year}/{season}] 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 [GET] + Parameters + year (required, Integer, `2018`) ... Returns anime of the year + season (required, String, `winter`) ... Returns anime of the season + Response 200 (application/json) [ ] ## Season Archive [/season/archive] All the years & their respective seasons that can be parsed from MyAnimeList ### Season Archive Request Example+Schema [GET] + Response 200 (application/json) [ ] ## Season Later [/season/later] Anime that have been announced for the upcoming seasons ### Season Later Request Example+Schema [GET] + Response 200 (application/json) [ ] ## Schedule [/schedule/{day}] 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 [GET] + Parameters + day (optional, String, `monday`) ... Returns scheduled anime of that specific day + Response 200 (application/json) [ ] ## Top [/top/{type}/{page}/{subtype}] 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 [GET] + Parameters + type (required, String, `anime`) ... Returns top items of this type + page (optional, Integer, `1`) ... Pagination support + subtype (optional, String, `upcoming`) ... Returns top items of this type filtered by their subtypes + Response 200 (application/json) [ ] ## Genre [/genre/{type}/{genre_id}/{page}] 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 [GET] + Parameters + type (required, String, `anime`) ... Returns anime/manga items of this genre + genre_id (optional, Integer, `1`) ... Genre ID + page (optional, Integer, `1`) ... Pagination + Response 200 (application/json) [ ] ## Producer [/producer/{producer_id}/{page}] Anime by this Producer/Studio/Licensor ### Parameters | Parameter | Argument | Description | | ------------- | ------------- | ------------- | | producer_id | INTEGER | Producer ID from MyAnimeList | | page (optional) | | ### Producer Request Example+Schema [GET] + Parameters + producer_id (optional, Integer, `1`) ... Producer ID + page (optional, Integer, `1`) ... Pagination + Response 200 (application/json) [ ] ## Magazine [/magazine/{magazine_id}/{page}] Manga by this Magazine/Serializer/Publisher ### Parameters | Parameter | Argument | Description | | ------------- | ------------- | ------------- | | magazine_id | INTEGER | Magazine ID from MyAnimeList | | page (optional) | | ### Magazine Request Example+Schema [GET] + Parameters + magazine_id (optional, Integer, `1`) ... Magazine ID + page (optional, Integer, `1`) ... Pagination + Response 200 (application/json) [ ] ## User [/user/{username}/{request}/{argument}] 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 | `all`, `watching`, `completed`, `onhold`, `dropped`, `plantowatch`, `ptw` (alias) | | mangalist | `all`, `reading`, `completed`, `onhold`, `dropped`, `plantoread`, `ptr` (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 [GET] + Parameters + username (required, string, `Nekomata1037`) ... Username on MyAnimeList + request (optional, string, `history`) ... Request + argument (optional, string, `anime`) ... Request argument + Response 200 (application/json) [ ] ## Club [/club/{id}/{request}] 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 [GET] + Parameters + id (required, Number, `1`) ... Returns the Club details from that the ID + request (optional, String, `members`) ... Return club members + Response 200 (application/json) [ ] ## Meta [/meta/{request}/{type}/{period}] 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 [GET] + Parameters + request (required, String, `requests`) ... + type (required, String, `anime`) ... + period (required, String, `today`) ... + Response 200 (application/json) [ ]