npm

npm’s 2019 JavaScript ecosystem survey analysis is now available! Get your copy here »

mal-scraper

2.6.0 • Public • Published

MalScraper

Build Status Codecov License

At the moment, MalScraper allows one to:

  • Gather information about all the anime being released in a season.
  • Gather anime-related news (include light-novels, manga, films...). 160 news available.
  • Make an anime search (in 2 different ways!).
  • Get different information for this anime.
  • Get only the best result for an anime search.
  • Get a list of an anime's episodes.
  • Access the full official MyAnimeList API (includes search, add, update and delete from your user watch lists).

MalScraper is being developed mainly for KawAnime but anyone can use it for its own purpose.

Any contribution is welcomed.

Tables of content:

Installation

npm install --save mal-scraper

Use

const malScraper = require('mal-scraper')

Methods

search.search()

Parameter Type Description
type string type of search (manga or anime)
opts object options for search (all keys are optional)

Usage example:

const malScraper = require('mal-scraper')
const search = malScraper.search
 
const type = 'anime'
 
// Helpers for types, genres and list you might need for your research
console.log(search.helpers)
 
search.search(type, {
  // All optionnals, but all values must be in their relative search.helpers.availableValues.
  maxResults: 100, // how many results at most (default: 50)
  has: 250, // If you already have results and just want what follows it, you can say it here. Allows pagination!
 
  term: 'Sakura', // search term
  type: 0, // 0-> none, else go check search.helpers.availableValues.type
  status: 0, // 0 -> none, else go check https://github.com/Kylart/MalScraper/blob/master/README.md#series-statuses-references or search.helpers.availableValues.status
  score: 0, // 0-> none, else go check search.helpers.availableValues.score
  producer: 0, // go check search.helpers.availableValue.p.<type>.value
  rating: 0, // 0-> none, else go check search.helpers.availableValues.r
  startDate: {
    day: 12,
    month: 2,
    year: 1990
  },
  endDate: {
    day: 12,
    month: 2,
    year: 2015
  },
  genreType: 0, // 0 for include genre list, 1 for exclude genre list
  genres: [1] // go check search.helpers.availableValues.genres.<type>.value
})
  .then(console.log)
  .catch(console.error)

Returns: A Anime search model object

getInfoFromName()

Parameter Type Description
Name string The name of the anime to search, the best match corresponding to that name will be returned

Usage example:

const malScraper = require('mal-scraper')
 
const name = 'Sakura Trick'
 
malScraper.getInfoFromName(name)
  .then((data) => console.log(data))
  .catch((err) => console.log(err))

Returns: A Anime data model object

getInfoFromURL()

This method is faster than getInfoFromName() as it only make one HTTP request

Parameter Type Description
URL string The URL to the anime

Usage example:

const malScraper = require('mal-scraper')
 
const url = 'https://myanimelist.net/anime/20047/Sakura_Trick'
 
malScraper.getInfoFromURL(url)
  .then((data) => console.log(data))
  .catch((err) => console.log(err))

Returns: A Anime data model object (same as getInfoFromName())

getResultsFromSearch()

Parameter Type Description
query string The search query

Usage example:

const malScraper = require('mal-scraper')
 
const query = 'sakura'
 
malScraper.getResultsFromSearch(query)
  .then((data) => console.log(data))
  .catch((err) => console.log(err))

Returns: An array of a maximum length of 10 containing Search result data model objects

getSeason()

This method get the list of anime, OVAs, movies and ONAs released (or planned to be released) during the season of the specified year

Parameter Type Description
year number The year
season string The season, must be either spring, summer, fall or winter

Usage example:

const malScraper = require('mal-scraper')
 
const year = 2017
const season = 'fall'
 
malScraper.getSeason(year, season)
  // `data` is an object containing the following keys: 'TV', 'OVAs', 'ONAs', 'Movies' and 'Specials'
  .then((data) => console.log(data))
  .catch((err) => console.log(err))

Returns: A Seasonal release data model object

getWatchListFromUser()

From v2.6.0

Parameter Type Description
username string The name of the user
after number Useful to paginate. Is the number of results you want to start from. By default, MAL returns 300 entries only.
type string Optional, can be either anime or manga

Usage example:

const malScraper = require('mal-scraper')
 
const username = 'Kylart'
const after = 25
const type = 'anime' // can be either `anime` or `manga`
 
// Get you an object containing all the entries with status, score... from this user's watch list
malScraper.getWatchListFromUser(username, after, type)
  .then((data) => console.log(data))
  .catch((err) => console.log(err))

Returns: A User watch list data model object

v2.5.2 and before

Parameter Type Description
username string The name of the user
type string Optional, can be either anime or manga

Usage example:

const malScraper = require('mal-scraper')
 
