DOCSEARCHbyAlgolia
Submit Docs

Jikan REST API

repository·master·Indexed 19 days ago

https://github.com/jikan-me/jikan-rest

An unofficial REST API for MyAnimeList.net that scrapes the website to provide structured data for anime and manga. Jikan v4 is designed for read-only data access and does not support authenticated user actions. It can be deployed as a containerized application via Docker or accessed through a public hosted API. The project includes a suite of CLI indexer commands for synchronizing anime, manga, genres, producers, and seasonal data into a local database.

Tokens
7.2K
Snippets
43
Records
47
Agent score
69%

What's inside Jikan

  1. Overview of Jikan REST API v4

    master

    Jikan is an unofficial REST API for MyAnimeList.net. It functions by scraping MyAnimeList.net to provide API functionality that the official site lacks. It is designed to help developers access anime and manga data without building their own parsers or relying on unstable official APIs.

    Important Limitations:

    • No Authentication: Jikan does not support authenticated requests. You cannot use it to update user lists. For list management, use the official MyAnimeList API.
    • Version Note: This repository is for v4. The v3 branch is discontinued and will not receive updates.

  2. Quickstart Jikan API using the container setup script

    master

    The easiest way to start a production-ready Jikan API setup (including redis, typesense, and mongodb) on Linux is using the provided CLI script. The script prompts you for required credentials and configures MongoDB to use a 1GB memory limit and enables CORS headers.

    Prerequisites:

    • git
    • docker or podman
    • docker-compose or podman-compose

    Note for Podman users: If container name resolution fails on the container network, you may need to install the aardvark-dns package (especially on Arch Linux which uses netavark by default).

    # After checking out the repository
./container-setup.sh start

  3. Update Jikan API to a newer version

    master

    To update your local container setup to a newer version:

    1. Stop the current application.
    2. Remove the existing jikan-api image.
    3. Pull the new image and set the JIKAN_API_VERSION environment variable to your desired tag (e.g., latest or a specific version like v4.0.0-11).
    ./container-setup.sh stop

# Pull and start with a specific version
JIKAN_API_VERSION=latest ./container-setup.sh start

  4. Configure Jikan API via Docker Compose

    master

    You can use docker-compose up directly, but you must manually create the following secret files in the same directory as your docker-compose.yml to provide credentials:

    • db_admin_password.txt
    • db_admin_username.txt
    • db_password.txt
    • db_username.txt
    • redis_password.txt
    • typesense_api_key.txt

    Customization of the API (like disabling CORS) can be done via the ./docker/config/.env.compose file. You can also adjust MongoDB memory usage using the MONGO_CACHE_SIZE_GB environment variable (default is 1).

    docker-compose up

  5. Populate the database using the indexer

    master

    A fresh installation of the Jikan API will have an empty database. You must run the indexers to scrape and populate data from MyAnimeList (MAL).

    Warning: This process can take 4-5 days. If interrupted, you must manually resume indexing; otherwise, the command will restart from the beginning. You can run it in the background using &.

    # Run the full indexer (may take days)
./container-setup.sh execute-indexers

# Run in the background
./container-setup.sh execute-indexers &

  7. Install Jikan via Docker

    master

    You can run Jikan as a containerized application. This is the fastest way to deploy your own instance. Ensure you have a .env file in your current directory to provide necessary configuration to the container.

    docker run -d --name=jikan-rest -p 8080:8080 -v ./.env:/app/.env jikanme/jikan-rest:latest

  8. Run Jikan API with Podman health checks

    master

    When building the image yourself with Podman, the image format is OCI by default. To ensure health checks function correctly, you must provide a specific health check command during podman run.

    podman run -d --name=jikan-rest -p 8080:8080 -v ./.env:/app/.env --health-start-period=5s --health-cmd="curl --fail http://localhost:2114/health?plugin=http || exit 1" jikan-rest:nightly

  9. Deploy Jikan REST via Docker Compose

    master

    You can deploy the full Jikan REST stack using Docker Compose. The setup includes the jikan_rest API service, mongodb for data storage, redis for caching, and typesense for search functionality.

    Key Configuration Requirements

    Environment Variables

    Several parameters can be tuned via environment variables or an .env file:

    • _JIKAN_API_VERSION: Specifies the version of the Jikan API image to use (defaults to latest).
    • APP_UID / APP_GID: Sets the user and group ID for the jikan_rest process (defaults to 10001).
    • MONGO_CACHE_SIZE_GB: Configures the WiredTiger cache size for MongoDB (defaults to 1.0).

    Secrets

    The deployment relies on Docker secrets for sensitive credentials. You must provide the following files in your environment:

    • db_username.txt / db_password.txt: Database credentials.
    • db_admin_username.txt / db_admin_password.txt: MongoDB admin credentials.
    • redis_password.txt: Redis authentication password.
    • typesense_api_key.txt: Typesense API key.

    Networking and Ports

    • Jikan REST API: Accessible on port 8080.
    • MongoDB: Port 27017.
    • Redis: Port 6379.
    • Typesense: Port 8108.

    Configuration File

    The jikan_rest service loads additional configuration from ./docker/config/.env.compose.

    # Example of how the service is defined in docker-compose.yml
services:
  jikan_rest:
    image: "docker.io/jikanme/jikan-rest:${_JIKAN_API_VERSION:-latest}"
    user: "${APP_UID:-10001}:${APP_GID:-10001}"
    ports:
      - '8080:8080/tcp'
    env_file:
      - ./docker/config/.env.compose