RanobeDB API v0

Introduction

This page describes the use of RanobeDB's public API to query information from its database. This API is marked as v0 and is still in development and missing some features.

This API is for non-commercial use only and the data is licensed under the Open Database License and the Database Contents License.

You can visit the #development channel on our Discord server to ask for any help or if you have any questions.

Usage

API endpoint: https://ranobedb.org/api/v0

Successful responses will return 200 OK with content-type: application/json. An unsuccessful response will have a 4xx - 5xx code.

The responses of each endpoint are given as TypeScript types.

The search params used in the endpoints are similar to the ones used on the website. You can visit a page and add some filters to see what the url search params should look like. For example, /books?q=seishun+buta+yarou&rl=en&rll=or&rf=print&rfl=or&sort=Relevance+desc&staff=195&sl=and&p=41&pl=or.

There are currently no rate-limits, but please do not exceed over 60 requests in 1 minute.

The API currently only supports read-only endpoints. Other features (like user lists) may be added in the feature.

Database querying

Common types

Language 'ja' | 'en' | 'zh-Hans' | 'zh-Hant' | 'fr' | 'es' | 'ko' | 'ar' | 'bg' | 'ca' | 'cs' | 'ck' | 'da' | 'de' | 'el' | 'eo' | 'eu' | 'fa' | 'fi' | 'ga' | 'gd' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'iu' | 'mk' | 'ms' | 'la' | 'lt' | 'lv' | 'nl' | 'no' | 'pl' | 'pt-pt' | 'pt-br' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'ta' | 'th' | 'tr' | 'uk' | 'ur' | 'vi'

Books

GET /books

Params
q string page number limit number Default 24; Max: 100 rl Language[] Release lanuages rll 'and' | 'or' Release lanuages logic rf ('digital' | 'print' | 'audio')[] Release formats rfl 'and' | 'or' Release formats logic staff number[] The id of staff sl 'and' | 'or' Staff logic p number[] The id of publishers pl 'and' | 'or' Publisher logic sort 'Relevance desc' | 'Relevance asc' | 'Title asc' | 'Title desc' | 'Release date asc' | 'Release date desc'
Response
{
    books:  {
        id: number;
        title: string;
        lang: Language;
        romaji: string | null;
        image_id: number | null;
        olang: Language;
        release_date: number;
        title_orig: string | null;
        romaji_orig: string | null;
        image: {
            id: number;
            filename: string;
            height: number;
            nsfw: boolean;
            spoiler: boolean;
            width: number;
        } | null;
    }[];
    count: string;
    currentPage: number;
    totalPages: number;
}

GET /book/[id]

Response
{
    description: string;
    lang: Language;
    id: number;
    romaji: string | null;
    description_ja: string;
    hidden: boolean;
    image_id: number | null;
    olang: Language;
    locked: boolean;
    release_date: number;
    title: string;
    title_orig: string | null;
    romaji_orig: string | null;
    image: {
        id: number;
        filename: string;
        height: number;
        nsfw: boolean;
        spoiler: boolean;
        width: number;
    } | null;
    titles: {
        lang: Language;
        romaji: string | null;
        book_id: number;
        official: true;
        title: string;
    }[];
    editions: {
        book_id: number;
        lang: Language | null;
        title: string;
        eid: number;
        staff: {
            note: string;
            role_type: "editor" | "staff" | "author" | "artist" | "translator" | "narrator";
            romaji: string | null;
            name: string;
            staff_id: number;
            staff_alias_id: number;
        }[];
    }[];
    releases: {
        lang: Language;
        id: number;
        romaji: string | null;
        description: string;
        hidden: boolean;
        locked: boolean;
        release_date: number;
        title: string;
        website: string | null;
        amazon: string | null;
        bookwalker: string | null;
        format: "digital" | "print" | "audio";
        isbn13: string | null;
        pages: number | null;
        rakuten: string | null;
    }[];
    publishers: {
        lang: Language;
        id: number;
        romaji: string | null;
        name: string;
        publisher_type: "publisher" | "imprint";
    }[];
    series: {
        books: {
            id: number;
            lang: Language;
            romaji: string | null;
            title: string;
            title_orig: string | null;
            romaji_orig: string | null;
            image: {
                id: number;
                filename: string;
                height: number;
                nsfw: boolean;
                spoiler: boolean;
                width: number;
            } | null;
        }[];
        tags: {
            id: number;
            name: string;
            ttype: "tag" | "content" | "demographic" | "genre";
        }[];
        lang: Language;
        id: number;
        romaji: string | null;
        title: string;
        title_orig: string | null;
        romaji_orig: string | null;
    } | undefined
}

Series

GET /series

