jikan

README

jikan-go

A simple Jikan v4 client for Golang.

[!CAUTION] This is not a production-ready implementation for use-cases outside of MinnaSync. Use this with immense caution. The library is immensely incomplete and lacks many features. If there is a feature that you need implemented, feel free to create a pull request implementing the feature. If you have a bug report for any existing features, please make an issue or pull request.

Caching

Basic Caching

The library itself supports basic caching methods. At the moment, only Redis is supported. You must have the JSON module loaded for this to work. A basic implementation is shown below.

package main

import (
    "github.com/minnasync/jikan-go"
    "github.com/go-redis/redis/v9"
)

func initRedis() *redis.Client {
	opts := &redis.Options{
        Addr:     "localhost:6379",
        DB:       0,
	}

	return redis.NewClient(opts)
}

func main() {
    redisClient := initRedis()
    client = jikan.NewClient(jikan.WithRedisCache(redisClient))
}

Advanced Caching

If you have an advanced usecase and do not like how the caching works, you can implement your own caching manager by having it implement the jikan.Cache interface.

package main

import (
    "github.com/minnasync/jikan-go"
)

type CustomCache struct {}

func NewCustomCache() jikan.Cache {
    return &CustomCache{}
}

func (c *CustomCache) Get(ctx context.Context, key string, v any) error {}
func (c *CustomCache) Set(ctx context.Context, key string, v any, ttl time.Duration) error {}
func (c *CustomCache) DeferSet(ctx context.Context, key string, v any, ttl time.Duration) {}
func (c *CustomCache) BulkSet(ctx context.Context, keyValues map[string]any, ttl time.Duration) error {}
func (c *CustomCache) DeferBulkSet(ctx context.Context, keyValues map[string]any, ttl time.Duration) {}
func (c *CustomCache) Delete(ctx context.Context, key string) error {}

func main() {
    cache := NewCustomCache()
    client = jikan.NewClient(jikan.WithCache(cache))
}

Documentation

Index

• type AiredInfo
• type Anime
  • func (a *Anime) IsExplicit() bool
• type AnimeEndpoints
  • func (s *AnimeEndpoints) GetById(ctx context.Context, id string) (*Anime, *Response, error)
  • func (s *AnimeEndpoints) GetFullById(ctx context.Context, id string) (*AnimeFull, *Response, error)
  • func (s *AnimeEndpoints) GetSearch(ctx context.Context, query string, values *url.Values) (*PaginatedResponseBody[Anime], *Response, error)
• type AnimeFull
• type BroadcastInfo
• type Cache
  • func NewRedisCache(client *redis.Client) Cache
• type Client
  • func NewJikanClient(options ...ClientOption) *Client
  • func (c *Client) Do(ctx context.Context, req *http.Request, v any) (*http.Response, error)
  • func (c *Client) NewGETRequest(path string) (*http.Request, error)
• type ClientOption
  • func WithCache(cache Cache) ClientOption
  • func WithRedisCache(client *redis.Client) ClientOption
• type Entity
• type Image
• type Images
  • func (i Images) GetPoster() *string
• type Link
• type PaginatedResponseBody
• type Pagination
• type PaginationItems
• type RedisCache
  • func (c *RedisCache) BulkSet(ctx context.Context, keyValues map[string]any, ttl time.Duration) error
  • func (c *RedisCache) DeferBulkSet(ctx context.Context, keyValues map[string]any, ttl time.Duration)
  • func (c *RedisCache) DeferSet(ctx context.Context, key string, v any, ttl time.Duration)
  • func (c *RedisCache) Delete(ctx context.Context, key string) error
  • func (c *RedisCache) Get(ctx context.Context, key string, v any) error
  • func (c *RedisCache) Set(ctx context.Context, key string, v any, ttl time.Duration) error
• type Relation
• type Response
• type ResponseBody
• type SeasonsEndpoints
  • func (s *SeasonsEndpoints) Now(ctx context.Context, query *url.Values) (*PaginatedResponseBody[Anime], *Response, error)
• type Theme
• type Title
• type TopEndpoints
  • func (s *TopEndpoints) GetTopAnime(ctx context.Context, query *url.Values) (*PaginatedResponseBody[Anime], *Response, error)
• type Trailer

Types

type AiredInfo

type AiredInfo struct {
	From string `json:"from"`
	To   string `json:"to"`
}

