diff options
| -rw-r--r-- | README.md | 556 |
1 files changed, 3 insertions, 553 deletions
@@ -2,564 +2,14 @@ mg is a free and open source library for accessing the official MyAnimeList V2 API using Go. All endpoints are supported except forums as of now. -If you find any bugs, please write to me at <vidhukant@vidhukant.com> +Official website & docs: <https://mg.vidhukant.com> -<https://mg.vidhukant.com> +If you find any bugs, please write to me at <vidhukant@vidhukant.com> # License Licenced under GNU General Public Licence V3 -GNU GPL License: [link](https://mikunonaka.net/mg/tree/LICENSE) +GNU GPL License: [LICENSE](https://mikunonaka.net/mg/tree/LICENSE) Copyright (c) 2022-2023 Vidhu Kant Sharma - -# Documentation - -***for v1.0.1+*** - -*Documentation might be incomplete or buggy. If you want to submit any changes, or need any help, please feel free to contact me at the given E-mail address.* - -## Initializing the mg client - -There are 2 ways to authenticate with mg: -- ClientAuth - - With ClientAuth, you just need to use your MyAnimeList Client ID to access the read-only resources. - You cannot do actions that require logging in. To use ClientAuth, set `client.ClientAuthOnly` to `true`. -- MainAuth - - With MainAuth, you can perform actions like getting recommendations, or editing an anime/manga list. - For this, you need to generate a Bearer token; for which a Client ID is still needed. - `ClientAuthOnly` must be set to `false` to use MainAuth. - -Go to <https://myanimelist.net/apiconfig> to generate your very own Client ID! - -Check out [this script](https://git.mikunonaka.net/mal-authtoken-generator/about/) -to generate an auth token, whilst I work on adding this functionality to mg! -It has been deprecated and may or may not work, but it's better than nothing! - -Also check out [this guide](https://myanimelist.net/blog.php?eid=835707) for more info; or just in case if this script doesn't work! - -``` go -package main - -import ( - "vidhukant.com/mg" -) - -func main() { - var client mg.Client - - // either this - client.MainAuth = "Bearer <your token here>" - - // or this - client.ClientAuth = "<your client id here>" - client.ClientAuthOnly = true - - // ... -} -``` - -# Anime - -## Searching for an anime - -`MainAuth` or `ClientAuth` - -``` go -// ... - -var animes []mg.Anime - -params := mg.SearchParamsNew() -params.SearchString = "mushishi" - -// optional; these are the default values -params.Limit = 100 // max = 100 -params.Offset = 0 -params.NSFW = false -params.Fields = []string{} - -err := client.SearchAnime(&animes, params) -if err != nil { - fmt.Println(err) -} - -for _, anime := range animes { - fmt.Println(anime.Title) -} - -// ... -``` - -## Getting an anime's information - -`MainAuth` or `ClientAuth` - -_searching can be a bit inaccurate, if you know the anime's ID (obtain it with SearchAnime!) and want to get detailed information, use this._ - -``` go -// ... - -var anime mg.Anime - -err := client.GetAnimeById(&anime, /*anime id*/ 457, /*fields*/ []string{}) -if err != nil { - fmt.Println(err) -} - -// ... -``` - -## Getting anime ranking list - -`MainAuth` or `ClientAuth` - -Accepted ranking types: -| Ranking Type | Description | -|----------------------------|-------------------------| -| mg.RankingTypeAll | Top Anime Series | -| mg.RankingTypeByPopularity | Top Anime by Popularity | -| mg.RankingTypeFavorite | Top Favorited Anime | -| mg.RankingTypeAiring | Top Airing Anime | -| mg.RankingTypeUpcoming | Top Upcoming Anime | -| mg.RankingTypeTV | Top Anime TV Series | -| mg.RankingTypeOVA | Top Anime OVA Series | -| mg.RankingTypeMovie | Top Anime Movies | -| mg.RankingTypeSpecial | Top Anime Specials | - -## Getting seasonal animes - -`MainAuth` or `ClientAuth` - -Accepted seasons: -- `mg.SeasonWinter` -- `mg.SeasonSpring` -- `mg.SeasonSummer` -- `mg.SeasonFall` - -Accepted sorts: -- `mg.SeasonSortByAnimeScore` (descending) -- `mg.SeasonSortByNumListUsers` (descending) - - -``` go -// ... - -var seasonals []mg.Anime - -params := mg.SeasonalParamsNew() - -params.Year = "2023" // required -params.Season = mg.SeasonFall // required - -// optional; these are the default values -params.Sort = mg.SeasonSortByAnimeScore -params.Limit = 100 // max = 500 -params.Offset = 0 -params.NSFW = false -params.Fields = []string{} - -err := client.GetSeasonalAnime(&seasonals, params) -if err != nil { - fmt.Println(err) -} - -// ... -``` - -## Getting suggested animes - -`MainAuth` only - -``` go -// ... - -var suggestedAnimes []mg.Anime - -params := mg.SuggestedParamsNew() - -// optional; these are the default values -params.Limit = 100 // max = 100 -params.Offset = 0 -params.NSFW = false -params.Fields = []string{} - -err := client.GetSeasonalAnime(&suggestedAnimes, params) -if err != nil { - fmt.Println(err) -} - -// ... -``` - -## Get any user's anime list - -`MainAuth` or `ClientAuth` - -This returns a boolean telling us if there is a next page on this user's list. -Simply increment the offset by the limit and create a new request in order to get the next page. - -In order to get the complete list, repeat the process until `nextPageExists` becomes false. - -Accepted statuses: -- `mg.ListStatusAll` -- `mg.ListStatusWatching` -- `mg.ListStatusCompleted` -- `mg.ListStatusOnHold` -- `mg.ListStatusDropped` -- `mg.ListStatusPTW` - -Accepted list sorts: -- `mg.SortByListScore` (descending) -- `mg.SortByListUpdatedAt` (descending) -- `mg.SortByAnimeTitle` (ascending) -- `mg.SortByAnimeStartDate` (descending) -- `mg.SortByAnimeId` (ascending) (beta according to MAL) - -``` go -// ... - -var animes []mg.Anime - -params := mg.ListParamsNew() - -// optional; these are the default values -params.Username = "@me" // can speciy any public account -params.Status = mg.ListStatusAll -params.Sort = mg.SortByListScore -params.Limit = 100 // max = 1000 -params.Offset = 0 -params.NSFW = false -params.Fields = []string{} - -nextPageExists, err := client.GetAnimeList(&animes, params) -if err != nil { - fmt.Println(err) -} - -// ... -``` - -## Updating an anime - -`MainAuth` only - -Updates an anime in the the currently logged in user's anime list. -Adds the anime if it's not in the list. - -Accepted statuses: -- `mg.ListStatusWatching` -- `mg.ListStatusCompleted` -- `mg.ListStatusOnHold` -- `mg.ListStatusDropped` -- `mg.ListStatusPTW` - -Score range: `0` - `10` - -Priority range: `0` - `2` -| Priority | Description | -|----------|-------------| -| 0 | Low | -| 1 | Medium | -| 2 | High | - -RewatchValue range: `0` - `5` -| RewatchValue | Description | -|--------------|-------------| -| 0 | None | -| 1 | Very Low | -| 2 | Low | -| 3 | Medium | -| 4 | High | -| 5 | Very High | - -``` go -// ... - -var res AnimeUpdateResponse - -// can omit any field but keep at least 1! -params := map[string]interface{} { - mg.Status: mg.ListStatusCompleted, - mg.IsRewatching: false, - mg.Score: 10, - mg.EpisodesWatched: 26, - mg.Priority: 2, - mg.TimesRewatched: 2, - mg.RewatchValue: 5, - mg.Tags: "tags", - mg.Comments: "comments", -} - -err := client.UpdateAnime(&res, /*anime id*/ 457, params) -if err != nil { - fmt.Println(err) -} - -// ... -``` - -## Deleting an anime from list - -`MainAuth` only - -Deletes the anime from currently logged in user's anime list. -Returns an error if anime is already not in the list. - -``` go -// ... - -err := client.DeleteAnime(/*anime id*/ 457) -if err != nil { - fmt.Println(err) -} - -// ... -``` - -# Manga - -## Searching for a manga - -`MainAuth` or `ClientAuth` - -_also works for light novels, etc_ - -``` go -// ... - -var mangas []mg.Manga - -carams := mg.SearchParamsNew() -carams.SearchString = "empty box and zeroth maria" - -// optional; these are the default values -params.Limit = 100 -params.Offset = 0 -params.NSFW = false -params.Fields = []string{} - -err := client.SearchManga(&mangas, params) -if err != nil { - fmt.Println(err) -} - -for _, manga range mangas { - fmt.Println(manga.Title) -} - -// ... -``` - -## Getting a manga's information - -`MainAuth` or `ClientAuth` - -_searching can be a bit inaccurate, if you know the manga's ID (obtain it with SearchManga!) and want to get detailed information, use this._ - -``` go -// ... - -var manga mg.Manga - -err := client.GetMangaById(&manga, /*manga id*/ 55215, /*fields*/ []string{}) -if err != nil { - fmt.Println(err) -} - -// ... -``` - -## Getting manga ranking list - -`MainAuth` or `ClientAuth` - -Accepted ranking types: -| RankingType | Description | -|----------------------------|----------------| -| mg.RankingTypeAll | All | -| mg.RankingTypeByPopularity | Most Popular | -| mg.RankingTypeFavorite | Most Favorited | -| mg.RankingTypeManga | Top Manga | -| mg.RankingTypeNovel | Top Novels | -| mg.RankingTypeOneShot | Top One-shots | -| mg.RankingTypeDoujin | Top Doujinshi | -| mg.RankingTypeManhwa | Top Manhwa | -| mg.RankingTypeManhua | Top Manhua | - -*RankedManga is just the Manga struct with an extra field `RankNum int`* - -``` go -// ... - -var rankingList []mg.RankedManga - -params := mg.RankingParamsNew() - -// optional; these are the default values -params.RankingType = mg.RankingTypeAll -params.Limit = 100 // max = 500 -params.Offset = 0 -params.NSFW = false -params.Fields = []string{} - -err := client.GetAnimeRanking(&rankingList, params) -if err != nil { - fmt.Println(err) -} - -// ... -``` - -## Get any user's manga list - -`MainAuth` or `ClientAuth` - -This returns a boolean telling us if there is a next page on this user's list. -Simply increment the offset by the limit and create a new request in order to get the next page. - -In order to get the complete list, repeat the process until `nextPageExists` becomes false. - -Accepted statuses: -- `mg.ListStatusAll` -- `mg.ListStatusReading` -- `mg.ListStatusCompleted` -- `mg.ListStatusOnHold` -- `mg.ListStatusDropped` -- `mg.ListStatusPTR` - -Accepted list sorts: -- `mg.SortByListScore` (descending) -- `mg.SortByListUpdatedAt` (descending) -- `mg.SortByMangaTitle` (ascending) -- `mg.SortByMangaStartDate` (descending) -- `mg.SortByMangaId` (ascending) (beta according to MAL) - -``` go -// ... - -var mangas []mg.Manga - -params := mg.ListParamsNew() - -// optional; these are the default values -params.Username = "@me" // can speciy any public account -params.Status = mg.ListStatusAll -params.Sort = mg.SortByListScore -params.Limit = 100 // max = 1000 -params.Offset = 0 -params.NSFW = false -params.Fields = []string{} - -nextPageExists, err := client.GetMangaList(&mangas, params) -if err != nil { - fmt.Println(err) -} - -// ... -``` - -## Updating a manga - -`MainAuth` only - -Updates a manga in the the currently logged in user's manga list. -Adds the manga if it's not in the list. - -Accepted statuses: -- `mg.ListStatusReading` -- `mg.ListStatusCompleted` -- `mg.ListStatusOnHold` -- `mg.ListStatusDropped` -- `mg.ListStatusPTR` - -Score range: `0` - `10` - -Priority range: `0` - `2` -| Priority | Description | -|----------|-------------| -| 0 | Low | -| 1 | Medium | -| 2 | High | - -RereadValue range: `0` - `5` -| RereadValue | Description | -|-------------|-------------| -| 0 | None | -| 1 | Very Low | -| 2 | Low | -| 3 | Medium | -| 4 | High | -| 5 | Very High | - -``` go -// ... - -var res MangaUpdateResponse - -// can omit any field but keep at least 1! -params := map[string]interface{} { - mg.Status: mg.ListStatusReading, - mg.IsRereading: false, - mg.Score: 10, - mg.VolumesRead: 2, - mg.ChaptersRead: 20, - mg.Priority: 2, - mg.TimesReread: 0, - mg.RereadValue: 5, - mg.Tags: "tags", - mg.Comments: "comments", -} - -err := client.UpdateManga(&res, /*manga id*/ 55215, params) -if err != nil { - fmt.Println(err) -} - -// ... -``` - -## Deleting a manga from list - -`MainAuth` only - -Deletes the manga from currently logged in user's manga list. -Returns an error if manga is already not in the list. - -``` go -// ... - -err := client.DeleteManga(/*manga id*/ 55215) -if err != nil { - fmt.Println(err) -} - -// ... -``` - -# User - -## Get logged in user's details - -`MainAuth` only - -MyAnimeList's official API doesn't support getting another user's details. Only the currently logged in user. - -``` go -// ... - -var user mg.User - -// to get user's list statistics or not -getStatistics := true - -err := client.GetSelfInfo(&user, getStatistics) -if err != nil { - fmt.Println(err) -} - -// ... -``` |