const username = 'Kylart'
const type = 'anime' // can be either `anime` or `manga`
 
// Get you an object containing all the entries with status, score... from this user's watch list
malScraper.getWatchListFromUser(username, type)
  .then((data) => console.log(data))
  .catch((err) => console.log(err))

Returns: A User watch list data model object

getNewsNoDetails()

Parameter Type Description
nbNews number The count of news you want to get, default is 160. Note that there is 20 news per page, so if you set it to 60 for example, it will result in 3 requests. You should be aware of that, as MyAnimeList will most likely rate-limit you if more than 35-40~ requests are done in a few seconds

Usage example:

const malScraper = require('mal-scraper')
 
const nbNews = 120
 
malScraper.getNewsNoDetails(nbNews)
  .then((data) => console.log(data))
  .catch((err) => console.log(err))

Returns: An array of News data model objects

getEpisodesList()

Parameter Type Description
anime object OR string If an object, it must have the name and id property. If you only have the name and not the id, you may call the method with the name as a string, this will be slower but the id will be automatically fetched on the way
anime.name string The name of the anime
anime.id number The unique identifier of this anime

Usage example:

const malScraper = require('mal-scraper')
 
malScraper.getEpisodesList({
  name: 'Sakura Trick',
  id: 20047
})
  .then((data) => console.log(data))
  .catch((err) => console.log(err))
 
//Alternatively, if you only have the name and not the id, you can let the method fetch the id on the way at the cost of being slower
 
const name = "Sakura Trick"
 
malScraper.getEpisodesList(name)
  .then((data) => console.log(data))
  .catch((err) => console.log(err))

Returns: An array of Anime episodes data model objects

Official API constructor

This requires a valid MyAnimeList account

MalScraper also provide a full coverage of MyAnimeList's official API. The official API methods are available once you initialized the officialApi constructor

Parameter Type Description
credentials object Object of a MAL account credentials
credentials.username string The username of the account to use for the official API
credentials.password string The password of the account to use for the official API

Usage example:

const malScraper = require('mal-scraper')
 
const api = new malScraper.officialApi({
  username: 'my_super_username',
  password: 'my_super_secret_password'
})

checkCredentials()

This method allows you to check if the credentials given in the constructor are valid

Usage example:

const malScraper = require('mal-scraper')
 
const api = new malScraper.officialApi({
  username: 'my_super_username',
  password: 'my_super_secret_password'
})
 
api.checkCredentials()
  .then((data) => console.log(data))
  .catch((err) => console.log(err))

Returns: A string "Invalid credentials" if the credentials are invalid, otherwise, the raw XML document with the id and the username of the account

search()

Parameter Type Description
type string The type, can be either manga or anime. Default is anime
name string The name of the manga/anime to search
const malScraper = require('mal-scraper')
 
const api = new malScraper.officialApi({
  username: 'my_super_username',
  password: 'my_super_secret_password'
})
 
const name = 'Sakura Trick'
const type = 'manga'
 
// type can be either 'anime' or 'manga'
api.search(type, name)
  .then((data) => console.log(data))
  .catch((err) => console.log(err))

Returns: An array of anime search results data model or manga search results data model objects

actOnList()

This method allows you to act on the account given in the constructor anime list

Parameter Type Description
action object An object which should contain the type of the manga/anime and the action to do
action.support string The type of the manga/anime to act on. Can be either anime or manga
action.action string The action to do, can be either add, update or delete
id number The unique identifier of the manga/anime
name string The name of the manga/anime to search
details object An object that can contain all the properties described here
details.episodes number Anime only - Number of episodes you watched
details.status number OR string Whether you completed, dropped... the anime/manga, see the statuses references
details.score number The score you would give to this anime/manga, must be a whole number between 0 and 10
details.times_rewatched number Anime only - Number of times you re-watched the anime
details.date_start string mmddyyyy date format of when you finished the anime/manga
details.date_finish string mmddyyyy date format of when you finished the anime/manga
details.tags string Tags separated by commas that you think correspond to this anime/manga
details.volumes number Manga only - Number of volumes you read
details.times_reread number Manga only - Number of times you re-read this manga
const malScraper = require('mal-scraper')
 
const api = new malScraper.officialApi({
  username: 'my_super_username',
  password: 'my_super_secret_password'
})
 
const id = 20047
 
api.actOnList({
  support: 'anime',
  action: 'add' 
}, id, {
  status: 1,
  score: 10
})

Data models

Anime data model

You should treat all properties as possibly undefined/empty, the only guaranteed properties are title, type and id

