Skip to main content
This guide covers the fundamental operations you’ll need to get started with the ČSFD API. All examples use real, working code from the library’s demo files.

​
Installation

First, install the package: 
npm install node-csfd-api

​
Quick Start

​
Fetching a Movie

Retrieve comprehensive information about a movie or TV series by its ČSFD ID: 
import { csfd } from 'node-csfd-api';

// Using async/await
const movie = await csfd.movie(621073);
console.log(movie.title);
console.log(movie.rating);
console.log(movie.genres);
Finding Movie IDs: You can find the movie ID in the ČSFD URL. For example, https://www.csfd.cz/film/535121 has ID 535121.

​
Searching for Content

Search for movies, TV series, and users across the ČSFD database: 
import { csfd } from 'node-csfd-api';

const results = await csfd.search('Tarantino');

// Access different result types
console.log(results.movies);   // Array of movies
console.log(results.tvSeries); // Array of TV series
console.log(results.users);    // Array of users
1

Import the library

import { csfd } from 'node-csfd-api';
2

Execute search

const results = await csfd.search('matrix');
3

Access results by type

// Loop through movies
results.movies.forEach(movie => {
  console.log(`${movie.title} (${movie.year})`);
});

​
Getting Creator Information

Retrieve detailed information about directors, actors, and other creators: 
import { csfd } from 'node-csfd-api';

const creator = await csfd.creator(2120); // Quentin Tarantino

console.log(creator.name);      // "Quentin Tarantino"
console.log(creator.birthday);  // "27.03.1963"
console.log(creator.bio);       // Biography text
console.log(creator.films);     // Filmography array

​
Getting User Ratings

Fetch user ratings from their ČSFD profile: 
import { csfd } from 'node-csfd-api';

// Get last page of ratings (~50 items)
const ratings = await csfd.userRatings('912');

console.log(ratings.length);
ratings.forEach(rating => {
  console.log(`${rating.title} - ${rating.userRating}/5`);
});

​
Getting User Reviews

Retrieve detailed user reviews: 
import { csfd } from 'node-csfd-api';

// Get user reviews
const reviews = await csfd.userReviews('195357-verbal');

reviews.forEach(review => {
  console.log(`${review.title} (${review.year})`);
  console.log(`Rating: ${review.userRating}/5`);
  console.log(`Review: ${review.text}`);
});

​
Error Handling

Always implement proper error handling when working with the API: 
import { csfd } from 'node-csfd-api';

try {
  const movie = await csfd.movie(535121);
  console.log(movie.title);
} catch (error) {
  console.error('Failed to fetch movie:', error);
  // Handle the error appropriately
}
This is a scraping library. ČSFD may change their HTML structure at any time, which could break the parser. Always implement error handling in production.

​
Complete Example

Here’s a complete example combining multiple operations: 
import { csfd, CSFDMovie } from 'node-csfd-api';
import fs from 'fs';

try {
  // Fetch movie details
  const movie: CSFDMovie = await csfd.movie(2);

  // Generate HTML output
  const html = `
  <!DOCTYPE html>
  <html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>${movie.title}</title>
    <style>
      body { font-family: sans-serif; background: #f9f9f9; padding: 40px; }
      h1 { color: #333; }
    </style>
  </head>
  <body>
    <h1>${movie.title}</h1>
    <p>${movie.descriptions[0]}</p>
    <p><a href="${movie.url}" target="_blank">View on ČSFD</a></p>
  </body>
  </html>
  `;

  fs.writeFileSync('index.html', html);
  console.log(`✅ index.html created with title: ${movie.title}`);
} catch (error) {
  console.error('❌ Error:', error);
}

​
Type Safety

The library is fully typed with TypeScript. Import types as needed: 
import { 
  csfd, 
  CSFDMovie, 
  CSFDCreator, 
  CSFDUserRatings,
  CSFDSearchResults 
} from 'node-csfd-api';

// TypeScript will provide autocomplete and type checking
const movie: CSFDMovie = await csfd.movie(535121);
const creator: CSFDCreator = await csfd.creator(2120);
const ratings: CSFDUserRatings[] = await csfd.userRatings('912');

​
Next Steps

Filtering Ratings

Learn advanced filtering and pagination options

Letterboxd Export

Export your ČSFD ratings to Letterboxd format

Browser Extensions

Use the library in Chrome/Firefox extensions

API Reference

Explore the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us