Welcome to the Screenpick API – your gateway to intelligent, AI-powered movie discovery. Our sophisticated recommendation engine leverages advanced machine learning algorithms to understand natural language queries and deliver personalized movie suggestions that match your exact preferences, mood, or specific criteria.

API Architecture

The Screenpick API follows RESTful principles and returns responses in JSON format. All endpoints support CORS for browser-based applications and require HTTPS for secure communication. Our API is built on a modern, scalable infrastructure ensuring fast response times and high availability.

Base URL

The Screenpick API uses API key authentication to ensure secure access to our services. All API requests require a valid API key that identifies your application and tracks usage against your plan limits.

Authentication Methods

To ensure fair usage and maintain optimal service performance for all users, the Screenpick API implements intelligent rate limiting. Our rate limits are designed to accommodate both casual developers and high-volume enterprise applications.

Rate Limit Tiers

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your daily request limit. Please upgrade your plan or try again tomorrow.",
  "limit": 15,
  "remaining": 0,
  "resetTime": "2024-01-01T00:00:00Z"
}

The Screenpick API uses conventional HTTP response codes to indicate the success or failure of requests. Our error responses include detailed information to help you quickly identify and resolve issues.

Error Response Format

When an error occurs, the API returns a structured JSON response with detailed error information to help you understand and resolve the issue quickly:

{
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid. Please check your parameters.",
    "details": "The 'q' parameter is required for movie recommendations.",
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_abc123def456"
  }
}

async function handleApiResponse(response) {
  if (!response.ok) {
    const errorData = await response.json();
    
    switch (response.status) {
      case 400:
        throw new Error(`Bad Request: ${errorData.error.message}`);
      case 401:
        throw new Error('Invalid API key. Please check your credentials.');
      case 429:
        const retryAfter = response.headers.get('Retry-After') || 60;
        throw new Error(`Rate limit exceeded. Retry after ${retryAfter} seconds.`);
      case 500:
        throw new Error('Server error. Please try again later.');
      default:
        throw new Error(`API Error: ${errorData.error.message}`);
    }
  }
  
  return await response.json();
}

While the Screenpick API is simple enough to use with any HTTP library, we've created SDKs and helper libraries to make integration even easier. These libraries handle authentication, error handling, and provide convenient methods for common use cases.

Quick Start Examples

import { ScreenpickClient } from 'screenpick-js';

// Initialize the client
const client = new ScreenpickClient({
  apiKey: 'your_api_key_here',
  timeout: 10000, // 10 seconds
});

// Get movie recommendations
async function getRecommendations() {
  try {
    const movies = await client.recommendations.search({
      query: 'romantic comedies from the 90s',
      limit: 10
    });
    
    console.log(`Found ${movies.length} recommendations:`);
    movies.forEach(movie => {
      console.log(`- ${movie.title} (${movie.release_date?.split('-')[0]})`);
    });
    
    return movies;
  } catch (error) {
    if (error.code === 'RATE_LIMIT_EXCEEDED') {
      console.log('Rate limit hit, waiting before retry...');
      await client.waitForRateLimit();
      return getRecommendations(); // Retry
    }
    throw error;
  }
}

// Get movie IDs
async function getMovieIDs(title) {
  const ids = await client.movies.getIDs(title);
  return ids;
}

// Check API health
const isHealthy = await client.health.check();