type Anime

type Anime struct {
	MalID           int           `json:"mal_id"`
	URL             string        `json:"url"`
	Images          Images        `json:"images"`
	Trailer         Trailer       `json:"trailer"`
	Approved        bool          `json:"approved"`
	Titles          []Title       `json:"titles"`
	Title           string        `json:"title"`
	TitleEN         string        `json:"title_english"`
	TitleJP         string        `json:"title_japanese"`
	TitleSynonyms   []string      `json:"title_synonyms"`
	Type            *string       `json:"type"`
	Source          *string       `json:"source"`
	Episodes        *int          `json:"episodes"`
	Status          *string       `json:"status"`
	Airing          bool          `json:"airing"`
	Aired           AiredInfo     `json:"aired"`
	Duration        *string       `json:"duration"`
	Rating          *string       `json:"rating"`
	Score           *float64      `json:"score"`
	ScoredBy        *int          `json:"scored_by"`
	Rank            *int          `json:"rank"`
	Popularity      *int          `json:"popularity"`
	Members         *int          `json:"members"`
	Favorites       *int          `json:"favorites"`
	Synopsis        *string       `json:"synopsis"`
	Background      *string       `json:"background"`
	Season          *string       `json:"season"`
	Year            *int          `json:"year"`
	Broadcast       BroadcastInfo `json:"broadcast"`
	Producers       []Entity      `json:"producers"`
	Licensors       []Entity      `json:"licensors"`
	Studios         []Entity      `json:"studios"`
	Genres          []Entity      `json:"genres"`
	ExplicityGenres []Entity      `json:"explicit_genres"`
	Themes          []Entity      `json:"themes"`
	Demographics    []Entity      `json:"demographics"`
}

func (*Anime) IsExplicit

func (a *Anime) IsExplicit() bool

IsExplicit will check the rating to determine if the anime is considered explicit.

type AnimeEndpoints

type AnimeEndpoints service

func (*AnimeEndpoints) GetById

func (s *AnimeEndpoints) GetById(ctx context.Context, id string) (*Anime, *Response, error)

GetById returns an anime resource.

https://docs.api.jikan.moe/#/anime/getanimebyid

func (*AnimeEndpoints) GetFullById

func (s *AnimeEndpoints) GetFullById(ctx context.Context, id string) (*AnimeFull, *Response, error)

GetFullById returns a complete anime resource.

https://docs.api.jikan.moe/#/anime/getanimefullbyid

func (*AnimeEndpoints) GetSearch

func (s *AnimeEndpoints) GetSearch(ctx context.Context, query string, values *url.Values) (*PaginatedResponseBody[Anime], *Response, error)

GetSearch will search for an anime based on a query.

https://docs.api.jikan.moe/#/anime/getanimesearch

type AnimeFull

type AnimeFull struct {
	Anime

	Relations []Relation `json:"relations"`
	Theme     Theme      `json:"theme"`
	External  []Link     `json:"external"`
	Streaming []Link     `json:"streaming"`
}

type BroadcastInfo

type BroadcastInfo struct {
	Day      string `json:"day"`
	Time     string `json:"time"`
	Timezone string `json:"timezone"`
}

type Cache

type Cache interface {
	// Get will get a value from the cache.
	Get(ctx context.Context, key string, value any) error
	// Set will set a value in the cache.
	Set(ctx context.Context, key string, value any, ttl time.Duration) error
	// DeferSet will set a value in the cache, but will not wait for the operation to complete.
	DeferSet(ctx context.Context, key string, value any, ttl time.Duration)
	// BulkSet will set multiple values in the cache.
	BulkSet(ctx context.Context, keyValues map[string]any, ttl time.Duration) error
	// DeferBulkSet will set multiple values in the cache, but will not wait for the operation to complete.
	DeferBulkSet(ctx context.Context, keyValues map[string]any, ttl time.Duration)
	// Delete will delete a value from the cache.
	Delete(ctx context.Context, key string) error
}

func NewRedisCache

func NewRedisCache(client *redis.Client) Cache

NewRedisCache will create a new cache manager for Redis that implements the Cache interface.

This will only use JSON commands, so your Redis server must have the JSON module loaded.

type Client

type Client struct {
	Anime   *AnimeEndpoints
	Seasons *SeasonsEndpoints
	Top     *TopEndpoints
	// contains filtered or unexported fields
}