Property Type Description
title string The title of the anime
synopsis string The synopsis of the anime
picture string The URL of the cover picture of the anime
characters array An array of Character data model objects
staff array An array of Staff data model objects
trailer string URL to the embedded video
englishTitle string The english title of the anime
synonyms string A list of synonyms of the anime title (other languages names, related ovas/movies/animes) separated by commas, like "Sakura Trick, Sakura Trap"
type string The type of the anime, can be either TV, OVA, Movie or Special
episodes string The number of aired episodes
status string The status of the anime (whether it is airing, finished...)
aired string The date from which the airing started to the one from which it ended, this property will be empty if one of the two dates is unknown
premiered string The date of when the anime has been premiered
broadcast string When the anime is broadcasted
producers array An array of the anime producers
studios array An array of the anime producers
source string On what the anime is based on (e.g: based on a manga...)
genres array An array of the anime genres (Action, Slice of Life...)
duration string Average duration of an episode (or total duration if movie...)
rating string The rating of the anime (e.g: R18+..), see the List of possible ratings
score string The average score
scoreStats string By how many users this anime has been scored, like "scored by 255,693 users"
ranked string The rank of the anime
popularity string The popularity of the anime
members string How many users are members of the anime (have it on their list)
favorites string Count of how many users have this anime as favorite
id number The unique identifier of the anime
url string the URL to the page

List of possible ratings

Anime ratings can be either:

  • G - All Ages
  • PG - Children
  • PG-13 - Teens 13 or older
  • R - 17+ (violence & profanity)
  • R+ - Mild Nudity
  • Rx - Hentai

Anime search model

Property Type Description
thumbnail string Full url for anime thumbnail
url string Full url for anime page
video string full url of anime trailer video if any
shortDescription string Short description of the anime (or manga)
title string Anime title
type string Anime type
nbEps string Anime number of episodes
score string Anime score
startDate string Anime start date
endDate string Anime end date
members string Anime number of members
rating string Anime rating

Staff data model

Property Type Description
link string Link to the MAL profile of this person
picture string Link to a picture of the person at the best possible size
name string Their name and surname, like Surname, Name
role string The role this person has/had in this anime (Director, Sound Director...)

Character data model

Property Type Description
link string Link to the MAL profile of this character
picture string Link to a picture of the character at the best possible size
name string Their name and surname, like Surname, Name
role string The role this person has/had in this anime (Main, Supporting...)
seiyuu object An object containing additional data about who dubbed this character
seiyuu.link string Link to the MAL profile of who dubbed this character
seiyuu.picture string Link to a picture of the seiyuu at the best possible size
seiyuu.name string Their name and surname, like Surname, Name

Search result data model

Property Type Description
id number The unique identifier of this result
type string The type of the result (e.g: anime...)
name string The title of the anime
url string The URL to the anime
image_url string URL of the image
thumbnail_url string URL of the thumbnail image
es_score number A number representing the accuracy of the result, where 1 is a perfect match and 0 a totally irrelevant one
payload object An object containing additional data about the anime
payload.media_type string The type of the anime, can be either TV, Movie, OVA or Special
payload.start_year number The year the airing of the anime started
payload.aired string The date from which the airing started to the one from which it ended
payload.score string The average score given to this anime
payload.status string The current status of the anime (whether it is still airing, finished...)

Seasonal release data model

Note: If nothing is found for the given date, the current year/season releases list will be returned

Property Type Description
TV array An array of Seasonal anime release data model objects
OVAs array An array of Seasonal anime release data model objects
ONAs array An array of Seasonal anime release data model objects
Movies array An array of Seasonal anime release data model objects
Specials array An array of Seasonal anime release data model objects

Seasonal anime release data model

Property Type Description
picture string Link to the picture of the anime
synopsis string The synopsis of the anime
licensor string The licensor
title string The name of the anime
link string The direct link to the anime page
genres array An array of strings which are the genres of this anime
producers array An array of strings which are the producers of this anime
fromType string From what this anime is based on/an adaptation of (Light novel, manga...)
nbEp string The number of aired episodes this anime has
releaseDate string When this anime has been released
score string The average score users have given to this anime

User watch list data model

v2.6.0

An array of User anime entry data model objects or User manga entry data model

v2.5.2 and before

Property Type Description
stats object A User stats data model object
lists array An array of User anime entry data model objects or User manga entry data model

User stats data model

Property Type Description
TV string Number of TV anime this user watched
OVA string Number of OVA anime this user watched
Movies string Number of Movies anime this user watched
Spcl string Number of special anime this user watched
ONA string Number of ONA anime this user watched
Days string Number of days spent in front of anime for this user
Eps string Number of eps watched by this user
MeanScore string Mean score given by this user
ScoreDev string Score deviation for this user

User anime entry data model

