AniRecommendAPI

A serverless REST API to discover anime recommendations — random, genre-based, or format-filtered — powered by AniList.

---

✨ Features

• 🎲 Get random anime recommendations
• 🔥 Get anime by id
• 🎯 Filter by genre (/genre?genre=Action)
• 🖼️ Dual API versions (with or without image)
• 📺 Filter by anime format (TV, MOVIE, OVA, etc.)
• 🧠 Smart scraper with no duplicates
• ☁️ GitHub-based auto JSON store
• 🆓 100% free to deploy on Vercel

---

🚀 Quick Start

Random anime (without image)

https://anirecommend.vercel.app/api/v1/random

Get Action anime (with image)

https://anirecommend.vercel.app/api/v2/genre?genre=action

Filter by format (e.g., Movie)

https://anirecommend.vercel.app/api/v3/format?type=movie

Filter by both genre and format

https://anirecommend.vercel.app/api/anime?genre=action&format=tv

Get anime by ID

https://anirecommend.vercel.app/api/v1/id?id=27

Random anime with ID included

https://anirecommend.vercel.app/api/v1/id

Get stats summary

https://anirecommend.vercel.app/api/stats

---

🌐 API Endpoints

Version 1 (Basic, No Image)

Endpoint	Description
/api/v1/random	Get a random anime
/api/v1/genre?genre=Action	Get a random anime from specific genre
/api/v1/id	Get random anime (with ID)
/api/v1/id?id=27	Get anime by ID

Version 2 (With Image)

Endpoint	Description
/api/v2/random	Random anime with cover image
/api/v2/genre?genre=Drama	Genre filter with image

Version 3 (By Format)

Endpoint	Description
/api/v3/format?type=movie	Get anime by format (Movie, TV, OVA, etc.)

Version 4 (Advanced Filters)

The /api/v4 endpoints support advanced filtering by season, year, score, format, adult content, source, and genre.

/api/v4/filter

Returns a random anime matching all query parameters.

Supported Query Parameters:

Parameter	Type	Example	Description
season	String	SPRING	Anime season (SPRING, SUMMER, FALL, WINTER)
year	Integer	2020	Year the anime aired
score	Integer	80	Minimum average score
adult	Boolean	true / false	Include adult (hentai) anime
source	String	MANGA	Source material (e.g., MANGA, LIGHT_NOVEL)
format	String	MOVIE	Format (TV, MOVIE, ONA, OVA, SPECIAL)
genre	String	Action	Genre name (case-insensitive)

GET /api/v4/filter?season=SPRING&year=2020&score=75&adult=false

GET /api/v4/filter?genre=Action&source=MANGA&format=TV

---

Universal

Endpoint	Description
/api/anime?genre=Action&format=Movie	Get anime with both filters

---

✅ Example Usage

GET /api/anime?season=SPRING&year=2020&score=75&adult=false
GET /api/anime?season=SPRING&year=2020&score=75&adult=false&format=TV&genre=Action&source=MANGA
GET /api/anime?season=SPRING&year=2020&format=TV&genre=Action&source=MANGA

---

📘 How It Works

The /api/anime endpoint supports the following optional query parameters:

Parameter	Type	Example	Description
season	string	SPRING	Filter by anime season (WINTER, etc)
year	number	2020	Filter by seasonYear
score	number	75	Minimum average score (0–100)
adult	boolean	true/false	Filter by NSFW status
format	string	TV	Filter by anime format (TV, MOVIE, etc)
genre	string	Action	Filter by genre
source	string	MANGA	Source material (MANGA, NOVEL, etc)

🧠 Filter Matching Logic

All parameters are ANDed together — meaning the result must match all provided filters.

---

🔥 Anime API Endpoints

Endpoint	Description	Parameters
GET /api/anime?genre={genre}	Filters anime by specific genre	genre: Action, Adventure, Comedy, etc.
GET /api/anime?format={type}	Filters anime by media type	format: TV, Movie, OVA, ONA, Special
GET /api/anime?genre={genre}&format={type}	Filters by both genre and media type	Combination of above parameters

Tip

All query values are case-insensitive (e.g., action, Action, ACTION work the same).

---

Statistics

Endpoint	Description
/api/stats	Show genre & format counts
/api/stats/badge	JSON badge showing total anime

📊 Sample Stats (/api/stats)

{
  "formats": {
    "TV": 35,
    "MOVIE": 20,
    "OVA": 5,
    "ONA": 10,
    "SPECIAL": 10
  },
  "genres": {
    "Action": 25,
    "Fantasy": 18,
    "Romance": 10,
    "Drama": 7,
    "Comedy": 12
  },
  "total": 80
}

---

📦 Sample Response

{
  "id": 102,
  "title": "Jujutsu Kaisen (呪術廻戦)",
  "description": "A boy fights cursed spirits after eating a special finger...",
  "type": "ANIME",
  "format": "TV",
  "status": "FINISHED",
  "episodes": 24,
  "duration": "23 Per Ep.",
  "score": 88,
  "genres": ["Action", "Supernatural", "Shounen"],
  "studios": ["MAPPA"],
  "season": "FALL",
  "seasonYear": 2020,
  "isAdult": false,
  "source": "MANGA",
  "image": "https://s4.anilist.co/file/anilistcdn/media/anime/cover/large/bx116588-xyz.jpg",
  "creator": "Shinei Nouzen",
  "github": "https://github.com/Shineii86",
  "telegram": "https://telegran.me/Shineii86",
  "message": "Build with ❤️ by Shinei Nouzen",
  "timestamp": "23/03/2023, 01:04:03 pm"
}

---

🛠️ Deployment Guide

Step 1: Fork the Repo

1. Visit: https://github.com/Shineii86/AniRecommendAPI
2. Click the Fork button

Step 2: Deploy to Vercel

1. Select your forked repo
2. Set the Environment Variable:

🔐 Environment Variables

Set these on Vercel → Project → Settings → Environment Variables:

Key	Value	Description
GH_PAT	Your GitHub token	Allows writing to data/anime.json
API_KEY	API KEY	Secures /api/scrape route

3. Deploy

---

📬 Support

• Issues: GitHub Issues

🪪 License

This project is licensed under the MIT License - see the LICENSE file for details.

💕 Loved My Work?

🚨 Follow me on GitHub

⭐ Give a star to this project

☎️ Contact

For inquiries or collaborations

^{Copyright © 2025 Shinei Nouzen All Rights Reserved}