Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nstratos/go-myanimelist
Go library for accessing the MyAnimeList API: https://myanimelist.net/apiconfig/references/api/v2
https://github.com/nstratos/go-myanimelist
anime client-lib go go-myanimelist mal mal-client manga myanimelist myanimelist-api
Last synced: about 2 months ago
JSON representation
Go library for accessing the MyAnimeList API: https://myanimelist.net/apiconfig/references/api/v2
- Host: GitHub
- URL: https://github.com/nstratos/go-myanimelist
- Owner: nstratos
- License: mit
- Created: 2015-05-03T10:07:05.000Z (over 9 years ago)
- Default Branch: main
- Last Pushed: 2024-04-24T14:21:52.000Z (8 months ago)
- Last Synced: 2024-10-25T05:25:17.076Z (about 2 months ago)
- Topics: anime, client-lib, go, go-myanimelist, mal, mal-client, manga, myanimelist, myanimelist-api
- Language: Go
- Homepage:
- Size: 1.85 MB
- Stars: 39
- Watchers: 2
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - go-myanimelist - Go client library for accessing the [MyAnimeList API](https://myanimelist.net/apiconfig/references/api/v2). (Third-party APIs / Utility/Miscellaneous)
- awesome-go - go-myanimelist - Go library for accessing the MyAnimeList API: - ★ 14 (Third-party APIs)
- awesome-go-extra - go-myanimelist - 05-03T10:07:05Z|2022-05-31T16:42:37Z| (Third-party APIs / Fail injection)
README
# go-myanimelist
[](https://pkg.go.dev/github.com/nstratos/go-myanimelist/mal)
[](LICENSE)
[](https://goreportcard.com/report/github.com/nstratos/go-myanimelist)
[](https://coveralls.io/github/nstratos/go-myanimelist?branch=main)
[](https://github.com/nstratos/go-myanimelist/actions?query=workflow%3Atests)
[](https://github.com/nstratos/go-myanimelist/actions?query=workflow%3Aintegration)
go-myanimelist is a Go client library for accessing the [MyAnimeList API v2](https://myanimelist.net/apiconfig/references/api/v2).
## Project Status
The project has been updated to support MyAnimeList API v2.
As of March 2017, this package is featured in
[awesome-go](https://github.com/avelino/awesome-go).
## Installation
This package can be installed using:
go get github.com/nstratos/go-myanimelist/mal
## Usage
Import the package using:
```go
import "github.com/nstratos/go-myanimelist/mal"
```
First construct a new mal client:
```go
c := mal.NewClient(nil)
```
Then use one of the client's services (User, Anime, Manga and Forum) to access
the different MyAnimeList API methods.
## Authentication
When creating a new client, pass an `http.Client` that can handle authentication
for you.
### Accessing publicly available information
To access public information, you need to add the ` X-MAL-CLIENT-ID` header in
your requests. You can achieve this by creating an `http.Client` with a custom
transport and use it as shown below:
```go
type clientIDTransport struct {
Transport http.RoundTripper
ClientID string
}
func (c *clientIDTransport) RoundTrip(req *http.Request) (*http.Response, error) {
if c.Transport == nil {
c.Transport = http.DefaultTransport
}
req.Header.Add("X-MAL-CLIENT-ID", c.ClientID)
return c.Transport.RoundTrip(req)
}
func main() {
publicInfoClient := &http.Client{
// Create client ID from https://myanimelist.net/apiconfig.
Transport: &clientIDTransport{ClientID: ""},
}
c := mal.NewClient(publicInfoClient)
// ...
}
```
### Authenticating using OAuth2
The recommended way is to use the `golang.org/x/oauth2` package
(https://github.com/golang/oauth2). After completing the OAuth2 flow, you will
get an oauth2 token containing an access token, a refresh token and an
expiration date. The oauth2 token can easily be stored in JSON format and used
like this:
```go
const storedToken = `
{
"token_type": "Bearer",
"access_token": "yourAccessToken",
"refresh_token": "yourRefreshToken",
"expiry": "2021-06-01T16:12:56.1319122Z"
}`
oauth2Token := new(oauth2.Token)
_ = json.Unmarshal([]byte(storedToken), oauth2Token)
// Create client ID and secret from https://myanimelist.net/apiconfig.
//
// Secret is currently optional if you choose App Type 'other'.
oauth2Conf := &oauth2.Config{
ClientID: "",
ClientSecret: "",
Endpoint: oauth2.Endpoint{
AuthURL: "https://myanimelist.net/v1/oauth2/authorize",
TokenURL: "https://myanimelist.net/v1/oauth2/token",
AuthStyle: oauth2.AuthStyleInParams,
},
}
oauth2Client := oauth2Conf.Client(ctx, oauth2Token)
// The oauth2Client will refresh the token if it expires.
c := mal.NewClient(oauth2Client)
```
Note that all calls made by the client above will include the specified oauth2
token which is specific for an authenticated user. Therefore, authenticated
clients should almost never be shared between different users.
Performing the OAuth2 flow involves registering a MAL API application and then
asking for the user's consent to allow the application to access their data.
There is a detailed example of how to perform the Oauth2 flow and get an oauth2
token through the terminal under `example/malauth`. The only thing you need to run
the example is a client ID and a client secret which you can acquire after
registering your MAL API application. Here's how:
1. Navigate to https://myanimelist.net/apiconfig or go to your MyAnimeList
profile, click Edit Profile and select the API tab on the far right.
2. Click Create ID and submit the form with your application details.
After registering your application, you can run the example and pass the client
ID and client secret through flags:
cd example/malauth
go run main.go democlient.go --client-id=... --client-secret=...
or
go install github.com/nstratos/go-myanimelist/example/malauth
malauth --client-id=... --client-secret=...
After you perform a successful authentication once, the oauth2 token will be
cached in a file under the same directory which makes it easier to run the
example multiple times.
Official MAL API OAuth2 docs:
https://myanimelist.net/apiconfig/references/authorization
## List
To search and get anime and manga data:
```go
list, _, err := c.Anime.List(ctx, "hokuto no ken",
mal.Fields{"rank", "popularity", "my_list_status"},
mal.Limit(5),
)
// ...
list, _, err := c.Manga.List(ctx, "hokuto no ken",
mal.Fields{"rank", "popularity", "my_list_status"},
mal.Limit(5),
)
// ...
```
You may get user specific data for a certain record by using the optional field
"my_list_status".
Official docs:
- https://myanimelist.net/apiconfig/references/api/v2#operation/anime_get
- https://myanimelist.net/apiconfig/references/api/v2#operation/manga_get
## UserList
To get the anime or manga list of a user:
```go
// Get the authenticated user's anime list, filter only watching anime, sort by
// last updated, include list status.
anime, _, err := c.User.AnimeList(ctx, "@me",
mal.Fields{"list_status"},
mal.AnimeStatusWatching,
mal.SortAnimeListByListUpdatedAt,
mal.Limit(5),
)
// ...
// Get the authenticated user's manga list's second page, sort by score,
// include list status, comments and tags.
manga, _, err := c.User.MangaList(ctx, "@me",
mal.SortMangaListByListScore,
mal.Fields{"list_status{comments, tags}"},
mal.Limit(5),
mal.Offset(1),
)
// ...
```
You may provide the username of the user or "@me" to get the authenticated
user's list.
Official docs:
- https://myanimelist.net/apiconfig/references/api/v2#operation/users_user_id_animelist_get
- https://myanimelist.net/apiconfig/references/api/v2#operation/users_user_id_mangalist_get
## MyInfo
To get information about the authenticated user:
```go
user, _, err := c.User.MyInfo(ctx)
// ...
```
This method can use the Fields option but the API doesn't seem to be able to
send optional fields like "anime_statistics" at the time of writing.
Official docs:
- https://myanimelist.net/apiconfig/references/api/v2#operation/users_user_id_get
## Details
To get details for a certain anime or manga:
```go
a, _, err := c.Anime.Details(ctx, 967,
mal.Fields{
"alternative_titles",
"media_type",
"num_episodes",
"start_season",
"source",
"genres",
"studios",
"average_episode_duration",
},
)
// ...
m, _, err := c.Manga.Details(ctx, 401,
mal.Fields{
"alternative_titles",
"media_type",
"num_volumes",
"num_chapters",
"authors{last_name, first_name}",
"genres",
"status",
},
)
// ...
```
By default most fields are not populated so use the Fields option to request the
fields you need.
Official docs:
- https://myanimelist.net/apiconfig/references/api/v2#operation/anime_anime_id_get
- https://myanimelist.net/apiconfig/references/api/v2#operation/manga_manga_id_get
## Ranking
To get anime or manga based on a certain ranking:
```go
anime, _, err := c.Anime.Ranking(ctx,
mal.AnimeRankingAiring,
mal.Fields{"rank", "popularity"},
mal.Limit(6),
)
// ...
manga, _, err := c.Manga.Ranking(ctx,
mal.MangaRankingByPopularity,
mal.Fields{"rank", "popularity"},
mal.Limit(6),
)
// ...
```
Official docs:
- https://myanimelist.net/apiconfig/references/api/v2#operation/anime_ranking_get
- https://myanimelist.net/apiconfig/references/api/v2#operation/manga_ranking_get
## Add or Update List
To add or update an entry in an authenticated user's list, provide the anime or
manga ID and then options to specify the status, score, comments, tags etc.
```go
_, _, err := c.Anime.UpdateMyListStatus(ctx, 967,
mal.AnimeStatusWatching,
mal.NumEpisodesWatched(73),
mal.Score(8),
mal.Comments("You wa shock!"),
mal.StartDate(time.Date(2022, 02, 20, 0, 0, 0, 0, time.UTC)),
mal.FinishDate(time.Time{}), // Remove an existing date.
)
// ...
_, _, err := c.Manga.UpdateMyListStatus(ctx, 401,
mal.MangaStatusReading,
mal.NumVolumesRead(1),
mal.NumChaptersRead(5),
mal.Comments("Migi"),
mal.StartDate(time.Date(2022, 02, 20, 0, 0, 0, 0, time.UTC)),
mal.FinishDate(time.Time{}), // Remove an existing date.
)
// ...
```
Official docs:
- https://myanimelist.net/apiconfig/references/api/v2#operation/anime_anime_id_my_list_status_put
- https://myanimelist.net/apiconfig/references/api/v2#operation/manga_manga_id_my_list_status_put
## Delete
To delete anime or manga from a user's list, simply provide their IDs:
```go
_, err := c.Anime.DeleteMyListItem(ctx, 967)
// ...
_, err := c.Manga.DeleteMyListItem(ctx, 401)
// ...
```
Official docs:
- https://myanimelist.net/apiconfig/references/api/v2#operation/anime_anime_id_my_list_status_delete
- https://myanimelist.net/apiconfig/references/api/v2#operation/manga_manga_id_my_list_status_delete
## More Examples
See package examples:
https://pkg.go.dev/github.com/nstratos/go-myanimelist/mal#pkg-examples
## Unit Testing
To run all unit tests:
go test -cover
To see test coverage in your browser:
go test -covermode=count -coverprofile=count.out && go tool cover -html count.out
## Integration Testing
The integration tests will exercise the entire package against the live
MyAnimeList API. As a result, these tests take much longer to run and there is
also a much higher chance of false positives in test failures due to network
issues etc.
These tests are meant to be run using a dedicated test account that contains
empty anime and manga lists. A valid oauth2 token needs to be provided every
time. Check the authentication section to learn how to get one.
By default the integration tests are skipped when an oauth2 token is not
provided. To run all tests including the integration tests:
go test --client-id='' --oauth2-token=''
## License
MIT