The userRatings() method retrieves a user’s movie and TV show ratings from their ČSFD profile. It supports pagination, filtering by content type, and bulk fetching.
Method Signature csfd . userRatings ( username : string | number , config ?: UserRatingsOptions , options ?: CSFDOptions ): Promise < CSFDUserRatings [] >
Parameters ČSFD username or user ID. Can be in format "912", "912-bart", or just the numeric ID 912
Configuration for filtering and pagination Fetch specific page number (default: 1). Each page contains approximately 50 ratings.
Fetch all pages of ratings. Use with caution - can trigger rate limiting. Default: false
Delay between page requests in milliseconds when allPages is true. Recommended: 2000 or higher. Default: 0
Include only specific content types (e.g., ['film', 'series']). Mutually exclusive with exclude.
Exclude specific content types (e.g., ['episode', 'season']). Mutually exclusive with includesOnly.
Optional request configuration Language variant. Defaults to 'cs'
Return Type Array of user rating objects Content type: 'film', 'series', 'episode', 'season', 'tv-film', etc.
Full URL to the content on ČSFD
colorRating
'bad' | 'average' | 'good' | 'unknown'
Overall ČSFD rating quality
Date when user rated the content (format: “DD.MM.YYYY”)
User’s rating (0-5 stars)
Usage Examples Basic Usage
Specific Page
All Pages (Rate Limited)
Filter by Type
Analyze Ratings
import { csfd } from 'node-csfd-api' ; // Get latest page of ratings (~50 items) const ratings = await csfd . userRatings ( '912-bart' ); ratings . forEach ( rating => { console . log ( ` ${ rating . title } ( ${ rating . year } ): ${ rating . userRating } /5` ); });
import { csfd } from 'node-csfd-api' ; // Get page 2 of ratings const page2 = await csfd . userRatings ( '912-bart' , { page: 2 }); console . log ( `Fetched ${ page2 . length } ratings from page 2` );
import { csfd } from 'node-csfd-api' ; // Fetch ALL ratings with 2-second delay between requests const allRatings = await csfd . userRatings ( '912-bart' , { allPages: true , allPagesDelay: 2000 // 2 seconds }); console . log ( `Total ratings: ${ allRatings . length } ` );
import { csfd } from 'node-csfd-api' ; // Get only movies (exclude TV content) const onlyMovies = await csfd . userRatings ( '912-bart' , { includesOnly: [ 'film' ] }); // Exclude episodes and seasons const noEpisodes = await csfd . userRatings ( '912-bart' , { exclude: [ 'episode' , 'season' ] });
import { csfd } from 'node-csfd-api' ; const ratings = await csfd . userRatings ( '912-bart' ); // Calculate average rating const avgRating = ratings . reduce ( ( sum , r ) => sum + r . userRating , 0 ) / ratings . length ; console . log ( `Average rating: ${ avgRating . toFixed ( 2 ) } /5` ); // Count 5-star ratings const fiveStars = ratings . filter ( r => r . userRating === 5 ). length ; console . log ( `5-star ratings: ${ fiveStars } ` );
[ { "id" : 812944 , "title" : "David Attenborough: Život na naší planetě" , "year" : 2020 , "type" : "film" , "url" : "https://www.csfd.cz/film/812944-david-attenborough-zivot-na-nasi-planete/" , "colorRating" : "good" , "userDate" : "01.11.2020" , "userRating" : 5 }, { "id" : 912552 , "title" : "Coronation" , "year" : 2020 , "type" : "film" , "url" : "https://www.csfd.cz/film/912552-coronation/" , "colorRating" : "good" , "userDate" : "28.10.2020" , "userRating" : 4 } ]
Content Type Filtering You can filter ratings by content type using includesOnly or exclude:
Available Content Types
'film' - Feature films'series' - TV series'season' - Individual seasons'episode' - Individual episodes'tv-film' - TV movies'tv-show' - TV shows'theatrical' - Theatrical productions'concert' - Concert recordings'student-film' - Student films'amateur-film' - Amateur films'music-video' - Music videos
includesOnly and exclude are mutually exclusive. If both are provided, includesOnly takes precedence.
Rate Limiting: When using allPages: true, always set an appropriate allPagesDelay (recommended: 2000ms or higher) to avoid being detected and blocked by ČSFD. Consider implementing exponential backoff for large datasets.
For exporting user ratings to CSV or JSON, use the built-in CLI tool: npx node-csfd-api export ratings 912-bart