From f23dae307e06d95499b35dbdd8e341b45756b330 Mon Sep 17 00:00:00 2001 From: Vidhu Kant Sharma Date: Tue, 20 Sep 2022 23:11:52 +0530 Subject: First commit --- content/docs/mal2go/_index.md | 4 + content/docs/mal2go/v4/_index.md | 11 ++ content/docs/mal2go/v4/anime/_index.md | 6 + content/docs/mal2go/v4/anime/get-anime-by-id.md | 42 ++++++ content/docs/mal2go/v4/anime/get-anime-ranking.md | 57 +++++++++ content/docs/mal2go/v4/anime/get-seasonal-anime.md | 61 +++++++++ .../docs/mal2go/v4/anime/get-suggested-anime.md | 46 +++++++ .../docs/mal2go/v4/anime/search-for-an-anime.md | 50 ++++++++ content/docs/mal2go/v4/anime/setting-up.md | 34 +++++ content/docs/mal2go/v4/anime/types.md | 141 +++++++++++++++++++++ content/docs/mal2go/v4/manga/_index.md | 6 + content/docs/mal2go/v4/manga/get-manga-by-id.md | 44 +++++++ content/docs/mal2go/v4/manga/get-manga-ranking.md | 57 +++++++++ content/docs/mal2go/v4/manga/search-for-a-manga.md | 51 ++++++++ content/docs/mal2go/v4/manga/setting-up.md | 34 +++++ content/docs/mal2go/v4/manga/types.md | 108 ++++++++++++++++ content/docs/mal2go/v4/tips-and-tricks/_index.md | 28 ++++ content/docs/mal2go/v4/user/_index.md | 5 + content/docs/mal2go/v4/user/anime/_index.md | 10 ++ .../mal2go/v4/user/get-self-user-info/_index.md | 48 +++++++ content/docs/mal2go/v4/user/manga/_index.md | 9 ++ content/docs/mal2go/v4/user/setting-up/_index.md | 34 +++++ 22 files changed, 886 insertions(+) create mode 100644 content/docs/mal2go/_index.md create mode 100644 content/docs/mal2go/v4/_index.md create mode 100644 content/docs/mal2go/v4/anime/_index.md create mode 100644 content/docs/mal2go/v4/anime/get-anime-by-id.md create mode 100644 content/docs/mal2go/v4/anime/get-anime-ranking.md create mode 100644 content/docs/mal2go/v4/anime/get-seasonal-anime.md create mode 100644 content/docs/mal2go/v4/anime/get-suggested-anime.md create mode 100644 content/docs/mal2go/v4/anime/search-for-an-anime.md create mode 100644 content/docs/mal2go/v4/anime/setting-up.md create mode 100644 content/docs/mal2go/v4/anime/types.md create mode 100644 content/docs/mal2go/v4/manga/_index.md create mode 100644 content/docs/mal2go/v4/manga/get-manga-by-id.md create mode 100644 content/docs/mal2go/v4/manga/get-manga-ranking.md create mode 100644 content/docs/mal2go/v4/manga/search-for-a-manga.md create mode 100644 content/docs/mal2go/v4/manga/setting-up.md create mode 100644 content/docs/mal2go/v4/manga/types.md create mode 100644 content/docs/mal2go/v4/tips-and-tricks/_index.md create mode 100644 content/docs/mal2go/v4/user/_index.md create mode 100644 content/docs/mal2go/v4/user/anime/_index.md create mode 100644 content/docs/mal2go/v4/user/get-self-user-info/_index.md create mode 100644 content/docs/mal2go/v4/user/manga/_index.md create mode 100644 content/docs/mal2go/v4/user/setting-up/_index.md (limited to 'content/docs/mal2go') diff --git a/content/docs/mal2go/_index.md b/content/docs/mal2go/_index.md new file mode 100644 index 0000000..66f369a --- /dev/null +++ b/content/docs/mal2go/_index.md @@ -0,0 +1,4 @@ +--- +title: MAL2Go +description: MyAnimeList V2 API wrapper for Go +--- diff --git a/content/docs/mal2go/v4/_index.md b/content/docs/mal2go/v4/_index.md new file mode 100644 index 0000000..61cac83 --- /dev/null +++ b/content/docs/mal2go/v4/_index.md @@ -0,0 +1,11 @@ +--- +title: MAL2Go V4 +description: Version 4 of MAL2Go MyAnimeList API Wrapper +--- + +MAL2Go V4 supports almost all of the functionality provided by the MyAnimeList API. Only working with the forums is not supported. +Everything else is supposed to properly work. If there is any bug please open an issue on the [GitHub repo](https://github.com/MikunoNaka/MAL2Go) or email me at [vidhukant@vidhukant.xyz](mailto:vidhukant@vidhukant.xyz). Forums support coming soon. + +### MAL2Go is divided into multiple packages that perform various API interactions. + +**MAL2Go documentation is incomplete but has been tested and works properly with MAL2Go v4.0.1** diff --git a/content/docs/mal2go/v4/anime/_index.md b/content/docs/mal2go/v4/anime/_index.md new file mode 100644 index 0000000..764cb33 --- /dev/null +++ b/content/docs/mal2go/v4/anime/_index.md @@ -0,0 +1,6 @@ +--- +title: Anime +description: Everything related to anime (except animelists) +weight: 1 +--- + diff --git a/content/docs/mal2go/v4/anime/get-anime-by-id.md b/content/docs/mal2go/v4/anime/get-anime-by-id.md new file mode 100644 index 0000000..ca310b3 --- /dev/null +++ b/content/docs/mal2go/v4/anime/get-anime-by-id.md @@ -0,0 +1,42 @@ +--- +title: "Getting an anime's information" +description: "Specify an anime's ID to get all the data about it." +weight: 3 +--- + +`GetAnimeById` takes in an anime's ID (which can be obtained using [`SearchAnime`](/docs/mal2go/v4/anime/search-for-an-anime) or through the URL of the anime's page on MAL) and returns information about it. This method takes these arguments: + +- `id int` The anime's ID +- `fields []string` The fields to include in the response. [Here](/docs/mal2go/v4/anime/types#mal2goanimeanime) is a list of the valid fields. Just using an empty slice (`[]string{}`) will include all the fields. + +Example: + +``` go +package main + +import ( + "github.com/MikunoNaka/MAL2Go/v4/anime" + "log" + "fmt" +) + +func main() { + authToken := "YOUR_TOKEN_HERE" + myClient := anime.Client { + AuthToken: "Bearer " + authToken, + } + + id := 457 + fields := []string{"title", "my_list_status", "num_episodes"} + + anime, err := myClient.GetAnimeById(id, fields) + if err != nil { + log.Fatal(err) // remember kids, always handle errors + } + + fmt.Printf("You have watched %d out of %d episodes in %s. Your list status for %s is %s.\n", anime.MyListStatus.EpWatched, anime.NumEpisodes, anime.Title, anime.Title, anime.MyListStatus.Status) +} +``` + +Above example prints something like +`"You have watched 26 out of 26 episodes in Mushishi. Your list status for Mushishi is completed."` diff --git a/content/docs/mal2go/v4/anime/get-anime-ranking.md b/content/docs/mal2go/v4/anime/get-anime-ranking.md new file mode 100644 index 0000000..6479b6c --- /dev/null +++ b/content/docs/mal2go/v4/anime/get-anime-ranking.md @@ -0,0 +1,57 @@ +--- +title: "Get anime ranking list" +description: "Returns a list of animes sorted by their rank" +weight: 4 +--- + +`GetAnimeRanking` returns a list of animes sorted by their rank. It accepts these arguments: + +- `rankingType string` Ranking type can be: + + `all` + + `airing` + + `upcoming` + + `tv` + + `ova` + + `movie` + + `special` + + `bypopularity` + + `favorite` +- `limit int` Is the max amount of results to get. Max is 500. +- `offset int` Is the "offset" for results. If offset is greater than 0 the first n number of reults will be ignored. +- `nsfw bool` Wether to include NSFW rated results +- `fields []string` The fields to include in the response. [Here](/docs/mal2go/v4/anime/types#mal2goanimeanime) is a list of the valid fields. Just using an empty slice (`[]string{}`) will include all the fields. + +Example: + +``` go +package main + +import ( + "github.com/MikunoNaka/MAL2Go/v4/anime" + "log" + "fmt" +) + +func main() { + authToken := "YOUR_TOKEN_HERE" + myClient := anime.Client { + AuthToken: "Bearer " + authToken, + } + + rankingType := "movie" + limit, offset := 10, 0 + nsfw := true // include NSFW results + fields := []string{"title"} + + ranking, err := myClient.GetAnimeRanking(rankingType, limit, offset, nsfw, fields) + if err != nil { + log.Fatal(err) // remember kids, always handle errors + } + + for _, i := range ranking { + fmt.Printf("#%d: %s\n", i.RankNum, i.Title) + } +} +``` + +Above example prints the top 10 ranked anime movies on MyAnimeList. diff --git a/content/docs/mal2go/v4/anime/get-seasonal-anime.md b/content/docs/mal2go/v4/anime/get-seasonal-anime.md new file mode 100644 index 0000000..f473a02 --- /dev/null +++ b/content/docs/mal2go/v4/anime/get-seasonal-anime.md @@ -0,0 +1,61 @@ +--- +title: "Get seasonal anime list" +description: "Specify an year and season to get animes from" +weight: 5 +--- + +`GetSeasonalAnime` returns a list of animes that released in the specified season and year. Accepted arguments are: + +- `year string` Is the max amount of search results to get. Max is 500. +- `season string` Is the "offset" for the search results. If offset is greater than 0 the first n number of search reults will be ignored. +Possible seasons: + + `winter` + + `spring` + + `summer` + + `fall` +- `sort string` Wether to include NSFW rated search results +Possible sorts: + + `anime_score` + + `anime_num_list_users` +- `limit int` Is the max amount of results to get. Max is 500. +- `offset int` Is the "offset" for results. If offset is greater than 0 the first n number of reults will be ignored. +- `nsfw bool` Wether to include NSFW rated results +- `fields []string` The fields to include in the response. [Here](/docs/mal2go/v4/anime/types#mal2goanimeanime) is a list of the valid fields. Just using an empty slice (`[]string{}`) will include all the fields. + +Example: + +``` go +package main + +import ( + "github.com/MikunoNaka/MAL2Go/v4/anime" + "log" + "fmt" +) + +func main() { + authToken := "YOUR_TOKEN_HERE" + myClient := anime.Client { + AuthToken: "Bearer " + authToken, + } + + year := "2022" + season := "spring" + sort := "anime_num_list_users" + limit, offset := 10, 0 + nsfw := true // include NSFW results + fields := []string{"title"} + + seasonalAnimes, err := myClient.GetSeasonalAnime(year, season, sort, limit, offset, nsfw, fields) + if err != nil { + log.Fatal(err) // remember kids, always handle errors + } + + fmt.Printf("Here are some popular animes from %s, %d\n", seasonalAnimes.Season.Name, seasonalAnimes.Season.Year) + for _, i := range seasonalAnimes.Animes { + fmt.Println(i.Title) + } +} +``` + +Above example prints 10 animes from spring 2022 with the most users. diff --git a/content/docs/mal2go/v4/anime/get-suggested-anime.md b/content/docs/mal2go/v4/anime/get-suggested-anime.md new file mode 100644 index 0000000..98dc01c --- /dev/null +++ b/content/docs/mal2go/v4/anime/get-suggested-anime.md @@ -0,0 +1,46 @@ +--- +title: "Get suggested animes" +description: "Returns some suggestions for the user" +weight: 6 +--- + +`GetSuggestedAnime` returns a list of animes suggested to the authenticated user. + +- `limit int` Is the max amount of results to get. Max is 100. +- `offset int` Is the "offset" for results. If offset is greater than 0 the first n number of reults will be ignored. +- `nsfw bool` Wether to include NSFW rated results +- `fields []string` The fields to include in the response. [Here](/docs/mal2go/v4/anime/types#mal2goanimeanime) is a list of the valid fields. Just using an empty slice (`[]string{}`) will include all the fields. + +Example: + +``` go +package main + +import ( + "github.com/MikunoNaka/MAL2Go/v4/anime" + "log" + "fmt" +) + +func main() { + authToken := "YOUR_TOKEN_HERE" + myClient := anime.Client { + AuthToken: "Bearer " + authToken, + } + + limit, offset := 10, 0 + nsfw := true // include NSFW results + fields := []string{"title"} + + suggestedAnimes, err := myClient.GetSuggestedAnime(limit, offset, nsfw, fields) + if err != nil { + log.Fatal(err) // remember kids, always handle errors + } + + for _, i := range suggestedAnimes { + fmt.Println(i.Title) + } +} +``` + +Above example prints 10 animes suggested to the authenticated user. diff --git a/content/docs/mal2go/v4/anime/search-for-an-anime.md b/content/docs/mal2go/v4/anime/search-for-an-anime.md new file mode 100644 index 0000000..addf43a --- /dev/null +++ b/content/docs/mal2go/v4/anime/search-for-an-anime.md @@ -0,0 +1,50 @@ +--- +title: "Searching for an anime" +description: "Use a search string to get a list of animes" +weight: 2 +--- + +Use the `SearchAnime` method to search for an anime. This method takes these arguments: + +- `searchString string` Is pretty obvious. This term is used to search for an anime on MyAnimeList. +- `limit int` Is the max amount of search results to get. Max is 100. +- `offset int` Is the "offset" for the search results. If offset is greater than 0 the first n number of search reults will be ignored. +- `nsfw bool` Wether to include NSFW rated search results +- `fields []string` The fields to include in the response. [Here](/docs/mal2go/v4/anime/types#mal2goanimeanime) is a list of the valid fields. Just using an empty slice (`[]string{}`) will include all the fields. +The MyAnimeList API is picky about what fields to actually include with search results. To be sure that you are getting all the data it is recommended to use the [`GetAnimeById`](/docs/mal2go/v4/anime/get-anime-by-id) method which ensures that all the required fields are included. + + +Example: + +``` go +package main + +import ( + "github.com/MikunoNaka/MAL2Go/v4/anime" + "log" + "fmt" +) + +func main() { + authToken := "YOUR_TOKEN_HERE" + myClient := anime.Client { + AuthToken: "Bearer " + authToken, + } + + searchString := "mushishi" // search for mushishi + limit := 10 // get 10 search results + offset := 0 // no offset + searchNsfw := false // don't include NSFW results + fields := []string{"title"} // only pull the title + + searchResults, err := myClient.SearchAnime(searchString, limit, offset, searchNsfw, fields) + if err != nil { + log.Fatal(err) // remember kids, always handle errors + } + + // loop over the search results and print the title + for _, anime := range searchResults { + fmt.Println(anime.Title) + } +} +``` diff --git a/content/docs/mal2go/v4/anime/setting-up.md b/content/docs/mal2go/v4/anime/setting-up.md new file mode 100644 index 0000000..30c4339 --- /dev/null +++ b/content/docs/mal2go/v4/anime/setting-up.md @@ -0,0 +1,34 @@ +--- +title: "Setting up" +description: "Install MAL2Go/anime and write some boilerplate" +weight: 1 +--- + +How to use the anime package: + +1. Install the anime package using this command + +``` fish +go get github.com/MikunoNaka/MAL2Go/v4/anime +``` + +2. Import and initialise the anime client. The client holds the authentication token of the user. The OAuth token should be set as "Bearer TOKEN". Refer to below example + +``` go +package main + +import ( + "github.com/MikunoNaka/MAL2Go/v4/anime" +) + +func main() { + // you should never hard-code tokens. This is just an example + authToken := "YOUR_TOKEN_HERE" + myClient := anime.Client { + AuthToken: "Bearer " + authToken, + } +} +``` + +Every program using MAL2Go needs something like this to initialise everything (that you need). +And now we are ready to use the MAL2Go/anime package! diff --git a/content/docs/mal2go/v4/anime/types.md b/content/docs/mal2go/v4/anime/types.md new file mode 100644 index 0000000..176c774 --- /dev/null +++ b/content/docs/mal2go/v4/anime/types.md @@ -0,0 +1,141 @@ +--- +title: "Types" +description: "The structs defined in this package" +weight: 7 +--- + +## MAL2Go/anime.Anime + +These are the valid fields you can use while getting data using MAL2Go/anime package. + +| Search Field | Struct Field | Type | Description | +|-------------------------------|-----------------|--------------------------------------------------|--------------------------------------------------------| +| id | Id | `int` | ID of the anime | +| title | Title | `string` | Title | +| main\_picture | MainPicture | [`util.Picture`](#mal2goutilgenre) | Cover picture | +| alternative\_titles | AltTitles | [`util.AltTitles`](#mal2goutilalttitles) | Alternative titles | +| start_date | StartDate | `string` | Date started airing | +| end\_date | EndDate | `string` | Date ended airing | +| synopsis | Synopsis | `string` | Synopsis | +| mean | MeanScore | `float32` | Mean score | +| rank | Rank | `int` | Rank of the anime (0 when cannot be calculated) | +| popularity | Popularity | `int` | Popularity | +| num\_list\_users | NumListUsers | `int` | Number of List Users | +| num\_scoring\_users | NumScoringUsers | `int` | Number of Scoring List Users | +| nsfw | NsfwStatus | `string` | NSFW rating (white = SFW, black = NSFW, gray = medium) | +| created\_at | CreatedAt | `string` | Created At | +| updated\_at | UpdatedAt | `string` | Updated At | +| media\_type | MediaType | `string` | Media Type | +| status | Status | `string` | Status | +| genres | Genres | [`[]util.Genre`](#mal2goutilgenre) | List of Genres | +| my\_list\_status | MyListStatus | [`ListStatus`](#mal2goanimeliststatus) | Authenticated user's List Status | +| *none, automatically applied* | ListStatus | [`ListStatus`](#mal2goanimeliststatus) | List status (for when looking up another user's list) | +| num\_episodes | NumEpisodes | `int` | Number of Episodes | +| start\_season | StartSeason | [`Season`](#mal2goanimeseason) | Season in Which the Anime Started Airing | +| broadcast | Broadcast | [`Broadcast`](#mal2goanimebroadcast) | Broadcast Info | +| source | Source | `string` | Source Media | +| average\_episode\_duration | DurationSeconds | `int` | Average Episode Duration (seconds) | +| rating | Rating | `string` | Rating (pg\_13, etc) | +| pictures | Pictures | [`[]util.Picture`](#mal2goutilgenre) | Pictures | +| background | Background | `string` | Background Info | +| related\_anime | RelatedAnime | [`[]Related`](#mal2goanimerelated) | Related Anime | +| related\_manga | RelatedManga | `not supported yet` | Related Manga (currently not supported) | +| recommendations | Recommendations | [`[]Recommendation`](#mal2goanimerecommendation) | Recommendations | +| studios | Studios | [`[]Studio`](#mal2goanimestudio) | List of Studios | +| statistics | Statistics | [`AnimeStatistics`](#mal2goanimeanimestatistics) | Statistics | + +## MAL2Go/anime.Season + +| Struct Field | Type | Description | Potential Values | +|--------------|----------|--------------------|-------------------------------------------------| +| Year | `int` | Year | Any positive integer | +| Season | `string` | Season of the year | `"winter"` / `"spring"` / `"summer"` / `"fall"` | + +## MAL2Go/anime.AnimeStatistics + +| Struct Field | Type | Description | +|--------------|---------------|----------------------| +| NumListUsers | `int` | Number of list users | +| Status | `to be added` | List status of user | + +## MAL2Go/anime.Broadcast + +| Struct Field | Type | Description | Potential Values | +|--------------|----------|-------------------|------------------------------| +| Day | `string` | Day of the week | Day of the week or `"other"` | +| Time | `string` | Time of broadcast | String like "01:25" or `nil` | + +## MAL2Go/anime.Related + +| Struct Field | Type | Description | Potential Values | +|-----------------------|------------------------------|------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| Anime | [`Anime`](#mal2goanimeanime) | Related anime | Any Anime | +| RelationType | `string` | Relation of this anime with selected one | `"sequel"`, `"prequel"`, `"alternative_setting"`, `"alternative_version"`, `"side_story"`, `"parent_story"`, `"summary"`, `"full_story"` | +| RelationTypeFormatted | `string` | RelationType with pretty formatting | Same as RelationType but with pretty formatting | + +## MAL2Go/anime.Studio + +| Struct Field | Type | Description | +|--------------|----------|-------------| +| Id | `int` | Studio ID | +| Name | `string` | Studio name | + +## MAL2Go/anime.Recommendation + +| Struct Field | Type | Description | +|--------------|------------------------------|---------------------------------------------------| +| Anime | [`Anime`](#mal2goanimeanime) | Recommendated anime for those who like this anime | +| Num | `int` | Number of recommendations (times recommended) | + +## MAL2Go/anime.ListStatus + +| Struct Field | Type | Description | Potential Values | +|----------------|----------|-----------------------------------------|------------------------------------------------------------------------------------| +| Status | `string` | Status | `"watching"`, `"completed"`, `"on_hold"`, `"dropped"`, `"plan_to_watch"`, or `nil` | +| Score | `int` | Score | 0 to 10 | +| StartDate | `string` | Start date for the user | date string or `nil` | +| FinishDate | `string` | Finish date for the user | date string or `nil` | +| Priority | `int` | Priority | | +| Tags | `string` | probably broken | | +| Comments | `string` | Comments | | +| UpdatedAt | `string` | Time last updated by the user | | +| EpWatched | `int` | Number of episodes watched | | +| IsRewatching | `bool` | If user is rewatching this anime or not | `true` or `false` | +| TimesRewatched | `int` | Times user has rewatched this | | +| RewatchValue | `int` | Frequency of rewatches | 0 to 5 (never, very low, low, medium, high, very high) | + +## MAL2Go/*util*.Picture + +Holds the cover picture/related picture's URLs in different sizes + +| Struct Field | Type | Description | Potential Values | +|--------------|----------|----------------------|----------------------------------------------| +| Medium | `string` | Medium sized picture | non empty string containing URL of picture | +| Large | `string` | Large sized picture | string containing the URL or an empty string | + +## MAL2Go/*util*.AltTitles + +| Struct Field | Type | Description | Potential Values | +|--------------|------------|-----------------------|---------------------------| +| Synonyms | `[]string` | Synonyms of the title | `[]string` or empty slice | +| En | `string` | English title | any string or `""` | +| Ja | `string` | Japanese title | any string or `""` | + +## MAL2Go/*util*.Genre + +| Struct Field | Type | Description | +|--------------|----------|-------------------| +| Id | `int` | ID of the genre | +| Name | `string` | Name of the genre | + +## MAL2Go/*util*.StatusStatistics + +**NOTE:** Due to changes with the MyAnimeList API, this might be broken in versions upto v4.1.0, this will be fixed in the next update. + +| Struct Field | Type | Description | +|--------------|----------|-------------------------------------------------| +| Watching | `string` | Number of users watching this anime | +| Completed | `string` | Number of users who have completed this anime | +| OnHold | `string` | Number of users who have put this anime on hold | +| Dropped | `string` | Number of users who have dropped this anime | +| PlanToWatch | `string` | Number of users planning to watch this anime | diff --git a/content/docs/mal2go/v4/manga/_index.md b/content/docs/mal2go/v4/manga/_index.md new file mode 100644 index 0000000..185d116 --- /dev/null +++ b/content/docs/mal2go/v4/manga/_index.md @@ -0,0 +1,6 @@ +--- +title: Manga +description: Everything related to manga (except mangalists) +weight: 2 +--- + diff --git a/content/docs/mal2go/v4/manga/get-manga-by-id.md b/content/docs/mal2go/v4/manga/get-manga-by-id.md new file mode 100644 index 0000000..682ef29 --- /dev/null +++ b/content/docs/mal2go/v4/manga/get-manga-by-id.md @@ -0,0 +1,44 @@ +--- +title: "Getting a manga's information" +description: "Specify a manga's ID to get all the data about it." +weight: 3 +--- + +`GetMangaById` takes in a manga's ID (which can be obtained using [`SearchManga`](#searching-for-a-manga) or through the URL of the manga's page on MAL) and returns information about it. This method takes these arguments: + +- `id int` The manga's ID +- `fields []string` The fields to include in the response. [Here]() is a list of the valid fields. Just using an empty slice (`[]string{}`) will include all the fields. + +Example: + +``` go +package main + +import ( + "github.com/MikunoNaka/MAL2Go/v4/manga" + "log" + "fmt" +) + +func main() { + authToken := "YOUR_TOKEN_HERE" + myClient := manga.Client { + AuthToken: "Bearer " + authToken, + } + + id := 103890 + fields := []string{"title", "my_list_status", "num_chapters"} + + manga, err := myClient.GetMangaById(id, fields) + if err != nil { + log.Fatal(err) // remember kids, always handle errors + } + + fmt.Printf("You have read %d out of %d chapters in %s. Your list status for %s is %s.\n", manga.MyListStatus.ChaptersRead, manga.NumChapters, manga.Title, manga.Title, manga.MyListStatus.Status) +} +``` + +Above example prints something like +`"You have read 7 out of 187 chapters in Bokutachi wa Benkyou ga Dekinai. Your list status for Bokutachi wa Benkyou ga Dekinai is reading."` + +Above output shows blank status because mushishi is not in my list. This is expected. diff --git a/content/docs/mal2go/v4/manga/get-manga-ranking.md b/content/docs/mal2go/v4/manga/get-manga-ranking.md new file mode 100644 index 0000000..ef5435f --- /dev/null +++ b/content/docs/mal2go/v4/manga/get-manga-ranking.md @@ -0,0 +1,57 @@ +--- +title: "Get manga ranking list" +description: "Returns a list of mangas sorted by their rank" +weight: 4 +--- + +`GetMangaRanking` returns a list of mangas sorted by their rank. It accepts these arguments: + +- `rankingType string` Ranking type can be: + + `all` + + `manga` + + `novels` + + `oneshots` + + `doujin` + + `manhwa` + + `manhua` + + `bypopularity` + + `favorite` +- `limit int` Is the max amount of results to get. Max is 500. +- `offset int` Is the "offset" for results. If offset is greater than 0 the first n number of reults will be ignored. +- `nsfw bool` Wether to include NSFW rated results +- `fields []string` The fields to include in the results. [Here]() is a list of the valid fields. Just using an empty slice (`[]string{}`) will include all the fields. Again, to get some very specific fields, [`GetMangaById`](#get-data-about-a-manga) is the most reliable option. + +Example: + +``` go +package main + +import ( + "github.com/MikunoNaka/MAL2Go/v4/manga" + "log" + "fmt" +) + +func main() { + authToken := "YOUR_TOKEN_HERE" + myClient := manga.Client { + AuthToken: "Bearer " + authToken, + } + + rankingType := "novels" + limit, offset := 10, 0 + nsfw := true // include NSFW results + fields := []string{"title"} + + ranking, err := myClient.GetMangaRanking(rankingType, limit, offset, nsfw, fields) + if err != nil { + log.Fatal(err) // remember kids, always handle errors + } + + for _, i := range ranking { + fmt.Printf("#%d: %s\n", i.RankNum, i.Title) + } +} +``` + +Above example prints the top 10 ranked novels on MyAnimeList. diff --git a/content/docs/mal2go/v4/manga/search-for-a-manga.md b/content/docs/mal2go/v4/manga/search-for-a-manga.md new file mode 100644 index 0000000..5d519aa --- /dev/null +++ b/content/docs/mal2go/v4/manga/search-for-a-manga.md @@ -0,0 +1,51 @@ +--- +title: "Search for a manga" +description: "Use a search string to get a list of mangas" +weight: 2 +--- + +Use the `SearchManga` method to search for a manga. This method takes these arguments: + +- `searchString string` Is pretty obvious. This term is used to search for a manga on MyAnimeList. +- `limit int` Is the max amount of search results to get. Max is 100. +- `offset int` Is the "offset" for the search results. If offset is greater than 0 the first n number of search reults will be ignored. +- `nsfw bool` Wether to include NSFW rated search results +- `fields []string` The fields to include in the search results. [Here]() is a list of the valid fields. Just using an empty slice (`[]string{}`) will include all the fields. +The MyAnimeList API is picky about what fields to actually include with search results. To be sure that you are getting all the data it is recommended to use the [`GetMangaById`](#get-data-about-a-manga) method which ensures that all the required fields are included. + + +Example: + +``` go +package main + +import ( + "github.com/MikunoNaka/MAL2Go/v4/manga" + "log" + "fmt" +) + +func main() { + authToken := "YOUR_TOKEN_HERE" + myClient := manga.Client { + AuthToken: "Bearer " + authToken, + } + + searchString := "mushishi" // search for mushishi + limit := 10 // get 10 search results + offset := 0 // no offset + searchNsfw := false // don't include NSFW results + fields := []string{"title"} // only pull the title + + searchResults, err := myClient.SearchManga(searchString, limit, offset, searchNsfw, fields) + if err != nil { + log.Fatal(err) // remember kids, always handle errors + } + + // loop over the search results and print the title + for _, manga := range searchResults { + fmt.Println(manga.Title) + } +} +``` + diff --git a/content/docs/mal2go/v4/manga/setting-up.md b/content/docs/mal2go/v4/manga/setting-up.md new file mode 100644 index 0000000..baa77cb --- /dev/null +++ b/content/docs/mal2go/v4/manga/setting-up.md @@ -0,0 +1,34 @@ +--- +title: "Setting up" +description: "Install MAL2Go/manga and write some boilerplate" +weight: 1 +--- + +How to use the manga package: + +1. Install the manga package using this command + +``` fish +go get github.com/MikunoNaka/MAL2Go/v4/manga +``` + +2. Import and initialise the anime client. The client holds the authentication token of the user. The OAuth token should be set as "Bearer TOKEN". Refer to below example + +``` go +package main + +import ( + "github.com/MikunoNaka/MAL2Go/v4/manga" +) + +func main() { + // you should never hard-code tokens. This is just an example + authToken := "YOUR_TOKEN_HERE" + myClient := manga.Client { + AuthToken: "Bearer " + authToken, + } +} +``` + +Every program using MAL2Go needs something like this to initialise everything (that you need). +And now we are ready to use the MAL2Go/manga package! diff --git a/content/docs/mal2go/v4/manga/types.md b/content/docs/mal2go/v4/manga/types.md new file mode 100644 index 0000000..6d3e297 --- /dev/null +++ b/content/docs/mal2go/v4/manga/types.md @@ -0,0 +1,108 @@ +--- +title: "Types" +description: "The structs defined in this package" +weight: 5 +--- + +## MAL2Go/manga.Manga + +These are the valid fields you can use while getting data using MAL2Go/manga package. **(INCOMPLETE)** + +| Search Field | Struct Field | Type | Description | +|-------------------------------|-----------------|--------------------------------------------------|--------------------------------------------------------| +| id | Id | `int` | ID of the manga | +| title | Title | `string` | Title | +| main\_picture | MainPicture | [`util.Picture`](#mal2goutilgenre) | Cover picture | +| alternative\_titles | AltTitles | [`util.AltTitles`](#mal2goutilalttitles) | Alternative titles | +| start_date | StartDate | `string` | Date started publishing | +| end\_date | EndDate | `string` | Date ended publishing | +| synopsis | Synopsis | `string` | Synopsis | +| mean | MeanScore | `float32` | Mean score | +| rank | Rank | `int` | Rank of the manga (0 when cannot be calculated) | +| popularity | Popularity | `int` | Popularity | +| num\_list\_users | NumListUsers | `int` | Number of List Users | +| num\_scoring\_users | NumScoringUsers | `int` | Number of Scoring List Users | +| nsfw | NsfwStatus | `string` | NSFW rating (white = SFW, black = NSFW, gray = medium) | +| created\_at | CreatedAt | `string` | Created At | +| updated\_at | UpdatedAt | `string` | Updated At | +| media\_type | MediaType | `string` | Media Type | +| status | Status | `string` | Status | +| genres | Genres | [`[]util.Genre`](#mal2goutilgenre) | List of Genres | +| my\_list\_status | MyListStatus | [`ListStatus`](#mal2gomangaliststatus) | Authenticated user's list status | +| *none, automatically applied* | ListStatus | [`ListStatus`](#mal2gomangaliststatus) | List status (for when looking up another user's list) | +| num\_volumes | NumVolumes | `int` | | +| num\_chapters | NumChapters | `int` | | +| authors | Authors | [`[]MangaAuthor`](#mal2gomangamangaauthor) | | +| pictures | Pictures | [`[]util.Picture`](#mal2goutilgenre) | Pictures | +| background | Background | `string` | Background Info | +| related\_anime| RelatedAnime | [`[]anime.Related`](/docs/mal2go/v4/anime/types#mal2goanimerelated) | Related Anime| +| related\_manga | RelatedManga | [`[]Related`](#mal2gomangarelated) | Related Manga (currently not supported) | +| recommendations | Recommendations | [`[]Recommendation`](#mal2goanimerecommendation) | Recommendations | +| serialization | Serialization | | | + +## MAL2Go/manga.ListStatus + +| Struct Field | Type | Description | Potential Values | +|--------------|----------|----------------------------------------|------------------------------------------------------------------------------------| +| Status | `string` | Status | `"watching"`, `"completed"`, `"on_hold"`, `"dropped"`, `"plan_to_watch"`, or `nil` | +| Score | `int` | Score | 0 to 10 | +| StartDate | `string` | Start date for the user | date string or `nil` | +| FinishDate | `string` | Finish date for the user | date string or `nil` | +| Priority | `int` | Priority | | +| Tags | `string` | probably broken | | +| Comments | `string` | Comments | | +| UpdatedAt | `string` | Time last updated by the user | | +| VolumesRead | `int` | Number of volumes read | | +| ChaptersRead | `int` | Number of chapters read | | +| IsRereading | `bool` | If user is rereading this manga or not | `true` or `false` | +| TimesReread | `int` | Times user has reread this | | +| RereadValue | `int` | Frequency of rereads | 0 to 5 (never, very low, low, medium, high, very high) | + +## MAL2Go/manga.Author + +| Struct Field | Type | Description | +|--------------|----------|---------------------| +| Id | `int` | Author ID | +| FirstName | `string` | Author's first name | +| LastName | `string` | Author's last name | + +## MAL2Go/manga.MangaAuthor + +| Struct Field | Type | Description | +|--------------|----------|----------------------------------| +| Id | `int` | Author ID | +| FirstName | `string` | Author's first name | +| LastName | `string` | Author's last name | +| Role | `string` | Role of the author in the series | + +## MAL2Go/manga.Related + +| Struct Field | Type | Description | Potential Values | +|-----------------------|------------------------------|------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| Manga | [`Manga`](#mal2gomangamanga) | Related manga | Any Anime | +| RelationType | `string` | Relation of this manga with selected one | `"sequel"`, `"prequel"`, `"alternative_setting"`, `"alternative_version"`, `"side_story"`, `"parent_story"`, `"summary"`, `"full_story"` | +| RelationTypeFormatted | `string` | RelationType with pretty formatting | Same as RelationType but with pretty formatting | + +## MAL2Go/*util*.Picture + +Holds the cover picture/related picture's URLs in different sizes + +| Struct Field | Type | Description | Potential Values | +|--------------|----------|----------------------|----------------------------------------------| +| Medium | `string` | Medium sized picture | non empty string containing URL of picture | +| Large | `string` | Large sized picture | string containing the URL or an empty string | + +## MAL2Go/*util*.AltTitles + +| Struct Field | Type | Description | Potential Values | +|--------------|------------|-----------------------|---------------------------| +| Synonyms | `[]string` | Synonyms of the title | `[]string` or empty slice | +| En | `string` | English title | any string or `""` | +| Ja | `string` | Japanese title | any string or `""` | + +## MAL2Go/*util*.Genre + +| Struct Field | Type | Description | +|--------------|----------|-------------------| +| Id | `int` | ID of the genre | +| Name | `string` | Name of the genre | diff --git a/content/docs/mal2go/v4/tips-and-tricks/_index.md b/content/docs/mal2go/v4/tips-and-tricks/_index.md new file mode 100644 index 0000000..b172763 --- /dev/null +++ b/content/docs/mal2go/v4/tips-and-tricks/_index.md @@ -0,0 +1,28 @@ +--- +title: "Tips and Tricks" +description: "Some tips and best practises for using MAL2Go (optional)" +weight: 4 +--- + +These are some tips and best practises, and other notes for using MAL2Go. Following this is optional but might make your life easier! + +## Better ways to store/read auth tokens: + +- Use [godotenv](https://github.com/joho/godotenv) to read the auth token from a config file +- [Viper](https://github.com/spf13/viper) can do the same thing, but can also write to the file easily; also with viper you can locate the file anywhere on your system +- [go-keyring](https://github.com/zalando/go-keyring) can be used to read/write the secret token to the system's keyring. It is by far the most secure way but only works on some systems (windows, macos and linux with gnome-keyring) + +## SearchManga and SearchAnime functions are quirky! + +While you *can* specify fields to these functions, in order to get specific data, searching for some reason only returns limited fields most of the times. +It's not like it just doesn't support all of the fields but many times it just.. doesn't. So if you want to search *and* get ALL fields about an anime, or just +be sure that the data is complete, use [`SearchAnime`](/docs/mal2go/v4/anime/search-for-an-anime/)/[`SearchManga`](/docs/mal2go/v4/manga/search-for-a-manga/) +just to get the ID. After that, use [`GetAnimeById`](/docs/mal2go/v4/anime/get-anime-by-id/)/[`GetMangaById`](/docs/mal2go/v4/manga/get-manga-by-id/). + +## macli has a good example on how to generate your own tokens with go + +MAL2Go was made for my other project, [macli](https://github.com/MikunoNaka/macli). +Macli's `auth` package uses [`github.com/zalando/go-keyring`](https://github.com/zalando/go-keyring) +and the `net/http` package to prompt the user and generate an auth token with the given client id. + +You can look at [the code](https://github.com/MikunoNaka/macli/tree/master/auth) to see how it works. diff --git a/content/docs/mal2go/v4/user/_index.md b/content/docs/mal2go/v4/user/_index.md new file mode 100644 index 0000000..02c62bc --- /dev/null +++ b/content/docs/mal2go/v4/user/_index.md @@ -0,0 +1,5 @@ +--- +title: User +description: Actions related to a user's account/lists +weight: 3 +--- diff --git a/content/docs/mal2go/v4/user/anime/_index.md b/content/docs/mal2go/v4/user/anime/_index.md new file mode 100644 index 0000000..0728945 --- /dev/null +++ b/content/docs/mal2go/v4/user/anime/_index.md @@ -0,0 +1,10 @@ +--- +title: User's Animelist +description: Actions related to a user's animelist +weight: 3 +--- + +The `MAL2Go/user/anime` package supports updating the currently authenticated user's anime list along with reading the anime lists of the current user as well as other users. + + +## coming soon! diff --git a/content/docs/mal2go/v4/user/get-self-user-info/_index.md b/content/docs/mal2go/v4/user/get-self-user-info/_index.md new file mode 100644 index 0000000..31b943c --- /dev/null +++ b/content/docs/mal2go/v4/user/get-self-user-info/_index.md @@ -0,0 +1,48 @@ +--- +title: Getting authenticated user's info +description: Returns information about currenlty logged in user +weight: 2 +--- + +## Getting self user's info + +The `GetSelfUserInfo` function can be used to get information about the currently logged in user. + +``` go +package main + +import ( + "fmt" + "log" + "github.com/MikunoNaka/MAL2Go/v4/user" +) + +func main() { + authToken := "YOUR_TOKEN_HERE" + myClient := user.Client { + AuthToken: "Bearer " + authToken, + } + + userInfo, err := myClient.GetSelfUserInfo() + if err != nil { + log.Fatal(err) + } + + fmt.Printf("Username: %s\n", userInfo.Name) + fmt.Printf("Profile Picture: %s\n", userInfo.Picture) + fmt.Printf("Gender: %s\n", userInfo.Gender) + fmt.Printf("Location: %s\n", userInfo.Location) + fmt.Printf("Birthday: %s\n", userInfo.Birthday) + fmt.Printf("Time Zone: %s\n", userInfo.TimeZone) + fmt.Printf("Joined At: %s\n", userInfo.JoinedAt) + fmt.Printf("User ID: %d\n", userInfo.Id) + + if userInfo.IsSupporter { + fmt.Println("You are a MyAnimeList Supporter.") + } else { + fmt.Println("You are not a MyAnimeList Supporter.") + } +} +``` + +**MyAnimeList's Official API only allows getting info about the currently logged in user.** diff --git a/content/docs/mal2go/v4/user/manga/_index.md b/content/docs/mal2go/v4/user/manga/_index.md new file mode 100644 index 0000000..fd87fc8 --- /dev/null +++ b/content/docs/mal2go/v4/user/manga/_index.md @@ -0,0 +1,9 @@ +--- +title: User's Mangalist +description: Actions related to a user's mangalist +weight: 4 +--- + +The `MAL2Go/user/manga` package supports updating the currently authenticated user's manga list along with reading the manga lists of the current user as well as other users. + +## coming soon! diff --git a/content/docs/mal2go/v4/user/setting-up/_index.md b/content/docs/mal2go/v4/user/setting-up/_index.md new file mode 100644 index 0000000..0b2b890 --- /dev/null +++ b/content/docs/mal2go/v4/user/setting-up/_index.md @@ -0,0 +1,34 @@ +--- +title: "Setting up" +description: "Install MAL2Go/user and write some boilerplate" +weight: 1 +--- + +How to use the user package: + +1. Install the user package using this command + +``` fish +go get github.com/MikunoNaka/MAL2Go/v4/user +``` + +2. Import and initialise the user client. The client holds the authentication token of the user. The OAuth token should be set as "Bearer TOKEN". Refer to below example + +``` go +package main + +import ( + "github.com/MikunoNaka/MAL2Go/v4/user" +) + +func main() { + // you should never hard-code tokens. This is just an example + authToken := "YOUR_TOKEN_HERE" + myClient := user.Client { + AuthToken: "Bearer " + authToken, + } +} +``` + +Every program using MAL2Go needs something like this to initialise everything (that you need). +And now we are ready to use the MAL2Go/anime package! -- cgit v1.2.3