Skip to main content

​
Overview

Popcorn Vision uses The Movie Database (TMDB) API to fetch movie and TV show information. You’ll need to create a free TMDB account and generate API credentials before running the application.
TMDB API is completely free for non-commercial use. Commercial usage requires approval from TMDB.

​
Prerequisites

  • A valid email address
  • Agreement to TMDB’s Terms of Service and API Terms of Use
  • A brief description of how you’ll use the API (e.g., “Personal movie tracking application”)

​
Getting Your API Credentials

1

Create a TMDB Account

Navigate to The Movie Database and click Sign Up in the top right corner.Fill in your details:
  • Username
  • Password
  • Email address
Verify your email address by clicking the confirmation link sent to your inbox.
2

Navigate to API Settings

Once logged in:
  1. Click your profile icon in the top right
  2. Select Settings from the dropdown
  3. Click API in the left sidebar
Or navigate directly to: TMDB API Settings
3

Request an API Key

On the API page, you’ll see a section to request an API key.
  1. Click click here link under “Request an API Key”
  2. Choose Developer (for non-commercial use)
  3. Accept the Terms of Use
4

Fill Out the Application Form

Provide the required information:Application Name: Popcorn Vision (or your custom name)Application URL: Your deployment URL or http://localhost:3000 for developmentApplication Summary: A brief description, such as:
Personal movie and TV show tracking application. Allows users to 
discover content, create watchlists, and rate movies/shows.
Click Submit when complete.
5

Copy Your API Credentials

You’ll immediately see your API credentials. Copy both:
​
API Key (v3 auth)
string
Your main API key - a 32-character hexadecimal string.Example format: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6Copy this value to API_KEY in your .env.local file.
​
API Read Access Token (v4 auth)
string
A longer JWT token used for some v4 API endpoints.Example format: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... (much longer)Copy this value to API_READ in your .env.local file.
Keep these credentials private! Never share them publicly or commit them to version control.

​
Configuring Popcorn Vision

After obtaining your credentials, add them to your environment configuration: 
# TMDB API Configuration
API_URL="https://api.themoviedb.org/3"
API_KEY="your_api_key_here"
API_READ="your_read_access_token_here"

​
Understanding API Versions

TMDB offers two API versions, and Popcorn Vision uses both:

API v3 (API Key)

The traditional REST API using an API key for authentication.Used for:
  • Fetching movie/TV data
  • Search functionality
  • Discover endpoints
  • Most read operations
Authentication: Query parameter api_key=YOUR_KEY

API v4 (Bearer Token)

Newer API version using OAuth-style bearer token authentication.Used for:
  • User account operations
  • Lists management
  • Ratings and favorites
  • Write operations
Authentication: Header Authorization: Bearer YOUR_TOKEN
Popcorn Vision primarily uses v3 API endpoints. The v4 Read Access Token is included for future compatibility and advanced features.

​
API Usage in Popcorn Vision

Here’s how your API credentials are used throughout the application:

​
Server-Side API Client

The main API client is configured in src/lib/axios.js: 
import Axios from "axios";

export const axios = Axios.create({
  baseURL: process.env.API_URL,
  params: { api_key: process.env.API_KEY },
  adapter: "fetch",
  fetchOptions: {
    next: { revalidate: 3600 }, // Cache for 1 hour
  },
});
This client automatically:
  • Adds your API key to all requests
  • Caches responses for 1 hour to reduce API calls
  • Uses Next.js fetch adapter for optimal performance

​
API Routes

Popcorn Vision uses Next.js API routes to proxy TMDB requests:
  • /api/search/query - Search for movies/TV shows
  • /api/search/filter - Filter and discover content
  • /api/authentication/* - User authentication flows
  • /api/account/* - User account management
  • /api/[[...segments]] - Catch-all proxy for other TMDB endpoints
API keys are kept secure on the server. They’re never exposed to client-side JavaScript.

​
Rate Limits

TMDB enforces rate limits to ensure fair usage:
​
Rate Limit
number
40 requests per 10 seconds per IP addressIf you exceed this limit, you’ll receive a 429 Too Many Requests response.

​
Avoiding Rate Limits

Popcorn Vision includes several strategies to stay within limits:
  1. Response Caching: API responses are cached for 1 hour using Next.js cache
  2. Request Batching: Multiple data points are fetched in single requests using append_to_response
  3. Rate Limiting Middleware: Built-in rate limiting using the limiter package
For high-traffic deployments, consider implementing Redis caching to further reduce API calls.

​
Testing Your API Connection

Verify your TMDB API credentials are working correctly:
1

Start the Development Server

npm run dev
# or
pnpm dev
2

Check the Application

Open http://localhost:3000 in your browser.If configured correctly, you should see:
  • Movie posters and backdrops loading
  • Trending movies on the homepage
  • Search functionality working
3

Test an API Endpoint Directly

You can test your API key directly using curl:
curl "https://api.themoviedb.org/3/movie/popular?api_key=YOUR_API_KEY_HERE"
A successful response will return JSON with popular movies:
{
  "page": 1,
  "results": [
    {
      "id": 123456,
      "title": "Example Movie",
      "overview": "Movie description...",
      // ... more fields
    }
  ]
}
4

Check the Browser Console

Open your browser’s Developer Tools (F12) and check the Console and Network tabs for any errors.Common error messages:
  • 401 Unauthorized - Invalid API key
  • 429 Too Many Requests - Rate limit exceeded
  • 404 Not Found - Incorrect API URL

​
Troubleshooting

Problem: API requests return 401 status code.Causes:
  • Incorrect API key
  • API key not activated yet
  • Extra spaces or quotes in .env.local
Solutions:
  1. Copy your API key fresh from TMDB Settings
  2. Remove any quotes or spaces around the key in .env.local
  3. Wait a few minutes if you just created your account
  4. Restart your dev server after updating .env.local
Problem: Too Many Requests error from TMDB.Cause: You’ve exceeded 40 requests per 10 seconds.Solutions:
  1. Implement caching for API responses
  2. Reduce the number of API calls on page load
  3. Wait 10 seconds and try again
  4. Check for infinite loops in your code making repeated API calls
Problem: Movie posters and backdrops are broken.Cause: Image CDN URLs not configured.Solution: Ensure all NEXT_PUBLIC_API_IMAGE_* variables are set in .env.local. Copy them from .env.example:
NEXT_PUBLIC_API_IMAGE_500="https://image.tmdb.org/t/p/w500"
NEXT_PUBLIC_API_IMAGE_1280="https://image.tmdb.org/t/p/w1280"
# ... etc
Problem: Your API key stops working.Causes:
  • Violation of TMDB Terms of Service
  • Commercial use without approval
  • Excessive API usage
Solution:
  1. Check your email for notices from TMDB
  2. Review TMDB API Terms
  3. Contact TMDB support if you believe it’s an error
  4. Request a new API key if necessary
Problem: CORS errors in browser console.Cause: Direct API calls from client-side code.Solution: Always use Popcorn Vision’s API routes (e.g., /api/search/query) instead of calling TMDB directly from the browser. The Next.js API routes act as a secure proxy.

​
API Documentation

For advanced usage and custom integrations, refer to the official TMDB API documentation:

TMDB API v3 Docs

Complete API v3 reference with all endpoints and parameters

TMDB API v4 Docs

API v4 documentation for advanced authentication and features

API Support

TMDB community forums for API support and questions

Rate Limits Guide

Detailed information about TMDB rate limiting policies

​
Next Steps

Environment Variables

Configure all environment variables for Popcorn Vision

Deployment

Deploy your configured instance to production

Build docs developers (and LLMs) love

Get started for freeTalk to us