Kinopoisk Film Enricher

Enrich film and serial (TV series) notes with data from Kinopoisk — descriptions, ratings, posters, and links — via the Kinopoisk Unofficial API.

Features

• Search by title — looks up the active note (or all notes) on Kinopoisk
• Film and serial (TV series) support — auto-detects whether a note is a film or a serial, and prefers the matching Kinopoisk entry type (FILM vs TV_SERIES) when matching by title
• Smart match — exact title match is preferred (with the expected type first); on multiple candidates a modal lists name, year and short description so you can pick the right entry
• Per-type data mapping — films and serials have separate field→property mappings (tabs in settings): you can enrich films and TV series into different properties without affecting each other
• Configurable note detection — the plugin decides which notes are films and which are serials by a property + value pair you set for each (default: type: film and type: serial); no more hardcoded type: film
• Bulk enrichment — enrich every film note, every serial note, or both at once from the settings page (buttons appear only when detection is configured); already-enriched notes are skipped
• Local posters — downloads the poster and stores it locally: [[Films_posters/<id>.jpg]] for films, [[TV_series_posters/<id>.jpg]] for serials (directories are configurable)
• Seasons for TV series — two serial-only fields computed from the /seasons endpoint: seasons (all seasons except the pilot) and released_seasons (only aired seasons, excluding scheduled/upcoming ones and the pilot)
• API key rotation — add as many keys as you like; keys are tried in order and rotated automatically on quota exhaustion (402/403)
• Local API cache — responses are cached as JSON in the vault, so re-enriching and re-opening notes does not burn quota
• Quota check — one-tap notice with used/remaining requests and reset time
• Update checks — queries GitHub releases for a newer version (command, settings button, optional silent check on startup)
• Graceful errors — actionable notices (missing key, exhausted quota, API down) instead of stack traces

Installation

1. Copy the plugin folder to your vault's .obsidian/plugins/ directory
2. Enable the plugin in Settings → Community plugins

Setup

1. API Keys — add at least one key from kinopoiskapiunofficial.tech (required)
2. Film note detection — pick the property and value that mark a note as a film
   • Property name, e.g. type
   • Expected value, e.g. film
   • Matching is case-insensitive; a note must have the property and its value must equal the expected value
3. Serial note detection — same as films, for TV series (default type / serial)
4. Data Mapping — separate tabs for Films and Serials; type the target property for each API field (type-ahead suggests existing properties), leave empty to disable the field
5. Behavior — overwrite existing values, and what to do when a property is missing from the note
6. Directories — poster directory for films (default Films_posters), poster directory for serials (default TV_series_posters), and cache directory (default .kinopoisk-cache)

Settings

Commands

• Enrich current note (film/serial) from Kinopoisk — fill the active note (auto-detects film vs serial)
• Enrich all film notes from Kinopoisk — batch-enrich every film note (skips notes that already have the mapped Kinopoisk URL property)
• Enrich all serial notes from Kinopoisk — batch-enrich every serial/TV-series note
• Enrich all film and serial notes from Kinopoisk — one pass over both types
• Check Kinopoisk API quota — show used/remaining requests
• Check for plugin updates — query GitHub releases and notify if a newer version exists

Usage

1. Make sure your notes carry the detection property/value, e.g.

   ---
   type: film
   status: false
   rating: 8.7
   ---
   

   and for a TV series:

   ---
   type: serial
   status: false
   rating: 8.7
   ---
   

2. Set Film note detection (property type, value film) and Serial note detection (property type, value serial) in the plugin settings
3. Run Enrich current note (or an Enrich all … button from settings / the command palette)
4. The plugin fills the mapped properties — by default:
   • kinopoisk — link to the Kinopoisk page
   • kp_rating — Kinopoisk rating
   • description — description (multi-line, written as a YAML block scalar)
   • poster — [[Films_posters/<id>.jpg]] for films, [[TV_series_posters/<id>.jpg]] for serials (local embed)
   • For serials only, also:
     • seasons — total seasons excluding the pilot (number 0)
     • released_seasons — aired seasons only (excludes the pilot and upcoming/scheduled seasons)
5. The Data Mapping tabs work per note type, so a film can write to one property while a serial writes to another (e.g. films → description, serials → synopsis)

Error handling

You get an actionable notice, not a stack trace:

• No key configured → points to Settings → Kinopoisk Plugin → API Keys
• All keys exhausted (402/403) → rotation continues automatically; the final message explains quota
• Network/API failure → checklist: connection, API availability, key validity, retry

API

Uses the Kinopoisk Unofficial API (kinopoiskapiunofficial.tech). Free tier: 500 requests/day.

License

MIT