Skip to main content
The REST server command starts a standalone Express.js server that exposes ČSFD data through HTTP endpoints.

​
Quick Start

1

Start the Server

npx node-csfd-api server
You should see:
                  _                  __    _               _
                 | |                / _|  | |             (_)
  _ __   ___   __| | ___    ___ ___| |_ __| |   __ _ _ __  _
 | '_ \ / _ \ / _` |/ _ \  / __/ __|  _/ _` |  / _` | '_ \| |
 | | | | (_) | (_| |  __/ | (__\__ \ || (_| | | (_| | |_) | |
 |_| |_|\___/ \__,_|\___|  \___|___/_| \__,_|  \__,_| .__/|_|
                                                    | |
                                                    |_|

[email protected]

API is running on: http://localhost:3000
2

Test the API

Open your browser or use curl:
curl http://localhost:3000/

​
Available Endpoints

​
Root Endpoint

curl http://localhost:3000/

​
Movie Details

Get comprehensive information about a movie or TV series. 
curl http://localhost:3000/movie/535121
Path: /movie/:id
​
id
number
required
ČSFD movie/series ID
​
language
string
Response language (cs, en, sk). Defaults to server configuration.
Search for movies, TV series, and users. 
curl http://localhost:3000/search/tarantino
Path: /search/:query
​
query
string
required
Search query (URL-encoded)
​
language
string
Response language (cs, en, sk)

​
Creator Details

Get information about actors, directors, and other creators. 
curl http://localhost:3000/creator/2120
Path: /creator/:id
​
id
number
required
ČSFD creator ID

​
User Ratings

Retrieve user ratings with optional pagination and filtering. 
curl http://localhost:3000/user-ratings/912-bart
Path: /user-ratings/:id
​
id
string
required
ČSFD user ID or username
​
page
number
Page number (default: 1)
​
allPages
boolean
Fetch all pages (true or false)
​
allPagesDelay
number
Delay in ms between page requests (default: 0)
​
includesOnly
string
Comma-separated content types to include (e.g., film,series)
​
excludes
string
Comma-separated content types to exclude (e.g., episode)

​
User Reviews

Retrieve detailed user reviews. 
curl http://localhost:3000/user-reviews/195357
Path: /user-reviews/:id
Accepts the same query parameters as /user-ratings/:id

​
Cinemas

Get cinema screenings (currently hardcoded to district 1, today). 
curl http://localhost:3000/cinemas
Path: /cinemas

​
Configuration

​
Port Configuration

Change the server port using the PORT environment variable: 
PORT=8080 npx node-csfd-api server

​
Language Configuration

Set a default language for all responses: 
LANGUAGE=en npx node-csfd-api server
Supported languages:
  • cs - Czech (default)
  • en - English
  • sk - Slovak
Clients can override the default language using the ?language= query parameter on any endpoint.

​
API Key Protection

Protect your server with API keys: 
API_KEY=your-secret-key npx node-csfd-api server
Clients must include the key in the request header: 
curl -H "x-api-key: your-secret-key" http://localhost:3000/movie/535121
Multiple API Keys: 
API_KEY="key1,key2,key3" npx node-csfd-api server
Custom Header Name: 
API_KEY_NAME=Authorization API_KEY=secret npx node-csfd-api server
Without API key protection, your server is open to the world. Anyone can access it without restrictions.

​
Verbose Logging

Enable detailed request logging: 
VERBOSE=true npx node-csfd-api server
This logs every successful request with timing and IP information.

​
Docker Deployment

​
Using Pre-built Image

1

Pull the Image

docker pull bartholomej/node-csfd-api
2

Run the Container

docker run -p 3000:3000 bartholomej/node-csfd-api
3

Access the API

curl http://localhost:3000/

​
With Environment Variables

docker run -p 8080:8080 \
  -e PORT=8080 \
  -e API_KEY=your-secret \
  -e LANGUAGE=en \
  bartholomej/node-csfd-api

​
Docker Compose

docker-compose.yml
version: '3.8'
services:
  csfd-api:
    image: bartholomej/node-csfd-api
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - API_KEY=your-secret-key
      - LANGUAGE=en
      - VERBOSE=true
    restart: unless-stopped
Run with: 
docker-compose up -d

​
Error Handling

The server returns structured error responses: 
{
  "error": "ID_MISSING",
  "message": "ID is missing. Provide ID like this: /movie/1234"
}

​
HTTP Status Codes

CodeDescription
200Success
401Missing or invalid API key
404Endpoint or resource not found
500Server error (failed to fetch from ČSFD)

​
Complete Example: Production Setup

1

Create .env File

.env
PORT=3000
API_KEY=super-secret-key-change-me
API_KEY_NAME=x-api-key
LANGUAGE=en
VERBOSE=true
2

Start with Docker Compose

docker-compose.yml
version: '3.8'
services:
  csfd-api:
    image: bartholomej/node-csfd-api
    ports:
      - "3000:3000"
    env_file:
      - .env
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/"]
      interval: 30s
      timeout: 10s
      retries: 3
3

Deploy

docker-compose up -d
4

Test

curl -H "x-api-key: super-secret-key-change-me" \
  http://localhost:3000/search/tarantino

​
Next Steps

REST API Endpoints

Explore all available endpoints and responses

Docker Hub

View the official Docker image

Build docs developers (and LLMs) love

Get started for freeTalk to us