Params
q string page number limit number Default 24; Max: 100 pubStatus 'ongoing' | 'completed' | 'hiatus' | 'stalled' | 'cancelled' | 'unknown' genresInclude number[] genresExclude number[] tagsInclude number[] tagsExclude number[] til 'and' | 'or' Tags include logic tel 'and' | 'or' Tags exclude logic rl Language[] Release lanuages rll 'and' | 'or' Release lanuages logic rf ('digital' | 'print' | 'audio')[] Release formats rfl 'and' | 'or' Release formats logic staff number[] The id of staff sl 'and' | 'or' Staff logic p number[] The id of publishers pl 'and' | 'or' Publisher logic sort 'Relevance desc' | 'Relevance asc' | 'Title asc' | 'Title desc' | 'Start date asc' | 'Start date desc' | 'End date asc' | 'End date desc' | 'Num. books asc' | 'Num. books desc'
Response
{
    series: {
        book: {
            id: number;
            image: {
                id: number;
                filename: string;
                height: number;
                nsfw: boolean;
                spoiler: boolean;
                width: number;
            } | null;
        } | null;
        volumes: {
            count: string | number | bigint;
        } | null;
        id: number;
        lang: "id" | "ja" | "en" | "zh-Hans" | "zh-Hant" | "fr" | "es" | "ko" | "ar" | "bg" | "ca" | "cs" | "ck" | "da" | "de" | ... 35 more
        romaji: string | null;
        hidden: boolean;
        locked: boolean;
        title: string;
        olang: "id" | "ja" | "en" | "zh-Hans" | "zh-Hant" | "fr" | "es" | "ko" | "ar" | "bg" | "ca" | "cs" | "ck" | "da" | "de" | ... 35 more
        c_num_books: number;
        title_orig: string | null;
        romaji_orig: string | null;
    }[];
    count: string;
    currentPage: number;
    totalPages: number;
}

GET /series/[id]

Response
{
    id: number;
    lang: Language;
    romaji: string | null;
    title: string;
    hidden: boolean;
    locked: boolean;
    description: string;
    olang: Language;
    bookwalker_id: number | null;
    wikidata_id: number | null;
    aliases: string;
    publication_status: "unknown" | "ongoing" | "completed" | "hiatus" | "stalled" | "cancelled";
    anidb_id: number | null;
    start_date: number;
    end_date: number;
    web_novel: string | null;
    title_orig: string | null;
    romaji_orig: string | null;
    book_description: {
        description: string;
        description_ja: string;
    } | null;
    books: {
        book_type: "main" | "sub";
        sort_order: number;
        id: number;
        lang: Language;
        romaji: string | null;
        title: string;
        image_id: number | null;
        release_date: number;
        title_orig: string | null;
        romaji_orig: string | null;
        image: {
            id: number;
            filename: string;
            height: number;
            nsfw: boolean;
            spoiler: boolean;
            width: number;
        } | null;
    }[];
    titles: {
        lang: Language;
        romaji: string | null;
        official: true;
        title: string;
    }[];
    child_series: {
        id: number;
        relation_type: "prequel" | "sequel" | "side story" | "main story" | "spin-off" | "parent story" | "alternate version";
        lang: Language;
        romaji: string | null;
        title: string;
    }[];
    publishers: {
        id: number;
        romaji: string | null;
        name: string;
        publisher_type: "publisher" | "imprint";
        lang: Language;
    }[];
    staff: {
        role_type: "staff" | "author" | "artist" | "editor" | "translator" | "narrator";
        note: string;
        romaji: string | null;
        name: string;
        staff_id: number;
        lang: Language;
        staff_alias_id: number;
    }[];
    tags: {
        id: number;
        name: string;
        ttype: "content" | "demographic" | "genre" | "tag";
    }[];
}

Releases

GET /releases

Params
q string page number limit number Default 24; Max: 100 rl Language[] Release lanuages rll 'and' | 'or' Release lanuages logic rf ('digital' | 'print' | 'audio')[] Release formats rfl 'and' | 'or' Release formats logic p number[] The id of publishers pl 'and' | 'or' Publisher logic sort 'Relevance desc' | 'Relevance asc' | 'Title asc' | 'Title desc' | 'Release date asc' | 'Release date desc' | 'Pages asc' | 'Pages desc'

GET /release/[id]

Response
{
    books:  {
        id: number;
        title: string;
        lang: Language;
        romaji: string | null;
        image_id: number | null;
        olang: Language;
        release_date: number;
        title_orig: string | null;
        romaji_orig: string | null;
        image: {
            id: number;
            filename: string;
            height: number;
            nsfw: boolean;
            spoiler: boolean;
            width: number;
        } | null;
    }[];
    count: string;
    currentPage: number;
    totalPages: number;
}

Staff

GET /staff

Params
q string page number limit number (max 100)
Response
{
    staff: {
        id: number;
        name: string;
        romaji: string | null;
    }[];
    count: string;
    currentPage: number;
    totalPages: number;
}

GET /staff/[id]

Response
{
    staff: {
        id: number;
        description: string;
        hidden: boolean;
        locked: boolean;
        bookwalker_id: number | null;
        pixiv_id: number | null;
        twitter_id: string | null;
        website: string | null;
        wikidata_id: number | null;
        romaji: string | null;
        name: string;
        aliases: {
            id: number;
            romaji: string | null;
            main_alias: boolean;
            name: string;
            staff_id: number;
        }[];
    };
}

Publishers

GET /publishers

Params
q string page number limit number (max 100)
Response
{
    publishers: {
        id: number;
        name: string;
        romaji: string | null;
    }[];
    count: string;
    currentPage: number;
    totalPages: number;
}

GET /publisher/[id]

Response
{
    publisher: {
        id: number;
        bookwalker: string | null;
        description: string;
        hidden: boolean;
        locked: boolean;
        name: string;
        romaji: string | null;
        twitter_id: string | null;
        website: string | null;
        wikidata_id: number | null;
        child_publishers: {
            id: number;
            relation_type: "imprint" | "parent brand" | "parent company" | "subsidiary";
            name: string;
            romaji: string | null;
        }[]
    };
}

Tags

GET /tags

Params
q string page number limit number (max 100)
Response
{
    tags: {
        id: number;
        description: string | null;
        name: string;
        ttype: "content" | "demographic" | "genre" | "tag";
        count: string | number | bigint;
    }[];
    count: string;
    totalPages: number;
    currentPage: number;
}