malhuda/jikan-rest
1
0
Fork 0
mirror of https://github.com/jikan-me/jikan-rest.git synced 2025-02-20 11:23:35 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
jikan-rest/apiary.apib

582 lines
20 KiB
Plaintext
Raw Blame History

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
<pre>
GET: All requests are done via GET
</pre>
# 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)
[
]
Reference in New Issue View Git Blame Copy Permalink