Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Python wrapper for the Jikan API

Project description


Travis (.org) Codecov pypi Version PyPi downloads Code style: black PRs Welcome

Jikanpy is a Python wrapper for Jikan, providing bindings for all API functionality, and supports Python 3.6+. Because it is intended to be pretty much identical, please consult Jikan's documentation for thornier details on how it is meant to be used. Perhaps most importantly, Jikanpy does not make any attempts to rate limit itself, so use it as responsibly as you would use the API primitively and remember that Jikan API has limitations, check out this section of documentation in order to see to what extent the API is limited or throttled.

In addition to the typical response from the API, each response contains two additional fields:

  • jikan_url: The URL that was requested; for example:
  • headers: The response headers from Jikan, detailed here.


$ pip install jikanpy


from jikanpy import Jikan
jikan = Jikan()

# json of all anime info specified by Jikan docs
mushishi = jikan.anime(457)

# same as above, but with extra info
# see Jikan docs for information about which endpoints have which extensions
mushishi_with_eps = jikan.anime(457, extension='episodes')
mushishi_with_eps_2 = jikan.anime(457, extension='episodes', page=2)
mushishi_with_characters_and_staff = jikan.anime(457, extension='characters_staff')

# you can also query characters
ginko = jikan.character(425)

# and manga
mushishi_manga = jikan.manga(418)

# search up people too
kana_hanazawa = jikan.person(185)

# search
search_result ='anime', 'Mushishi')
# add a page number to the search request
search_result ='anime', 'Mushishi', page=2)
# add a filter to the search (see Jikan docs about what filters are legal)
search_result ='anime', 'Mushishi', parameters={'type': 'tv'})
search_result ='anime', 'Mushishi', parameters={'genre': 37})
# use multiple query parameters
search_result ='anime', 'Mushishi', parameters={'genre': 37, 'type': 'tv'})
# use it all!
search_result ='anime', 'Mushishi', page=3, parameters={'genre': 37, 'type': 'tv'})

# seasonal anime
winter_2018 = jikan.season(year=2018, season='winter')
spring_2016 = jikan.season(year=2016, season='spring')

# all the years and seasons on MAL
archive = jikan.season_archive()

# anime in upcoming seasons
later = jikan.season_later()

# scheduled anime
scheduled = jikan.schedule()
# add a day of the week if you only want the day's schedule
monday = jikan.schedule(day='monday')

# top anime
top_anime ='anime')
# add a page and subtype if you want
top_anime ='anime', page=2, subtype='upcoming')

# action anime
# See Jikan docs for mappings between genres and their IDs
action = jikan.genre(type='anime', genre_id=1)
# adventure manga
adventure = jikan.genre(type='manga', genre_id=2)

# anime made by Studio Deen (sasuga deen)
studio_deen_anime = jikan.producer(producer_id=37)
# add an optional page
studio_deen_anime = jikan.producer(producer_id=37, page=2)

# manga from Weekly Shounen Jump
jump = jikan.magazine(magazine_id=83)
# add an optional page
jump = jikan.magazine(magazine_id=83, page=2)

# user info
nekomata1037 = jikan.user(username='Nekomata1037')
# get profile info, same as above
nekomata1037 = jikan.user(username='Nekomata1037', request='profile')
# friends info
nekomata1037 = jikan.user(username='Nekomata1037', request='friends')
# history of anime/manga
nekomata1037 = jikan.user(username='Nekomata1037', request='history')
# anime list
nekomata1037 = jikan.user(username='Nekomata1037', request='animelist')
nekomata1037 = jikan.user(username='Nekomata1037', request='animelist', argument='completed', page=2)
# manga list
xinil = jikan.user(username='Xinil', request='mangalist')
xinil = jikan.user(username='Xinil', request='mangalist', argument='all')
# user info filters (see Jikan docs for valid filters)
nekomata1037 = jikan.user(username='Nekomata1037', request='animelist', parameters={'year': 2019})

# clubs
fantasy_anime_league =

# meta info about the Jikan REST API
# meta info about what requests have been done
requests = jikan.meta(request='requests', type='anime', period='today')
# meta info about API's status
status = jikan.meta(request='status', type='anime', period='today')

Async Usage

import asyncio
from jikanpy import AioJikan

loop = asyncio.get_event_loop()

async def main(loop):
    aio_jikan = AioJikan(loop=loop)

    mushishi = await aio_jikan.anime(457)
    fma = await aio_jikan.manga(25)
    ginko = await aio_jikan.character(425)
    kana_hanazawa = await aio_jikan.person(185)
    naruto = await'anime', query='naruto')
    winter_2018 = await aio_jikan.season(year=2018, season='winter')
    archive = await aio_jikan.season_archive()
    later = await aio_jikan.season_later()
    monday = await aio_jikan.schedule(day='monday')
    top_anime = await'anime')
    meta = await aio_jikan.meta(request='requests', type='anime', period='today')
    action = await aio_jikan.genre(type='anime', genre_id=1)
    deen = await aio_jikan.producer(producer_id=37)
    jump = await aio_jikan.magazine(magazine_id=83)
    nekomata1037 = await aio_jikan.user(username='Nekomata1037')
    fantasy_anime_league = await
    # Close the connection to Jikan API
    await aio_jikan.close()


Overriding default settings in Jikan and AioJikan with constructor arguments

If you're running an instance of jikan-rest on your system, and want to use that instead of, you can pass that to Jikan:

from jikanpy import Jikan
jikan = Jikan(selected_base='http://localhost:8000/v3/')

You can also choose whether or not to use the HTTPS version of the URL or not, which defaults to True.

from jikanpy import Jikan
jikan_1 = Jikan()               # HTTPS
jikan_2 = Jikan(use_ssl=True)   # HTTPS
jikan_3 = Jikan(use_ssl=False)  # HTTP

If you want to use your own Requests session, you can do that too.

import requests
from jikanpy import Jikan

session = requests.Session()
# Set custom persistent headers that will be used with all HTTP requests with your session
session.headers.update({'x-test': 'true'})

jikan = Jikan(session=session)

You can use any or all of these constructor arguments when creating an instance of Jikan.

AioJikan also has selected_base, use_ssl, and session (although AioJikan uses AioHTTP session, not Requests), but also has loop, to provide your own asynchronous event loop.

import aiohttp
import asyncio

from jikanpy import AioJikan

loop = asyncio.get_event_loop()

async def main(loop):
    # Construct AioJikan with own base URL and custom AioHTTP session with custom persistent headers and event loop
    session = aiohttp.ClientSession(loop=loop, headers={'x-test': 'true'})
    aio_jikan_1 = AioJikan(selected_base='http://localhost:8000/v3/', session=session)

    # Construct AioJikan with HTTP URL and event loop that will be used in internal AioHTTP session
    aio_jikan_2 = AioJikan(use_ssl=False, loop=loop)

    await aio_jikan_1.close()
    await aio_jikan_2.close()



# In root of repository
$ pytest

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for jikanpy, version 3.4.1
Filename, size File type Python version Upload date Hashes
Filename, size jikanpy-3.4.1-py3-none-any.whl (13.5 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size jikanpy-3.4.1.tar.gz (13.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page