TMDb Getting Started: API Key & First Request (2026)

Getting started overview

To begin using the TMDb API, the initial steps involve setting up an account, generating an API key, and then executing a basic API call to confirm authentication and connectivity. The TMDb API provides access to extensive datasets for movies, TV shows, and individuals, primarily through RESTful endpoints that return JSON responses. Understanding the process for obtaining credentials and making a first request is fundamental for any development or research utilizing this resource.

The API is designed to be accessible for developers, offering a clear path from registration to data retrieval. Adhering to the specified rate limits and terms of use, particularly concerning attribution for commercial applications, is required for ongoing access to the service. For those new to API interactions, the process involves standard HTTP requests, often managed through web browsers or programmatic clients like curl, which is a command-line tool for transferring data with URLs, supporting various protocols including HTTP and HTTPS curl documentation.

This guide outlines the necessary steps to get from no account to a successful API call. It covers account creation, API key generation, and constructing a representative request to demonstrate the API's functionality.

Quick Reference Steps

Create an account and get keys

Access to the TMDb API requires a user account. The registration process is standard, requiring an email address and password. Once registered, users must then apply for an API key, which serves as the primary method of authentication for all API requests TMDb Getting Started documentation.

Follow these steps to obtain your API key:

1. Register for a TMDb account: Navigate to the TMDb sign-up page and complete the registration form. You will need to verify your email address to activate your account.

2. Access API settings: After logging in, go to your TMDb API settings page. This section is where you manage your API access.

3. Request a new API key: On the API settings page, select the option to request a new API key. You will be prompted to choose the type of API key: Developer or Web Service. For most common uses, the Developer API key is appropriate.

   • Developer API Key: Suited for personal projects, learning, and non-commercial applications.
   • Web Service API Key: Intended for commercial applications or services that require higher rate limits or specific terms of use. Note that commercial usage may require additional approval and attribution TMDb API terms of use.

4. Provide application details: You will need to provide information about how you intend to use the API, including an application name, a brief description, and a website URL if applicable. This information helps TMDb understand the usage patterns and ensures compliance with their terms.

5. Accept terms of use: Read and accept the TMDb API terms of use TMDb API terms and conditions. These terms outline important aspects like attribution requirements, rate limits, and acceptable use policies.

6. Retrieve your API key: Once your application is submitted and approved (often instantaneous for Developer keys), your API key will be displayed on the TMDb API settings page. This key is a unique alphanumeric string that you will include in all your API requests.

It is important to keep your API key secure and avoid exposing it in client-side code or public repositories. Treat your API key like a password, as it grants access to the TMDb service under your account.

Your first request

After obtaining your API key, the next step is to make a test request to verify that your credentials are set up correctly and that you can retrieve data. A basic endpoint to start with is the 'movie/popular' endpoint, which returns a list of currently popular movies TMDb movie popular endpoint reference.

The base URL for all TMDb API requests is https://api.themoviedb.org/3/.

To construct your first request, you will append the endpoint and your API key as a query parameter.

Example Request URL Structure:

https://api.themoviedb.org/3/<ENDPOINT>?api_key=<YOUR_API_KEY>

Let's use the /movie/popular endpoint:

https://api.themoviedb.org/3/movie/popular?api_key=YOUR_API_KEY

Replace YOUR_API_KEY with the actual API key you obtained from your TMDb account settings.

Making the request using curl

curl is a widely used command-line tool for making HTTP requests. It's available on most Unix-like operating systems and can be installed on Windows. To make your first request using curl, open your terminal or command prompt and execute the following command, substituting YOUR_API_KEY with your key:

curl "https://api.themoviedb.org/3/movie/popular?api_key=YOUR_API_KEY"

Upon successful execution, curl will output a JSON response containing a list of popular movies, similar to this:

{
  "page": 1,
  "results": [
    {
      "adult": false,
      "backdrop_path": "/path/to/backdrop.jpg",
      "genre_ids": [28, 12, 878],
      "id": 507086,
      "original_language": "en",
      "original_title": "Movie Title One",
      "overview": "A brief description of the movie.",
      "popularity": 1234.567,
      "poster_path": "/path/to/poster.jpg",
      "release_date": "2023-01-01",
      "title": "Movie Title One",
      "video": false,
      "vote_average": 7.8,
      "vote_count": 1234
    }
    // ... more movie objects
  ],
  "total_pages": 500,
  "total_results": 10000
}

