Overview
Connect World uses The Movie Database (TMDB) API to fetch trending movies and TV shows, display content catalogs, and provide rich metadata for the streaming platform. TMDB provides comprehensive movie and TV show data including posters, ratings, and descriptions.Prerequisites
- TMDB account (sign up here)
- TMDB API key (v3)
Environment Configuration
Create TMDB API Key
- Log in to TMDB
- Go to Settings → API
- Request an API key (choose “Developer” option)
- Fill out the application form
- Copy your API Key (v3 auth)
Add environment variable
Add this variable to your
.env.local file:.env.local
The
NEXT_PUBLIC_ prefix makes this variable accessible on the client-side, which is safe for TMDB API keys as they’re designed for public use.Service Implementation
The TMDB service provides a centralized interface for all TMDB API interactions. File:src/infrastructure/external/tmdbService.ts
API Functions
getTrendingAll
Fetches trending movies and TV shows for a specified time window.timeWindow:"day"or"week"(default:"week")
TmdbMovie objects
getNowPlayingMovies
Retrieves movies currently playing in theaters.TmdbMovie objects
getTopRatedSeries
Fetches the highest-rated TV series.TmdbMovie objects
getPosterUrl
Generates the full URL for movie/TV posters and backdrops.path: The poster path from TMDB (e.g.,/abc123.jpg)size: Image size (default:"w500")
- Posters:
"w92","w154","w185","w342","w500","w780","original" - Backdrops:
"w300","w780","w1280","original"
Usage Examples
Server Component (Next.js)
Fetch trending content on the server for optimal performance. File:src/app/page.tsx
page.tsx
The
revalidate export enables Next.js ISR (Incremental Static Regeneration), caching the TMDB data for 1 hour to reduce API calls.Display Content Catalog
Render movies and TV shows with posters and metadata.CatalogSection.tsx
Handle Missing API Key
Gracefully handle missing TMDB configuration.TypeScript Types
TmdbMovie Interface
TmdbResponse Interface
API Rate Limits
TMDB enforces rate limits on API requests:- 40 requests per 10 seconds per IP address
- Exceeding the limit returns
429 Too Many Requests
Best Practices
Cache Responses
Use Next.js ISR or a caching layer to minimize API calls and improve performance.
Handle Errors Gracefully
Always catch TMDB errors and provide fallback content for better UX.
Optimize Images
Use appropriate image sizes. Don’t load
original when w500 suffices.Localize Content
Set the
language parameter in the axios client to localize results.Language Configuration
Change the language for TMDB responses:en-US, es-ES, fr-FR, de-DE, etc.
Advanced Features
Search Movies
Add a search function to your TMDB service:Get Movie Details
Fetch detailed information about a specific movie:Get Genre List
Retrieve the list of official genres:Additional Resources
Troubleshooting
Common Issues
“Invalid API key”- Verify your API key is correct in
.env.local - Ensure the environment variable name matches:
NEXT_PUBLIC_TMDB_API_KEY - Restart your development server after adding the key
- Check the API endpoint URL is correct
- Verify the movie/show ID exists in TMDB
- Ensure language parameter is valid
- Implement caching to reduce API calls
- Use Next.js
revalidateto cache responses - Wait before retrying (10 seconds for rate limit reset)
- Some content may not have posters available
- Always check if
poster_pathisnullbefore usinggetPosterUrl() - Provide fallback placeholder images
Debugging Tips:
- Log the full error response for detailed TMDB error messages
- Use the TMDB API explorer to test endpoints: https://developers.themoviedb.org/3
- Check your API usage in the TMDB dashboard
