SDKs overview

Watchmode provides an API that offers access to a comprehensive database of movies and TV shows, including their streaming availability across various platforms. To facilitate developer interaction with this API, Watchmode offers official SDKs in multiple programming languages. These SDKs are designed to streamline the process of making requests, handling responses, and managing authentication, reducing the need for developers to write boilerplate code for HTTP communication. The SDKs typically encapsulate API endpoints as language-specific methods, allowing developers to integrate Watchmode's data into their applications more efficiently. While official SDKs are the primary recommendation for stable and supported integrations, the developer community also contributes libraries that extend functionality or support additional languages.

The Watchmode API itself is a RESTful interface, typically communicating over HTTPS with JSON payloads for both requests and responses. Understanding REST API principles can be beneficial when working with the API, even when using an SDK, as it clarifies the underlying communication patterns. For detailed information on the API's endpoints and data models, developers can refer to the Watchmode API documentation.

Official SDKs by language

Watchmode maintains official SDKs for several popular programming languages, ensuring direct support and compatibility with the latest API features. These SDKs are developed and maintained by Watchmode, offering a reliable and recommended method for integration. Each SDK typically includes modules for authentication, making requests to various API endpoints (e.g., searching for titles, getting details, checking streaming sources), and parsing responses into native language objects.

The following table outlines the official SDKs available:

Language Package Name Installation Command Maturity
Python watchmode-python pip install watchmode-python Stable
Node.js watchmode-node npm install watchmode-node Stable
PHP watchmode-php composer require watchmode/watchmode-php Stable

These official SDKs are designed to abstract the HTTP request and response handling, allowing developers to focus on application logic rather than API communication specifics. For further details on each SDK's specific methods and capabilities, consult the Watchmode developer documentation.

Installation

Installing Watchmode's official SDKs involves using the respective package manager for each programming language. The process is generally straightforward and follows standard practices for library inclusion. Before installation, developers should ensure they have the correct runtime environment and package manager configured on their system.

Python SDK Installation

The Python SDK for Watchmode can be installed using pip, the standard package installer for Python. It requires a Python 3.x environment.

pip install watchmode-python

After installation, the library can be imported into Python scripts to interact with the API.

Node.js SDK Installation

For Node.js projects, the Watchmode SDK is available via npm, the Node.js package manager. This requires a Node.js runtime environment.

npm install watchmode-node

Once installed, the module can be required or imported into JavaScript/TypeScript files.

PHP SDK Installation

The PHP SDK for Watchmode is managed through Composer, the dependency manager for PHP. This requires Composer to be installed and available in the project environment.

composer require watchmode/watchmode-php

After running this command, Composer will add the SDK to your project's vendor/ directory and update the composer.json and composer.lock files.

For any specific dependency requirements or troubleshooting during installation, refer to the Watchmode API documentation for SDKs.

Quickstart example

This section provides a quickstart example demonstrating how to use the Watchmode Python SDK to fetch streaming availability for a specific title. This example assumes you have already installed the watchmode-python package and have obtained an API key from your Watchmode account.

Python Quickstart: Fetching Title Details

The following Python code snippet illustrates how to initialize the Watchmode client with your API key and retrieve detailed information, including streaming sources, for a movie or TV show. Replace YOUR_API_KEY with your actual Watchmode API key.

import watchmode

# Replace with your actual Watchmode API Key
API_KEY = "YOUR_API_KEY"

# Initialize the Watchmode client
client = watchmode.WatchmodeClient(api_key=API_KEY)

# Example: Get details for a specific title (e.g., 'The Office' TV show)
# You would typically find the Watchmode ID through a search endpoint first
title_id = 345573 # Example Watchmode ID for 'The Office' (US)

try:
    title_details = client.titles.get_details(title_id=title_id)

    print(f"Title: {title_details.title}")
    print(f"Type: {title_details.type}")
    print(f"Year: {title_details.year}")
    print(f"IMDB ID: {title_details.imdb_id}")

    if title_details.sources:
        print("\nStreaming Sources:")
        for source in title_details.sources:
            print(f" - {source.name} ({source.type}): {source.web_url}")
    else:
        print("\nNo streaming sources found for this title.")

except watchmode.exceptions.WatchmodeAPIError as e:
    print(f"An API error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

This example demonstrates basic client initialization and a call to the get_details method. The title_id used here is an example; in a real application, you would first use a search endpoint (e.g., client.search.search_titles(search_field='name', search_value='The Office')) to find the correct ID.

Community libraries

Beyond the official SDKs, the Watchmode API has inspired various community-contributed libraries and wrappers. These libraries are developed and maintained independently by developers who find the API useful for their projects. Community libraries often provide support for additional programming languages, offer alternative approaches to API interaction, or include specialized features not present in the official SDKs.

While community libraries can offer flexibility and innovation, developers should exercise caution. Unlike official SDKs, community-maintained projects may not always keep pace with API updates, may have varying levels of documentation, or might not adhere to the same security and stability standards. It is recommended to review the project's activity, documentation, and community support before integrating a third-party library into a production application.

Developers interested in exploring community contributions can often find them on platforms like GitHub by searching for "Watchmode API" or "Watchmode client" in their preferred programming language. The Watchmode developer community may also occasionally highlight notable third-party tools.

When evaluating a community library, consider:

  • Active Maintenance: Check the last commit date and frequency of updates.
  • Documentation: Ensure there is clear documentation and examples.
  • Issue Tracking: Review open and closed issues to gauge responsiveness and common problems.
  • License: Understand the licensing terms (e.g., MIT, Apache 2.0).
  • Community Support: Look for forums, chat groups, or other channels for support.

For developers who require specific functionalities or languages not covered by official SDKs, community libraries can be a valuable resource, provided they are thoroughly vetted.