KatsuteDev / Mal4J

Java wrapper for the official MyAnimeList API

Documentation • API Docs • Setup • FAQ • Forum Post
Maven Central • GitHub Packages • Releases

Mal4J is a Java wrapper for the MyAnimeList API. This library is compatible with Java 8+, Java 9+ modules, and Android.

This library supports read and write operations, including list updates.

• 📃 Installation
• ✨ Features
• 👨‍💻 Contributing
• 💼 License
• ⚠️️ Disclaimer

(back to top)

📃 Installation

Mal4J requires at least Java 8. No additional dependencies/libraries are required.

Compiled binaries can be installed from:

• Maven Central
• GitHub Packages
• Releases

See setup for steps to authenticate and actually use this library.

(back to top)

✨ Features

🔎 Search Queries

Find Anime and Manga by search, ranking, season, and suggestions.

MyAnimeList mal = MyAnimeList.withClientID("");
List<Anime> search =
    mal.getAnime()
        .withQuery("さくら荘のペットな彼女")
        .withLimit(1)
        .withOffset(1)
        .includeNSFW(false)
        .search();

📋 Anime and Manga Lists

Read and edit your Anime and Manga listings.

MyAnimeList mal = MyAnimeList.withToken("");
MangaListStatus status =
    mal.updateMangaListing(28107)
        .status(MangaStatus.Reading)
        .volumesRead(7)
        .chaptersRead(2)
        .rereading(false)
        .priority(Priority.High)
        .timesReread(0)
        .rereadValue(RereadValue.VeryHigh)
        .tags("tags", "more tags")
        .comments("comments")
        .update();

📦 Everything Else

All information provided in the MyAnimeList API including Anime, Manga, forums, genres, pictures, and statistics, are accessible in this library.

MyAnimeList mal = MyAnimeList.withClientID("");
Anime anime = mal.getAnime(13759);

String ja = anime.getAlternativeTitles().getJapanese();
Genre[] genres = anime.getGenres();
RelatedAnime[] relatedAnime = anime.getRelatedAnime();
AnimeRecommendation[] recs = anime.getRecommendations();
OpeningTheme[] op = anime.getOpeningThemes();
Video[] PV = anime.getVideos();

(back to top)

👨‍💻 Contributing

GitHub Copilot is strictly prohibited on this repository.
Pulls using this will be rejected.

• Found a bug? Post it in issues.
• Want to further expand our project? Fork this repository and submit a pull request.

⚠️️ Before you start

For Anime/Manga list tests Sakura-sou no Pet na Kanojo (Anime#13759 and Manga#28107) will be used.

The test cases will create a backup of your list in the anime-list.txt and manga-list.txt files. Make sure you fix your ratings and any other information that might be overwritten by this test.

Ignore test failures for these known issues: ⚠️ External Issues.

💻 Running Tests Locally

For local tests you can use Java 8+, however only methods in the Java 8 API may be used. The src/main/java9 and src/main/java11 folders should not be marked as a source root.

Run tests locally by adding a text file named client.txt that contains the client ID in the src/test/java/resources directory.

Please note that the client ID being used for tests must not have a client secret and must have an app redirect url of http://localhost:5050.

🌐 Running Tests using GitHub Actions

Tests can be run using GitHub Actions by running the MyAnimeList CI workflow manually in the actions tab of your fork. Note that this requires two secrets, a MAL_CLIENT which contains the client ID, and a MAL_TOKEN which contains the OAuth token (ex: Bearer <oauth token>).

(back to top)

💼 License

This library is released under the GNU General Public License (GPL) v2.0.

⚠️️ Disclaimer

• @Katsute and @KatsuteDev are not affiliated with MyAnimeList.
• By using the MyAnimeList API you are subject to their Terms Of Service.

(back to top)