aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md565
1 files changed, 565 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ba8e532
--- /dev/null
+++ b/README.md
@@ -0,0 +1,565 @@
+# mg
+
+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>
+
+<https://mg.vidhukant.com>
+
+# License
+
+Licenced under GNU General Public Licence V3
+
+GNU GPL License: [link](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)
+}
+
+// ...
+```