Skip to main content

Anime API Guide

The client.anime service provides access to MyAnimeList anime metadata, rankings, seasonal schedules, personalized recommendations, and user list management.

API Reference

These methods interact with the official MyAnimeList Anime Endpoints.

Searching Anime​

Search for anime by title or keyword using getAnimeList:

val searchResult = client.anime.getAnimeList(
    query = "Attack on Titan",
    limit = 10,
    offset = 0
)

searchResult.data.forEach { anime ->
    println("${anime.id}: ${anime.title}")
}

Fetching Anime Details​

Fetch complete information for a specific anime by its ID:

import io.github.rribeiro5.koani.anime.AnimeField

val anime = client.anime.getAnimeDetails(
    animeId = 16498,
    fields = listOf(
        AnimeField.SYNOPSIS,
        AnimeField.MEAN,
        AnimeField.GENRES,
        AnimeField.NUM_EPISODES
    )
)

println("Title: ${anime.title}")
println("Score: ${anime.mean}")
println("Synopsis: ${anime.synopsis}")

Anime Rankings​

Query top-ranked anime by category using AnimeRankingType:

import io.github.rribeiro5.koani.anime.AnimeRankingType

val topAnime = client.anime.getAnimeRanking(
    rankingType = AnimeRankingType.ALL,
    limit = 5
)

topAnime.data.forEach { ranked ->
    println("#${ranked.ranking.rank}: ${ranked.node.title}")
}
  • Available Ranking Types: ALL, AIRING, UPCOMING, TV, OVA, MOVIE, SPECIAL, BY_POPULARITY, FAVORITE.
  • API Endpoint: GET /anime/ranking

Seasonal Anime​

Fetch anime schedules for a specific year and season:

import io.github.rribeiro5.koani.anime.Season
import io.github.rribeiro5.koani.anime.SeasonalAnimeSort

val seasonalList = client.anime.getSeasonalAnimes(
    year = 2024,
    season = Season.SUMMER,
    sort = SeasonalAnimeSort.ANIME_SCORE,
    limit = 10
)

seasonalList.data.forEach { anime ->
    println("${anime.title} (${anime.mean})")
}

Suggested Anime Recommendations​

Fetch personalized anime recommendations for the authenticated user:

val suggestions = client.anime.getSuggestedAnimes(limit = 10)

suggestions.data.forEach { anime ->
    println("Recommended: ${anime.title}")
}

User Anime List Management​

Authentication Required

Updating or reading user list items requires an authenticated session.

Get User Anime List​

Fetch a user's anime list filtered by status:

import io.github.rribeiro5.koani.anime.UserAnimeListStatusType

val userList = client.anime.getUserAnimeList(
    userName = "@me", // or specific username
    status = UserAnimeListStatusType.WATCHING,
    limit = 20
)

userList.data.forEach { item ->
    println("${item.node.title} - Score: ${item.listStatus?.score}")
}

Update Anime List Item​

Add or update an anime's status, score, or episode progress:

import io.github.rribeiro5.koani.anime.UserAnimeListStatus

val updatedStatus = client.anime.updateUserAnimeListStatus(
    animeId = 5114,
    status = UserAnimeListStatus.COMPLETED,
    score = 10,
    numEpisodesWatched = 64
)

println("Updated status: ${updatedStatus.status}, Score: ${updatedStatus.score}")

Delete Anime List Item​

Remove an entry from the user's anime list:

client.anime.deleteUserAnimeListItem(animeId = 5114)