This unofficial API is a supplement to the official API. The main reasons I'm working on this are:
Please report any bugs to @sliceoflifer on Twitter.
The MyAnimeList Unofficial API allows developers to interact with the MyAnimeList site programmatically via HTTP requests.
All read methods are HTTP GET requests. Some requests require authentication. The response data format is JSON by default (see data formats for XML responses).
| Request | Description | Example |
|---|---|---|
| /animelist/username | Fetch a user's anime list | http://mal-api.com/animelist/xinil |
| /anime/anime_id | Fetch an anime's details | http://mal-api.com/anime/1887 |
| /history/username | Fetch a user's history | http://mal-api.com/history/xinil |
| /anime/search | Search for anime matching a query. | http://mal-api.com/anime/search?q=haruhi |
| /anime/top | Fetch the top anime. | http://mal-api.com/anime/top |
| /anime/popular | Fetch the popular anime. | http://mal-api.com/anime/popular |
| /anime/upcoming | Fetch the upcoming anime. | http://mal-api.com/anime/upcoming |
| /anime/just_added | Fetch the just added anime. | http://mal-api.com/anime/just_added |
| /mangalist/username | Fetch a user's manga list | http://mal-api.com/mangalist/xinil |
| /manga/manga_id | Fetch a manga's details | http://mal-api.com/anime/104 |
Check out the full documentation for these read methods below.
All write methods are HTTP POST, PUT or DELETE requests. Read the section on HTTP verb emulation if you have difficulties performing PUT or DELETE requests. Authentication is required.
| Request | Method | Description | Arguments |
|---|---|---|---|
| /animelist/anime | POST |
Add an anime to user's anime list | anime_id, status?, episodes?, score? |
| /animelist/anime/anime_id | PUT |
Update an anime already on user's anime list | status?, episodes?, score? |
| /animelist/anime/anime_id | DELETE |
Delete an anime from user's anime list | - |
Check out the full documentation for these write methods below.
All API methods are HTTP requests and support the full set of HTTP verbs - GET, POST, HEAD, PUT, DELETE. If your client doesn't support the full set of HTTP verbs and is capable of only GET and POST requests, HTTP verb emulation is also supported.
If you're using a client that only supports GET and POST requests, or making API requests from a web browser via AJAX, you'll need to fake PUT, DELETE and HEAD requests. Simply send along a _method parameter as part of your request body with the HTTP verb (case-insensitive).
For example, to emulate a HTTP DELETE to /animelist/anime/1:
POST /animelist/anime/1Request body:_method=delete
An anime list is a user's personal list of anime. It also includes statistics on a user based on her list, such as her average score given to anime and number of days spent watching anime.
Format:
anime - A list of anime.
statistics - A hash/dictionary containing statistics.
days - Number of days spent watching anime.Note that not all these properties are available in /animelist requests and will be indicated below.
id - The anime ID.title - The anime title.other_titles - A hash/dictionary containing other titles this anime has.
synonyms - A list of synonym(s) of the anime's title.english - A list of English title(s). Not available in /animelist requests.japanese - A list of Japanese title(s). Not available in /animelist requests.rank - Global rank of this anime. Not available in /animelist requests.popularity_rank - Rank of this anime based on its popularity, i.e. number of users that have added this anime. Not available in /animelist requests.image_url - URL to an image for this anime.type - Type of anime. Possible values: TV, Movie, OVA, ONA, Special, Music.episodes - Number of episodes. null is returned if the number of episodes is unknown.status - Airing status of this anime. Possible values: finished airing, currently airing, not yet aired.classification - Classification or rating of this anime. This is a freeform text field, with possible values like: R - 17+ (violence & profanity), PG - Children. Not available in /animelist requests.members_score - Weighted score members of MyAnimeList have given to this anime. Not available in /animelist requests.members_count - Number of members who have this anime on their list. Not available in /animelist requests.favorited_count - Number of members who have this anime marked as one of their favorites. Not available in /animelist requests.synopsis - Text describing the anime. Not available in /animelist requests.genres - A list of genres for this anime, e.g. ["Action", "Comedy", "Shounen"]. Not available in /animelist requests.tags - A list of popular tags for this anime, e.g. ["supernatural", "comedy"]. Not available in /animelist requests.manga_adaptations - A list of manga adaptations of this anime (or conversely, manga from which this anime is adapted). Not available in /animelist requests.
manga_id - ID of the manga.title - Title of the manga.url - URL to the manga on the MyAnimeList website.prequels - A list of anime prequels of this anime. Not available in /animelist requests.
anime_id - ID of the anime.title - Title of the anime.url - URL to the anime on the MyAnimeList website.sequels - A list of anime sequels of this anime. Not available in /animelist requests.
anime_id - ID of the anime.title - Title of the anime.url - URL to the anime on the MyAnimeList website.side_stories - A list of anime side stories of this anime. Not available in /animelist requests.
anime_id - ID of the anime.title - Title of the anime.url - URL to the anime on the MyAnimeList website.These additional properties are available for authenticated users who have the requested anime on their anime list:
watched_status - User's watched status of the anime. This is a string that is one of: watching, completed, on-hold, dropped, plan to watch.watched_episodes - Number of episodes already watched by the user.score - User's score for the anime, from 1 to 10.An anime list is a user's personal list of manga.
Format:
manga - A list of manga.
id - The manga ID.title - The manga title.other_titles - A hash/dictionary containing other titles this manga has.
synonyms - A list of synonym(s) of the manga's title.english - A list of English title(s).japanese - A list of Japanese title(s).rank - Global rank of this manga.popularity_rank - Rank of this manga based on its popularity, i.e. number of users that have added this manga.image_url - URL to an image for this manga.type - Type of manga. Possible values: Manga, Novel, One Shot, Doujin, Manwha, Manhua, OEL ("OEL manga" refers to "Original English-Language manga").chapters - Number of chapters. null is returned if the number of chapters is unknown.volumes - Number of volumes. null is returned if the number of volumes is unknown.status - Publishing status of this anime. Possible values: finished, publishing, not yet published.members_score - Weighted score members of MyAnimeList have given to this manga.members_count - Number of members who have this manga on their list.favorited_count - Number of members who have this manga marked as one of their favorites.synopsis - Text describing the manga.genres - A list of genres for this manga, e.g. ["Comedy", "Slice of Life"].tags - A list of popular tags for this manga, e.g. ["comedy", "slice of life"].anime_adaptations - A list of anime adaptations of this anime (or conversely, anime from which this manga is adapted).
anime_id - ID of the anime.title - Title of the anime.url - URL to the anime on the MyAnimeList website.related_manga - A list of related manga.
manga_id - ID of the manga.title - Title of the manga.url - URL to the manga on the MyAnimeList website.These additional properties are available for authenticated users who have the requested manga on their manga list:
read_status - User's read status of the anime. This is a string that is one of: reading, completed, on-hold, dropped, plan to read.chapters_read - Number of chapters already read by the user.volumes_read - Number of volumes already read by the user.score - User's score for the manga, from 1 to 10.The MyAnimeList Unofficial API supports both JSON and XML output formats. Specify the output format using the format parameter (JSON is the default):
http://mal-api.com/anime/1887?format=json
http://mal-api.com/anime/1887?format=xml
Authentication is required for certain API requests. The MyAnimeList Unofficial API only supports HTTP Basic Authentication because of the limitations of the MyAnimeList site.
The MyAnimeList Unofficial API takes your username and password and authenticates it with MyAnimeList directly - no passwords are saved or logged.
However, it is clearly inferior to secure solutions like OAuth and requires you to trust an unofficial API with your MyAnimeList password. It bothers us too. You can help us bug the MyAnimeList developers at the MAL API club.
The API returns appropriate HTTP status codes. In addition, the API also includes error information in the response body. Error responses have a single error property that is a string describing the error, e.g.:
{"error":"forbidden"}
An additional details property is sometimes available for further diagnostics.
Possible error codes are:
not-found - Unrecognized/missing anime/manga ID.ARG-required - The HTTP argument ARG is required for this request, e.g., anime_id-required.network-error - A network error has occurred connecting to MyAnimeList.unauthorized - The request requires authentication.forbidden - User does not have access.Fetch an anime list with the given username:
http://mal-api.com/animelist/usernameExample: http://mal-api.com/animelist/xinil
The response is an anime list.
Fetch an anime with the given anime id:
http://mal-api.com/anime/anime_idExample: http://mal-api.com/anime/1887
The response is an anime.
The following optional parameters are supported:
mine=1 - If specified, include the authenticated user's anime details (e.g. user's score, watched status, watched episodes). Requires authentication. See anime response type.NOT YET IMPLEMENTED
Fetch the history of a user with the given username.
http://mal-api.com/history/usernameExample: http://mal-api.com/history/xinil
The response is a list of anime and/or manga IDs together with the episode/chapter watched or read, and the time it was watched or read.
TODO Give an example of the response format.
To get only the user's anime history, use the http://mal-api.com/history/username/anime
To get only the user's manga history, use the http://mal-api.com/history/username/manga
Search for anime matching a query.
http://mal-api.com/anime/search?q=query
Only 1 required parameter is supported:
q - The query (URL encoded).The response is a list of anime. Only the following anime properties are available: id, title, episodes, type, synopsis, image_url, members_score, classification
NOT YET IMPLEMENTED
Fetch the top ranking anime.
http://mal-api.com/anime/top
The following optional parameters are supported:
type - Type of anime to return. Possible values: TV, Movie, OVA, Special. Defaults to nothing, which returns top anime of any type.page - Page of top anime to return. Defaults to 1, i.e. the 1st page.per_page - Number of anime to return per page. Defaults to 30.To quote MyAnimeList:
Weighted Rank (WR) = (v / (v + m)) * S + (m / (v + m)) * C
S= Average score for the Anime (mean).
v= Number of votes for the Anime = (Number of people scoring the Anime).
m= Minimum votes/scores required to get a calculated score (currently 50 scores required).
C= The mean score across the entire Anime DB.
NOT YET IMPLEMENTED
Fetch the most popular anime. The popularity of an anime is determined by the number of MyAnimeList members watching it.
http://mal-api.com/anime/popularExample: http://mal-api.com/anime/popular?page=1&per_page=30
The following optional parameters are supported:
page - Page of anime to return. Defaults to 1, i.e. the 1st page.per_page - Number of anime to return per page. Defaults to 30.NOT YET IMPLEMENTED
Fetch the upcoming anime. This is a list of anime sorted by airing date.
http://mal-api.com/anime/upcomingExample: http://mal-api.com/anime/upcoming?start_date=20090815
The following optional parameters are supported:
start_date - Only anime which air after this date (in YYYYMMDD format) are returned. Defaults to the current date in UTC.page - Page of anime to return. Defaults to 1, i.e. the 1st page.per_page - Number of anime to return per page. Defaults to 20.NOT YET IMPLEMENTED
Fetch anime that have just been added to the MyAnimeList database. The anime are sorted with the most recently added ones in front.
http://mal-api.com/anime/just_addedExample: http://mal-api.com/anime/just_added?page=1&per_page=30
The following optional parameters are supported:
page - Page of anime to return. Defaults to 1, i.e. the 1st page.per_page - Number of anime to return per page. Defaults to 20.NOT YET IMPLEMENTED
Fetch a manga list with the given username:
http://mal-api.com/mangalist/usernameExample: http://mal-api.com/mangalist/xinil
The response is a manga list.
Retrieve details for the manga with the given manga id:
http://mal-api.com/manga/manga_idExample: http://mal-api.com/manga/104
The response is an manga.
The following optional parameters are supported:
mine=1 - If specified, include the authenticated user's manga details (e.g. user's score, chapters read, volumes read). Requires authentication. See manga response type.All write methods require authentication.
Adds an anime to a user's anime list:
POST http://mal-api.com/animelist/anime
Parameters:
anime_id - required - ID of anime to add to user's animelist.status - Integer or string representing user's watched status of the anime. Possible values: 1/"watching", 2/"completed", 3/"on-hold"/"onhold", 4/"dropped", 6/"plan to watch"/"plantowatch". Default: 1/"watching"episodes - Number of episodes watched. Default: 0score - User's score for an anime. An integer from 1 to 10.Example:
POST http://mal-api.com/animelist/animeRequest body:anime_id=1887 status=watching episodes=1 score=9
Updates an anime already on a user's anime list:
PUT http://mal-api.com/animelist/anime/anime_id
Parameters:
status - Integer or string representing user's watched status of the anime. Possible values: 1/"watching", 2/"completed", 3/"on-hold"/"onhold", 4/"dropped", 6/"plan to watch"/"plantowatch". Default: 1/"watching"episodes - Number of episodes watched. Default: 0score - User's score for an anime. An integer from 1 to 10.Example:
PUT http://mal-api.com/animelist/anime/1887Request body:status=completed episodes=24 score=10
Delete an anime from a user's anime list. This removes any record of the anime from a user's anime list and cannot be undone.
DELETE http://mal-api.com/animelist/anime/anime_id
Parameters: none.
Returns: HTTP 200 OK and the original anime (this is useful for undoing a delete) if the anime was successfully deleted from animelist. Otherwise, returns appropriate HTTP response code and an error message.
Example:
DELETE http://mal-api.com/animelist/anime/1887
Test whether supplied user credentials are valid. The authentication mechanism is HTTP Basic Authentication. This method is rate-limited (the response status code will be HTTP 503 Service Temporarily Unavailable) because it can be a vector for brute force attacks.
http://mal-api.com/account/verify_credentials
The response is an HTTP 200 OK status code if authentication was successful. Otherwise, an HTTP 401 Unauthorized status code is returned.