func NewJikanClient

func NewJikanClient(options ...ClientOption) *Client

NewJikanClient will create a new, default client.

func (*Client) Do

func (c *Client) Do(ctx context.Context, req *http.Request, v any) (*http.Response, error)

Do will execute an HTTP request.

func (*Client) NewGETRequest

func (c *Client) NewGETRequest(path string) (*http.Request, error)

NewGETRequest will create a new GET request only.

Jikan only supports GET requests, refer to documentation. https://docs.api.jikan.moe/#/section/information/allowed-http(s)-requests

type ClientOption

type ClientOption func(*Client)

func WithCache

func WithCache(cache Cache) ClientOption

WithCache will enable caching with a custom cache manager.

func WithRedisCache

func WithRedisCache(client *redis.Client) ClientOption

WithRedisCache will enable redis caching.

type Entity

type Entity struct {
	MalID int    `json:"mal_id"`
	Type  string `json:"type"`
	Name  string `json:"name"`
	URL   string `json:"url"`
}

type Image

type Image struct {
	ImageURL string `json:"image_url"`
	SmallURL string `json:"small_image_url"`
	LargeURL string `json:"large_image_url"`
}

type Images

type Images map[string]Image

func (Images) GetPoster

func (i Images) GetPoster() *string

GetPoster will get the highest resolution poster image.

type Link

type Link struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

type PaginatedResponseBody

type PaginatedResponseBody[T any] struct {
	Data []T `json:"data"`
}

type Pagination

type Pagination struct {
	LastVisiblePage int             `json:"last_visible_page"`
	HasNextPage     bool            `json:"has_next_page"`
	CurrentPage     int             `json:"current_page"`
	Items           PaginationItems `json:"items"`
}

type PaginationItems

type PaginationItems struct {
	Count   int `json:"count"`
	Total   int `json:"total"`
	PerPage int `json:"per_page"`
}

type RedisCache

type RedisCache struct {
	// contains filtered or unexported fields
}

func (*RedisCache) BulkSet

func (c *RedisCache) BulkSet(ctx context.Context, keyValues map[string]any, ttl time.Duration) error

func (*RedisCache) DeferBulkSet

func (c *RedisCache) DeferBulkSet(ctx context.Context, keyValues map[string]any, ttl time.Duration)

func (*RedisCache) DeferSet

func (c *RedisCache) DeferSet(ctx context.Context, key string, v any, ttl time.Duration)

func (*RedisCache) Delete

func (c *RedisCache) Delete(ctx context.Context, key string) error

func (*RedisCache) Get

func (c *RedisCache) Get(ctx context.Context, key string, v any) error

func (*RedisCache) Set

func (c *RedisCache) Set(ctx context.Context, key string, v any, ttl time.Duration) error

type Relation

type Relation struct {
	Relation string   `json:"relation"`
	Entry    []Entity `json:"entry"`
}

type Response

type Response struct {
	IsCached bool
	Response *http.Response
}

type ResponseBody

type ResponseBody[T any] struct {
	Data T `json:"data"`
}

type SeasonsEndpoints

type SeasonsEndpoints service

func (*SeasonsEndpoints) Now

func (s *SeasonsEndpoints) Now(ctx context.Context, query *url.Values) (*PaginatedResponseBody[Anime], *Response, error)

Now will return the list of anime airing in the current season To filter results, pass in query parameters. Refer to documentation for accepted parameters.

https://docs.api.jikan.moe/#/seasons/getseasonnow

type Theme

type Theme struct {
	Openings []string `json:"openings"`
	Endings  []string `json:"endings"`
}

type Title

type Title struct {
	Type  string `json:"type"`
	Title string `json:"title"`
}

type TopEndpoints

type TopEndpoints service

func (*TopEndpoints) GetTopAnime

func (s *TopEndpoints) GetTopAnime(ctx context.Context, query *url.Values) (*PaginatedResponseBody[Anime], *Response, error)

GetTopAnime will return the top anime. To filter results, pass in query parameters. Refer to documentation for accepted parameters.

https://docs.api.jikan.moe/#/top/gettopanime

type Trailer

type Trailer struct {
	YoutubeID string `json:"youtube_id"`
	URL       string `json:"url"`
	EmbedURL  string `json:"embed_url"`
}