REST API Endpoints

Available Endpoints

The CSFD REST API exposes the following endpoints:

Method	Endpoint	Description
`GET`	`/`	API information and available endpoints
`GET`	`/movie/:id`	Get detailed movie information
`GET`	`/search/:query`	Search for movies, TV series, and users
`GET`	`/creator/:id`	Get creator details and filmography
`GET`	`/user-ratings/:id`	Get user ratings with pagination
`GET`	`/user-reviews/:id`	Get user reviews with pagination
`GET`	`/cinemas`	Get cinema listings for today

Root Endpoint

GET

Returns basic API information and available endpoints.

Response

name

string

Package name: node-csfd-api

version

string

Current API version

docs

string

Documentation URL

links

string[]

Array of available endpoint paths

Example

curl http://localhost:3000/

{
  "name": "node-csfd-api",
  "version": "1.0.0",
  "docs": "https://github.com/bartholomej/node-csfd-api",
  "links": [
    "/movie/:id",
    "/creator/:id",
    "/search/:query",
    "/user-ratings/:id",
    "/user-reviews/:id",
    "/cinemas"
  ]
}

Get Movie Details

/movie/:id

GET

Retrieve comprehensive information about a movie or TV series.

Path Parameters

number

required

The CSFD movie ID (e.g., 535121)

Query Parameters

language

string

Language code for content. Supported values: cs, en, sk

Response

number

CSFD movie ID

title

string

Movie title

year

string

Release year

rating

number

CSFD rating percentage (0-100)

ratingCount

number

Number of ratings

colorRating

string

Rating category: good, average, or bad

type

string

Content type: film, series, tv-film, etc.

genres

string[]

Array of genre names

origins

string[]

Array of country names

descriptions

string[]

Array of plot descriptions

creators

object

Object containing directors, actors, writers, music, producers arrays

poster

string

URL to movie poster image

url

string

CSFD URL for the movie

Example

curl http://localhost:3000/movie/535121

curl "http://localhost:3000/movie/535121?language=en"

{
  "id": 535121,
  "title": "Na špatné straně",
  "year": "2018",
  "rating": 73,
  "ratingCount": 6654,
  "colorRating": "good",
  "type": "film",
  "genres": ["Krimi", "Drama", "Thriller"],
  "origins": ["USA", "Kanada"],
  "descriptions": ["Otupělý policejní veterán Ridgeman..."],
  "creators": {
    "directors": [
      {
        "id": 87470,
        "name": "S. Craig Zahler",
        "url": "https://www.csfd.cz/tvurce/87470-s-craig-zahler/"
      }
    ],
    "actors": [...],
    "writers": [...]
  },
  "poster": "https://image.pmgstatic.com/cache/resized/w1080/files/images/film/posters/163/579/163579352_bf8737.jpg",
  "url": "https://www.csfd.cz/film/535121"
}

Movie IDs can be found in CSFD URLs: https://www.csfd.cz/film/535121 → ID is 535121

Search

/search/:query

GET

Search for movies, TV series, and users across the CSFD database.

Path Parameters

query

string

required

Search query (URL-encoded)

Query Parameters

language

string

Language code for content. Supported values: cs, en, sk

Response

movies

array

Array of movie results matching the query

tvSeries

array

Array of TV series results matching the query

users

array

Array of user profiles matching the query

Example

curl http://localhost:3000/search/tarantino

curl "http://localhost:3000/search/matrix?language=en"

{
  "movies": [
    {
      "id": 8852,
      "title": "Pulp Fiction: Historky z podsvětí",
      "year": "1994",
      "type": "film",
      "colorRating": "good",
      "url": "https://www.csfd.cz/film/8852",
      "origins": ["USA"],
      "creators": {...}
    }
  ],
  "tvSeries": [...],
  "users": [...]
}

Get Creator Details

/creator/:id

GET

Get detailed information about a creator including biography and filmography.

Path Parameters

number

required

The CSFD creator ID (e.g., 2120 for Quentin Tarantino)

Query Parameters

language

string

Language code for content. Supported values: cs, en, sk

Response

number

CSFD creator ID

name

string

Creator’s full name

birthday

string

Birth date in DD.MM.YYYY format

birthplace

string

Place of birth

age

number

Current age

photo

string

URL to creator’s photo

bio

string

Biography text

films

array

Array of films with id, title, year, and colorRating

Example

curl http://localhost:3000/creator/2120

{
  "id": 2120,
  "name": "Quentin Tarantino",
  "birthday": "27.03.1963",
  "birthplace": "Knoxville, Tennessee, USA",
  "age": 58,
  "photo": "https://image.pmgstatic.com/cache/resized/w100h132crop/files/images/creator/photos/164/515/164515525_b98f8a.jpg",
  "bio": "Quentin Tarantino se narodil 27. března roku 1963...",
  "films": [
    {
      "id": 527699,
      "title": "Tenkrát v Hollywoodu",
      "year": 2019,
      "colorRating": "good"
    }
  ]
}

Get User Ratings

/user-ratings/:id

GET

Retrieve user ratings from their CSFD profile with pagination and filtering.

Path Parameters

string

required

Username or user ID (e.g., 912 or 912-bart)

Query Parameters

language

string

Language code. Supported values: cs, en, sk

page

number

Page number for pagination (default: 1)

allPages

boolean

Fetch all pages of ratings. Use with caution. (default: false)

allPagesDelay

number

Delay in milliseconds between page requests when allPages=true

includesOnly

string

Comma-separated list of content types to include: film, series, episode, season

excludes

string

Comma-separated list of content types to exclude

Response

Array of rating objects:

title

string

Content title

year

number

Release year

type

string

Content type

url

string

CSFD URL

colorRating

string

CSFD rating category

userDate

string

Date when user rated (DD.MM.YYYY)

userRating

number

User’s rating (1-5 stars)

Examples

# Get first page of ratings
curl http://localhost:3000/user-ratings/912-bart

# Get specific page
curl http://localhost:3000/user-ratings/912-bart?page=2

# Get only movies
curl "http://localhost:3000/user-ratings/912-bart?includesOnly=film"

# Exclude episodes and seasons
curl "http://localhost:3000/user-ratings/912-bart?excludes=episode,season"

# Get all pages with 2-second delay between requests
curl "http://localhost:3000/user-ratings/912-bart?allPages=true&allPagesDelay=2000"

[
  {
    "title": "David Attenborough: Život na naší planetě",
    "year": 2020,
    "type": "film",
    "url": "https://www.csfd.cz/film/812944",
    "colorRating": "good",
    "userDate": "01.11.2020",
    "userRating": 5
  }
]

When using allPages=true, always set an appropriate allPagesDelay (2000ms or more) to avoid overwhelming the CSFD servers and potential rate limiting.

Get User Reviews

/user-reviews/:id

GET

Retrieve detailed user reviews from their CSFD profile.

Path Parameters

string

required

User ID (e.g., 195357 or 195357-verbal)

Query Parameters

Same as User Ratings endpoint.

Response

Array of review objects (includes all rating fields plus):

number

Review ID

text

string

Review text content

poster

string

URL to movie poster

Example

curl http://localhost:3000/user-reviews/195357

curl "http://localhost:3000/user-reviews/195357?page=2&includesOnly=film"

[
  {
    "id": 1391448,
    "title": "Co s Péťou?",
    "year": 2025,
    "type": "film",
    "url": "https://www.csfd.cz/film/1391448",
    "colorRating": "good",
    "userDate": "27.11.2025",
    "userRating": 4,
    "text": "Co s Péťou? Inu, co by? Každý normální Sparťan...",
    "poster": "https://image.pmgstatic.com/cache/resized/w240h339/files/images/film/posters/170/492/170492173_1l3djd.jpg"
  }
]

Get Cinema Listings

/cinemas

GET

Get cinema listings for today.

Query Parameters

language

string

Language code. Supported values: cs, en, sk

Response

Returns cinema showtimes and listings for the current day.

Example

curl http://localhost:3000/cinemas

curl "http://localhost:3000/cinemas?language=cs"

Error Responses

All endpoints return consistent error objects:

{
  "error": "ERROR_CODE",
  "message": "Human-readable error message"
}

Common Error Codes

Code	Status	Description
`ID_MISSING`	`404`	ID parameter is missing from the request
`MOVIE_FETCH_FAILED`	`500`	Failed to fetch movie data
`CREATOR_FETCH_FAILED`	`500`	Failed to fetch creator data
`SEARCH_FETCH_FAILED`	`500`	Failed to fetch search results
`USER_RATINGS_FETCH_FAILED`	`500`	Failed to fetch user ratings
`USER_REVIEWS_FETCH_FAILED`	`500`	Failed to fetch user reviews
`CINEMAS_FETCH_FAILED`	`500`	Failed to fetch cinema data
`PAGE_NOT_FOUND`	`404`	Endpoint does not exist
`API_KEY_MISSING`	`401`	API key required but not provided
`API_KEY_INVALID`	`401`	Invalid API key

Error Example

curl http://localhost:3000/movie/

{
  "error": "ID_MISSING",
  "message": "ID is missing. Provide ID like this: /movie/1234"
}

Use the root endpoint / to discover all available endpoints and their current paths.

Core API

TypeScript Types

REST API

MCP Server

​Available Endpoints

​Root Endpoint

​Response

​Example

​Get Movie Details

​Path Parameters

​Query Parameters

​Response

​Example

​Search

​Path Parameters

​Query Parameters

​Response

​Example

​Get Creator Details

​Path Parameters

​Query Parameters

​Response

​Example

​Get User Ratings

​Path Parameters

​Query Parameters

​Response

​Examples

​Get User Reviews

​Path Parameters

​Query Parameters

​Response

​Example

​Get Cinema Listings

​Query Parameters

​Response

​Example

​Error Responses

​Common Error Codes

​Error Example

Build docs developers (and LLMs) love

Available Endpoints

Root Endpoint

Response

Example

Get Movie Details

Path Parameters

Query Parameters

Response

Example

Search

Path Parameters

Query Parameters

Response

Example

Get Creator Details

Path Parameters

Query Parameters

Response

Example

Get User Ratings

Path Parameters

Query Parameters

Response

Examples

Get User Reviews

Path Parameters

Query Parameters

Response

Example

Get Cinema Listings

Query Parameters

Response

Example

Error Responses

Common Error Codes

Error Example