Bangumi - Documentation

new Bangumi(optionsopt)

Source:

bangumi.js, line 17

Parameters:

Name Type Attributes Description

options

object

Name	Type	Attributes	Description
`app_id`	`string`	<optional>	app id used for identify source, deprecated
`access_token`	`string`	<optional>	access token used for identify user
`protocol`	`string`	<optional>	http protocol used for api
`user_agent`	`string`	<optional>	custom useragent, see https://github.com/bangumi/api/blob/master/docs-raw/user%20agent.md for more information

Example

const Bangumi = require('bangumi');
const bgm = new Bangumi({
  access_token: "123456"
});

Methods

auth(params, callbackopt) → {Promise}

A POST method that login user with username and password, and returns auth string

Deprecated:

since version 1.0.0, newer version of api will use oauth.

Source:

bangumi.js, line 381

Parameters:

Name Type Attributes Description

params

object

Name	Type	Description
`username`	`string`	username or uid of target username
`password`	`string`	password for target user

callback function <optional> callback function

Returns:

Type:: Promise

createCollection(subject_id, paramsopt, callbackopt) → {Promise}

A POST method that updates user's status on specific subject by subject id

Source:

bangumi.js, line 416

Parameters:

Name Type Attributes Description

subject_id number id of target subject

params

object

Name	Type	Attributes	Default	Description
`status`	`string`	<optional>	wish	accept [wish\|collect\|do\|on_hold\|dropped]
`comment`	`string`	<optional>		comment on target subject status update
`tags`	`string`	<optional>		tags on target subject status update, separated by comma
`rating`	`number`	<optional>		star rating on target subject, accept [0~10]
`privacy`	`number`	<optional>		privacy control of this action, accepts [0\|1] (0.open, 1.private)

callback function <optional> callback function

Returns:

Type:: Promise

Example

bgm.createCollection(211567, {status: 'do', rating: 10});

fetchCalendar(callbackopt) → {Promise}

A GET method that gets current weekly shows' seclude

Source:

bangumi.js, line 224

Parameters:

Name	Type	Attributes	Description
`callback`	`function`	<optional>	callback function

Returns:

Type:: Promise

fetchCollection(subject_id, paramsopt, callbackopt) → {Promise}

A GET method that get current user's collection details on specific subject by subject id

Source:

bangumi.js, line 397

Parameters:

Name Type Attributes Description

subject_id number id of target subject

params

object

Name	Type	Attributes	Description
`auth`	`string`	<optional>	authentication string used for validation of user identity, deprecated

callback function <optional> callback function

Returns:

Type:: Promise

Example

bgm.fetchCollection(1);

fetchEps(subject_id, callbackopt) → {Promise}

A GET method that gets a list of episodes of a subject by subject id

Deprecated:

use fetchSubjectEps

Source:

bangumi.js, line 261

Parameters:

Name	Type	Attributes	Description
`subject_id`	`number`		id of target subject
`callback`	`function`	<optional>	callback function

Returns:

Type:: Promise

fetchProgress(username, paramsopt, callbackopt) → {Promise}

A GET method that get lists of episodes that user already watched, sorted by subject id

Source:

bangumi.js, line 366

Parameters:

Name Type Attributes Description

username string | number username or uid of target username

params

object

Name	Type	Attributes	Description
`subject_id`	`number`	<optional>	the id of the subject user wants fetch progress
`auth`	`string`	<optional>	authentication string used for validation of user identity, deprecated

callback function <optional> callback function

Returns:

Type:: Promise

Example

bgm.fetchProgress(1, {subject_id:899}).then(console.log);

fetchSubject(subject_id, paramsopt, callbackopt) → {Promise}

A GET method that gets a details of a subject by id

Source:

bangumi.js, line 248

Parameters:

Name Type Attributes Description

subject_id number id of target subject

params

object

Name	Type	Attributes	Description
`responseGroup`	`string`	<optional>	accept [small\|medium\|large]

callback function <optional> callback function

Returns:

Type:: Promise

fetchSubjectEps(subject_id, callbackopt) → {Promise}

A GET method that gets a list of episodes of a subject by subject id

Source:

bangumi.js, line 273

Parameters:

Name	Type	Attributes	Description
`subject_id`	`number`		id of target subject
`callback`	`function`	<optional>	callback function

Returns:

Type:: Promise

Example

bgm.fetchSubjectEps(211567);

fetchUser(username, callbackopt) → {Promise}

A GET method that gets target user's profile

Source:

bangumi.js, line 235

Parameters:

Name	Type	Attributes	Description
`username`	`string` \| `number`		username or uid of target username
`callback`	`function`	<optional>	callback function