Property Type Description
status integer Status of the anime in the user's watch list (completed, on-hold...), see the Statuses references
score integer Score given by the user
tags string anime tags for this anime. Tags are separated by a comma
isRewatching integer Whther this user is rewatching this anime
numWatchedEpisodes: integer Number of episodes this user watched for this anime
animeTitle string The title of the anime
animeNumEpisodes integer How many episodes this anime has
animeAiringStatus string The status of the anime, see the Series statuses references
animeId string The unique identifier of this anime
animeStudios string Studios of this anime
animeLicensors string Who licensed this anime
animeSeason string ???
hasEpisodeVideo boolean Whether episode information are available on MAL
hasPromotionVideo boolean Whether anime trailer is available on MAL
videoUrl string path to video url on MAL
animeUrl string path to anime url on MAL
animeImagePath string path to anime thumbnail url on MAL
isAddedToList boolean ???
animeMediaTypeString string Type of this anime
animeMpaaRatingString string Rating of this anime
startDateString string When did this user start watching it
finishDateString string When did this user finish it
animeStartDateString string Start date of the anime following the format (MM-DD-YYYY)
animeEndDateString string End date of the anime following the format (MM-DD-YYYY)
daysString string ???
storageString string Storage type for this anime (set by the user)
priorityString string Priority of this anime for the user

User manga entry data model

Property Type Description
myID string Deprecated
status string Status of the manga in the user's watch list (completed, on-hold...), see the Statuses references
score string The score the user has given to this manga
tags string The tags the user has given to this manga
isRereading string Whether the user is re-reading this manga or not, where 0 means not
nbReadChapters string Count of how many chapters of this manga the user has read
nbReadVolumes string Count of how many volumes of this manga the user has read
mangaTitle string The title of the manga
mangaNumChapters string Total count of chapters this manga has
mangaNumVolumes string Count of volumes this manga has
mangaPublishingStatus string The status of the manga, see the Series statuses references
mangaId string The unique identifier of this manga
mangaMagazines string Magazines where this manga airs
mangaUrl string Path to manga page
mangaImagePath string path to manga thumbnail
isAddedToList boolean ???
mangaMediaTypeString string The type of the manga, see the Types references
startDateString string A mm-dd-yyyy format date of when the user started watching this manga
finishDateString string A mm-dd-yyyy format date of when the user finished watching this manga
mangaStartDateString string A mm-dd-yyyy format date of when the manga started
mangaEndDateString string A mm-dd-yyyy format date of when the manga ended
daysString string ???
retailString string ???
priorityString string Priority of this manga for the user

The types, statuses and series statuses aren't explicitly given by MyAnimeList, a number is given instead, here's the corresponding statuses/types according to their numbers

Types references

  • 0: Unknown
  • 1: TV | Manga
  • 2: OVA | Novel
  • 3: Movie | One-shot
  • 4: Special | Doujinshi
  • 5: ONA | Manhwha
  • 6: Music | Manhua

Statuses references

  • 1: Watching | Reading
  • 2: Completed
  • 3: On-hold
  • 4: Dropped
  • 6: Plan-to-watch | Plan-to-read

Series statuses references

  • 1: Currently airing | Publishing
  • 2: Finished airing | Finished
  • 3: Not yet aired | Not yet published

News data model

Property Type Description
title string The title of the news
link string The link to the article
image string URL of the cover image of the article
text string A short preview of the news description
newsNumber string The unique identifier of the news

Anime episodes data model

Property Type Description
epNumber number The episode number
aired string A "Jan 10, 2014" date like of when the episode has been aired
discussionLink string -
title string The title of the episode
japaneseTitle string The japanese title of the episode

Anime search results data model

Property Type Description
id string The unique identifier of this anime
title string The title of the anime
english string The english title of the anime
synonyms string A set of synonyms of this anime
episodes string The total count of aired episodes this anime has
score string The average score given by users to this anime
type string The type of the anime (TV, OVA...)
status string The status of the anime (Airing, Finished airing...)
start_date string A yyyy-mm-dd date format of when the anime started to be aired
end_date string A yyyy-mm-dd date format of when the anime finished
synopsis string The synopsis of the anime
image string URL to the cover image of the anime

Manga search results data model

Property Type Description
id string The unique identifier of this manga
title string The title of the manga
english string The english title of the manga
synonyms string A set of synonyms of this manga
chapters string The total count of chapters this manga has
volumes string The total count of volumes this manga has
score string The average score given by users to this manga
type string The type of the manga (Manga, Doujinshi...)
status string The status of the manga (Publishing, Finished...)
start_date string A yyyy-mm-dd date format of when the manga started publication
end_date string A yyyy-mm-dd date format of when the manga finished
synopsis string The synopsis of the manga
image string URL to the cover image of the manga

Contributing

  1. Fork it!
  2. Create your feature branch: git checkout -b my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request.

License

MIT License

Copyright (c) Kylart

install

npm i mal-scraper

Downloadsweekly downloads

1,684

version

2.6.0

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability