2018-09-07 19:28:57 +05:00
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 Parser](https://github.com/jikan-me/jikan)
Base URL: `https://api.jikan.moe/v3`
[Status](https://status.jikan.moe) | [Bug Report](https://github.com/jikan-me/jikan/issues/new) | **[Discord](https://discord.gg/dDMxFmz)**
## Announcement - 2nd Sept, 2019
**2nd September, 2018**
REST v3 has been released. There's a lot of changes and additions!
- [News Post](https://myanimelist.net/forum/?topicid=1616529&show=50#msg55620086)
- "Extended Requests" are **NO LONGER** supported in v3
- [MIGRATION NOTES](https://github.com/jikan-me/jikan-rest/blob/master/MIGRATION.MD)
From **1st January, 2019**
- `api.jikan.moe` will point towards the latest v3 endpoint
- "Extended Request" will be depreciated in V2.
## 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)
- [JikanPHP - Source](https://github.com/jikan-me/jikan/)
- [JikanPy - Wrapper](https://github.com/AWConant/jikanpy) by Andrew Conant
- [Jikan.rb - Wrapper](https://github.com/Zerocchi/jikan.rb) by Zerocchi
- [Jikan.Net - Wrapper](https://github.com/Ervie/jikan.net) by Ervie
- [JikanJs - Wrapper](https://github.com/zuritor/jikanjs) by zuritor (Sven)
# 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
All 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
<pre>
GET: All requests are done via GET
</pre>
# Response Headers
- 200 `OK` - the request was successful.
- 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
# 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!**
## 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 |
**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.
### 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 |
### Example Calls
- `/manga/1/characters` // Returns the list of characters and staff
### 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]
2018-09-07 21:24:03 +05:00
Search results for the query
2018-09-07 19:28:57 +05:00
**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)
[
]
## Schedule [/schedule/{day}]
2018-09-07 21:24:03 +05:00
Anime schedule of the week or specified day
2018-09-07 19:28:57 +05:00
**Note:** If you don't pass the `day` parameter, it'll return the schedule for **all** days of the week
### Parameters
| Parameter | Argument | Description |
| ------------- | ------------- | ------------- |
2018-09-07 21:24:03 +05:00
| day (optional) | `monday` `tuesday` `wednesday` `thursday` `friday` `saturday` `sunday`, `other` **(v3)**, `unknown` **(v3)** | Anime scheduled for that specific day |
2018-09-07 19:28:57 +05:00
### 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}]
2018-09-07 21:24:03 +05:00
Anime/Manga items of the genre
2018-09-07 19:28:57 +05:00
**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 [/producer/{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.
### Parameters
| Parameter | Argument | Description |
| ------------- | ------------- | ------------- |
| username | string | Username on MyAnimeList |
| request | `profile`, `history`, `friends` | |
| data (optional) | Additional data for `history` and `friends` |
#### 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 |
#### 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)
### 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)
[
]
## 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)
[
]