Returns:

Type:: Promise

fetchUserCollection(username, params, callbackopt) → {Promise}

A GET method that gets details of user's collection by user id

Source:

bangumi.js, line 290

Parameters:

Name Type Attributes Description

username string username or uid of target username

params

object

Name	Type	Attributes	Description
`cat`	`string`		type of the collections, accepts [watching\|all_watching]
`responseGroup`	`string`	<optional>	type of the collections, accepts [medium\|small]
`ids`	`string`	<optional>	ids of subjects users wants to fetch, this is very poorly implemented at the moment

callback function <optional> callback function

Returns:

Type:: Promise

Example

bgm.fetchUserCollection(1, {cat:'all_watching', responseGroup: 'small'}).then(console.log)

fetchUserCollections(username, subject_type, paramsopt, callbackopt) → {Promise}

A GET method that gets overview of user's collection by username and subject type

Source:

bangumi.js, line 306

Parameters:

Name Type Attributes Description

username string username or uid of target username

subject_type string type of subject

params

object

Name	Type	Attributes	Description
`max_results`	`number`	<optional>	upper limit of amount of subjects client can fetch (max 25)

callback function <optional> callback function

Returns:

Type:: Promise

Example

bgm.fetchUserCollections('sai', 'real', {max_results: 1}).then(console.log).catch(console.error)

fetchUserCollectionsStatus(username, paramsopt, callbackopt) → {Promise}

A GET method that gets overview of user's collection statics by username

Source:

bangumi.js, line 325

Parameters:

Name	Type	Attributes	Description
`username`	`string`		username or uid of target username
`params`	`object`	<optional>
`callback`	`function`	<optional>	callback function

Returns:

Type:: Promise

Example

bgm.fetchUserCollectionsStatus('sai').then(console.log).catch(console.error)

get(url, params, callbackopt)

A general GET request method for Bangumi API

Source:

bangumi.js, line 141

Parameters:

Name	Type	Attributes	Description
`url`	`string`		base GET request path
`params`	`object`		parameters used for GET query string
`callback`	`function`	<optional>	callback function

post(url, params, callbackopt) → {Promise}

A general POST request method for Bangumi API

Source:

bangumi.js, line 211

Parameters:

Name	Type	Attributes	Description
`url`	`string`		base POST request path
`params`	`object`		parameters used for POST body
`callback`	`function`	<optional>	callback function

Returns:

Type:: Promise

search(keywords, paramsopt, callbackopt) → {Promise}

A GET method that searches and returns a list of subjects by keywords

Source:

bangumi.js, line 348

Parameters:

Name Type Attributes Description

keywords string query string for search

params

object

Name	Type	Attributes	Description
`responseGroup`	`string`	<optional>	accept [small\|medium\|large]
`type`	`number`	<optional>	accept [1\|2\|3\|4\|6] (1.book 2.anime 3.music 4.game 5.live action)
`start`	`number`	<optional>	result start index, used for paging
`max_results`	`number`	<optional>	the number of entries returns, max 25

callback function <optional> callback function

Returns:

Type:: Promise

Example

bgm.search('天元突破');

setPromiseProvider(provider)

Set custom promise provider, default using nodejs ES6 promise provider

Source:

bangumi.js, line 63

Parameters:

Name	Type	Description
`provider`	`function`	Custom promise provider

Example

//use bluebird as provider, so you can use things like .finally()
bgm.setPromiseProvider(require('bluebird'));

updateEpStatus(ep_id, status, paramsopt, callbackopt) → {Promise}

A POST method that updates user's status on specific episode by episode id

Source:

bangumi.js, line 432

Parameters:

Name Type Attributes Description

ep_id number id of target episode

status string accept [watched|queue|drop|remove]

params

object

Name	Type	Attributes	Description
`ep_id`	`string`	<optional>	a list of episode ids for batch processing, separated by comma

callback function <optional> callback function

Returns:

Type:: Promise

Example

bgm.updateEpStatus(7036,'drop');

updateWatchedEps(subject_id, params, callbackopt) → {Promise}

A POST method that marks episode 1 to target number as watched

Source:

bangumi.js, line 449

Parameters:

Name Type Attributes Description

subject_id number id of target subject

params

object

Name	Type	Attributes	Description
`watched_eps`	`string`		the number of episodes that user currently have watched
`watched_vols`	`string`	<optional>	the number of episodes that user currently have watched

callback function <optional> callback function

Returns:

Type:: Promise

Example

bgm.updateWatchedEps(18462, {watched_eps: 10, watched_vols: 2});