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)

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)

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

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

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();

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)

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

• Found a bug? Post it in issues.
• Have a suggestion or looking for inspiration? Check out our discussions.
• Want to further expand our project? Fork this repository and submit a pull request.

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.

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.

Devs running tests through GitHub Actions may do so 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)

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

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

(back to top)