kinois

README

kino.is Go client

Official Go client for the kino.is API — a movie & TV catalogue with people, ratings, where-to-watch and live cinema showtimes. Zero third-party dependencies (standard library only).

go get github.com/kino-is/sdk-go

Usage

package main

import (
	"fmt"

	kinois "github.com/kino-is/sdk-go"
)

func main() {
	c := kinois.New()
	c.Lang = "en"

	res, err := c.Search("interstellar", "")
	if err != nil {
		panic(err)
	}
	fmt.Println(res["films"])

	film, _ := c.GetFilm(63139, "")
	fmt.Println(film["film"])

	showtimes, _ := c.ShowtimesKZ("almaty")
	fmt.Println(showtimes["cinemas"])
}

API

kinois.New() returns a *Client (BaseURL, Lang, Token, HTTP are exported and settable). All methods return map[string]any (decoded JSON) and an error; non-2xx responses return *kinois.Error.

• Search(query, lang) · GetFilm(id, lang) · GetPerson(id, lang)
• Catalog(url.Values) · NowInCinemas(country, lang) · NowShowing(lang)
• ShowtimesKZ(city) · CinemasUA() · Boxoffice() · Calendar(url.Values) · Lists()

Pass "" for lang to use the client default. Languages: ru en uk kk uz be de he.

Also

TypeScript: @kino-is/sdk · Python: kino-is · OpenAPI spec: kino-is/api · MCP: kino-is/mcp

License

MIT © kino.is

Documentation

Overview

Package kinois is the official Go client for the kino.is API — a movie & TV catalogue with people, ratings, where-to-watch and live cinema showtimes. Zero third-party dependencies.

c := kinois.New()
res, err := c.Search("interstellar", "")

MIT — https://kino.is

Index

• type Client
  • func New() *Client
  • func (c *Client) Boxoffice() (Result, error)
  • func (c *Client) Calendar(params url.Values) (Result, error)
  • func (c *Client) Catalog(params url.Values) (Result, error)
  • func (c *Client) CinemasUA() (Result, error)
  • func (c *Client) GetFilm(id int, lang string) (Result, error)
  • func (c *Client) GetPerson(id int, lang string) (Result, error)
  • func (c *Client) Lists() (Result, error)
  • func (c *Client) NowInCinemas(country, lang string) (Result, error)
  • func (c *Client) NowShowing(lang string) (Result, error)
  • func (c *Client) Search(query, lang string) (Result, error)
  • func (c *Client) ShowtimesKZ(city string) (Result, error)
• type Error
  • func (e *Error) Error() string
• type Result

Types

type Client

type Client struct {
	BaseURL string
	Lang    string // default content language: ru en uk kk uz be de he
	Token   string // optional bearer token (write/user endpoints only)
	HTTP    *http.Client
}

Client talks to the kino.is API.

func New

func New() *Client

New returns a Client with sensible defaults (base https://kino.is, lang "ru").

func (*Client) Boxoffice

func (c *Client) Boxoffice() (Result, error)

Boxoffice returns box-office charts.

func (*Client) Calendar

func (c *Client) Calendar(params url.Values) (Result, error)

Calendar returns the release calendar.

func (*Client) Catalog

func (c *Client) Catalog(params url.Values) (Result, error)

Catalog browses/filters the catalogue (type, genre, year, country, sort, page…).

func (*Client) CinemasUA

func (c *Client) CinemasUA() (Result, error)

CinemasUA returns cinemas in Ukraine with film/session counts.

func (*Client) GetFilm

func (c *Client) GetFilm(id int, lang string) (Result, error)

GetFilm returns full details for a film by its kino.is id.

func (*Client) GetPerson

func (c *Client) GetPerson(id int, lang string) (Result, error)

GetPerson returns a person (actor/director/…) by id: name, birth, filmography.

func (*Client) Lists

func (c *Client) Lists() (Result, error)

Lists returns curated lists.

func (*Client) NowInCinemas

func (c *Client) NowInCinemas(country, lang string) (Result, error)

NowInCinemas lists films currently in cinemas in a country (ISO-2 code). lang may be "".

func (*Client) NowShowing

func (c *Client) NowShowing(lang string) (Result, error)

NowShowing returns the "now showing" set.

func (*Client) Search

func (c *Client) Search(query, lang string) (Result, error)

Search finds films, series, cartoons and anime by title or keywords. lang may be "".

func (*Client) ShowtimesKZ

func (c *Client) ShowtimesKZ(city string) (Result, error)

ShowtimesKZ returns real per-cinema showtimes in Kazakhstan (Kinopark). city may be "".

type Error

type Error struct {
	Status int
	Path   string
	Msg    string
}

Error is returned for non-2xx responses.

func (*Error) Error

func (e *Error) Error() string

type Result

type Result = map[string]any

Result is a decoded JSON object returned by the API.