If you receive a JSON object with movie data, your first request was successful, and your API key is correctly configured. If you encounter an error, refer to the Troubleshooting the first call section.

Making the request in a web browser

You can also test your API key and make requests directly in your web browser. Simply paste the full request URL into your browser's address bar:

https://api.themoviedb.org/3/movie/popular?api_key=YOUR_API_KEY

The browser will display the JSON response. Many browsers offer built-in JSON formatters or extensions that make the output more readable.

Common next steps

With a successful first API call completed, developers typically proceed to explore more specific endpoints and integrate the API into their applications. Here are some common next steps:

• Explore the API Reference: The TMDb API Reference details all available endpoints, required parameters, and expected responses. This is the authoritative source for understanding the full capabilities of the API, covering categories like movies, TV shows, people, companies, and more. It outlines how to fetch detailed information, search for specific titles, and retrieve images.

• Understand Rate Limits: Be aware of the TMDb API rate limits, which define the number of requests you can make within a specific timeframe (e.g., 40 requests per 10 seconds, and 200,000 requests per day for the free tier). Implement a rate-limiting strategy in your application to avoid hitting these caps and getting temporary bans. Techniques include using delays between requests or implementing a token bucket algorithm, a common method for handling network traffic and API request rates Cloudflare API rate limiting best practices.

• Integrate into a Programming Language: Move beyond curl and integrate the API calls into your chosen programming language (e.g., Python, JavaScript, Java). Most languages have HTTP client libraries that simplify making requests and parsing JSON responses. For example, in Python, libraries like requests are commonly used to handle HTTP communication Python Requests library documentation.

• Handle API Responses: Learn to parse and process the JSON responses effectively. This involves extracting specific data fields, handling arrays of results, and managing pagination for endpoints that return large datasets.

• Error Handling: Implement robust error handling in your application to gracefully manage scenarios like invalid API keys, rate limit exceedances, or server-side issues. The TMDb API typically returns informative error messages in JSON format.

• Image Integration: TMDb provides image paths in its API responses. To display images (e.g., movie posters or backdrops), you need to combine these paths with a base image URL from the TMDb image configuration endpoint. This allows for dynamic image loading based on the fetched data.

• Authentication with Sessions (Advanced): For features requiring user-specific actions, such as rating movies or adding to watchlists, TMDb uses a session-based authentication system rather than just the API key. This involves creating a request token, authenticating it, and then generating a session ID TMDb session creation guide.

Troubleshooting the first call

If your first API request does not return the expected movie data, consider the following common issues:

• Invalid API Key: The most frequent issue is an incorrect or expired API key. Double-check that your API key in the URL exactly matches the one provided on your TMDb API settings page. Even a single character mismatch will result in an authentication failure.

  • Error Message Example: {"success":false,"status_code":7,"status_message":"Invalid API key: You do not have permissions to access the service."}

• Incorrect Endpoint or URL Structure: Verify that the base URL (https://api.themoviedb.org/3/) and the specific endpoint (e.g., movie/popular) are spelled correctly and concatenated properly. Ensure that the api_key parameter is correctly added after a question mark (?) and separated by an equals sign (=).

  • Error Message Example: {"success":false,"status_code":34,"status_message":"The resource you requested could not be found."} (often for wrong endpoint)

• Rate Limit Exceeded: If you make too many requests in a short period, TMDb may temporarily block your IP address or key. For beginners, this is less common on the first call but can occur if automated scripts are run without care. The free tier limits are 40 requests per 10 seconds and 200,000 requests per day TMDb API rate limit information.

  • Error Message Example: {"success":false,"status_code":25,"status_message":"Your request count (#) is larger than the maximum allowed #."}

• Network Connectivity Issues: Ensure your device has a stable internet connection and that no firewalls or proxies are blocking outgoing HTTPS requests to api.themoviedb.org. You can test general connectivity by trying to access other websites.

• HTTP Method: The TMDb API primarily uses GET requests for data retrieval. Ensure your client is sending a GET request, not a POST, PUT, or DELETE request.

• Awaiting API Key Approval: While developer keys are often instant, there might be a brief delay for approval, especially for web service keys. Check your API settings page to confirm the status of your key.

• Browser-Specific Issues: If testing in a browser, ensure no extensions are interfering with the request or response display. Try using a different browser or an incognito/private window.

When troubleshooting, it's helpful to copy the exact URL being used and paste it into a simple tool like curl or a browser to isolate whether the issue is with your code or the API call itself. Review the TMDb official documentation for detailed error codes and messages.