Skip to main content

​
Quickstart

Get started with node-csfd-api in just a few minutes. This guide will walk you through making your first API calls.

​
Your first API call

1

Install the package

First, install node-csfd-api in your project:
npm install node-csfd-api
2

Import the library

Import the csfd instance in your code:
import { csfd } from 'node-csfd-api';
3

Fetch a movie

Make your first API call to fetch movie details:
import { csfd } from 'node-csfd-api';

// Fetch movie details by ČSFD ID
const movie = await csfd.movie(535121);

console.log(movie.title);      // "Na špatné straně"
console.log(movie.year);       // "2018"
console.log(movie.rating);     // 73
console.log(movie.genres);     // ["Krimi", "Drama", "Thriller"]
4

View the results

Run your code and you’ll see the movie data:
{
  "id": 535121,
  "title": "Na špatné straně",
  "year": "2018",
  "rating": 73,
  "ratingCount": 6654,
  "colorRating": "good",
  "genres": ["Krimi", "Drama", "Thriller"],
  "origins": ["USA", "Kanada"],
  "type": "film",
  "url": "https://www.csfd.cz/film/535121",
  "poster": "https://image.pmgstatic.com/cache/resized/w1080/files/images/film/posters/163/579/163579352_bf8737.jpg"
  // ... and much more
}

​
Common operations

Here are the most common operations you’ll perform with the library:

​
Fetch movie details

Get comprehensive information about a movie or TV series: 
import { csfd } from 'node-csfd-api';

const movie = await csfd.movie(621073);

console.log(movie.title);
console.log(movie.rating);
console.log(movie.creators.directors);
console.log(movie.creators.actors);
console.log(movie.vod); // VOD platforms where available

​
Search for content

Search across movies, TV series, and users: 
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

// Example: Get first movie result
if (results.movies.length > 0) {
  const firstMovie = results.movies[0];
  console.log(firstMovie.title);
  console.log(firstMovie.year);
  console.log(firstMovie.rating);
}

​
Get 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.birthplace); // "Knoxville, Tennessee, USA"
console.log(creator.bio);       // Biography text
console.log(creator.films);     // Filmography array

// Loop through filmography
creator.films.forEach((film) => {
  console.log(`${film.title} (${film.year})`);
});

​
Get user ratings

Access user ratings from ČSFD profiles: 
import { csfd } from 'node-csfd-api';

// Get latest ratings (default: last page, ~50 items)
const ratings = await csfd.userRatings('912');

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

// Get specific page
const page2 = await csfd.userRatings('912', { page: 2 });

// Filter by content type
const onlyMovies = await csfd.userRatings('912', {
  includesOnly: ['film']
});

​
Get user reviews

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

// Get latest reviews
const reviews = await csfd.userReviews('195357');

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

​
Complete example

Here’s a complete example that demonstrates multiple API calls: 
import { csfd } from 'node-csfd-api';

async function main() {
  // Search for Tarantino
  const searchResults = await csfd.search('Tarantino');
  console.log(`Found ${searchResults.movies.length} movies`);

  // Get Tarantino's creator info
  const tarantino = await csfd.creator(2120);
  console.log(`${tarantino.name} was born ${tarantino.birthday}`);
  console.log(`Films directed: ${tarantino.films.length}`);

  // Get details for his first film in the list
  if (tarantino.films.length > 0) {
    const firstFilm = tarantino.films[0];
    const movieDetails = await csfd.movie(firstFilm.id);
    console.log(`\nLatest film: ${movieDetails.title}`);
    console.log(`Rating: ${movieDetails.rating}%`);
    console.log(`Genres: ${movieDetails.genres.join(', ')}`);
  }

  // Get user ratings
  const ratings = await csfd.userRatings('912');
  console.log(`\nUser has rated ${ratings.length} items`);
}

main();

​
Important notes

This is a scraping library. Use it responsibly and respect ČSFD’s terms of service:
  • Implement appropriate rate limiting in production
  • Consider caching responses to minimize server load
  • Be aware of CORS restrictions when using in browsers
When using userRatings() or userReviews() with the allPages option, always set an appropriate allPagesDelay to avoid detection:
const allRatings = await csfd.userRatings('912', {
  allPages: true,
  allPagesDelay: 2000 // 2 second delay between requests
});

​
Next steps

Now that you’ve made your first API calls, explore more advanced features:

API Reference

Explore all available methods, types, and options

Examples

See real-world examples and integration patterns

MCP Server

Use ČSFD data with AI agents like Claude Desktop

Docker Support

Run as a standalone REST API service

Build docs developers (and LLMs) love

Get started for freeTalk to us