4K Media API

Access high-quality 4K movies and TV shows through our comprehensive API endpoint.

The 4K Media API provides access to a curated collection of high-quality 4K movies and TV shows. This endpoint allows you to search, filter, and paginate through our extensive library of 2160p content.

Base Endpoint

GET /api/4k_media

Query Parameters

Pagination Parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number for pagination
`perPage`	number	`20`	Number of items per page (max 100)

Filtering Parameters

Parameter	Type	Default	Description
`search`	string	`""`	Search term to filter by title or year (case-insensitive)
`mediaType`	string	`undefined`	Filter by media type: `"movie"` or `"tv"`
`year`	string	`""`	Filter by release year (e.g., "2023", "2024")

Response Format

{
  "items": [
    {
      "id": "123",
      "title": "Movie Title",
      "release_date": "2023-01-01",
      "error_message": null,
      "created_at": "2023-12-01T10:00:00Z",
      "updated_at": "2023-12-01T10:00:00Z",
      "status": "active",
      "is_tv": false,
      "season_number": null,
      "episode_number": null,
      "highest_quality": "2160p",
      "poster": "https://example.com/poster.jpg",
      "rating": "8.5",
      "media_type": "movie"
    }
  ],
  "total": 150,
  "page": 1,
  "perPage": 20,
  "totalPages": 8,
  "hasNextPage": true,
  "hasPrevPage": false
}

Response Fields

Media Item Fields

Field	Type	Description
`id`	string \| number	TMDB ID of the media
`title`	string	Title of the movie or TV show
`release_date`	string	Release date in YYYY-MM-DD format
`error_message`	string \| null	Error message if any issues occurred
`created_at`	string	ISO timestamp when the record was created
`updated_at`	string	ISO timestamp when the record was last updated
`status`	string	Current status of the media
`is_tv`	boolean	Whether the media is a TV show
`season_number`	number \| null	Season number (TV shows only)
`episode_number`	number \| null	Episode number (TV shows only)
`highest_quality`	string	Video quality (always "2160p" for 4K content)
`poster`	string	URL to the poster image
`rating`	string \| null	Rating information
`media_type`	string	Either "movie" or "tv"

Pagination Fields

Field	Type	Description
`total`	number	Total number of items available
`page`	number	Current page number
`perPage`	number	Number of items per page
`totalPages`	number	Total number of pages
`hasNextPage`	boolean	Whether there's a next page
`hasPrevPage`	boolean	Whether there's a previous page

Examples

Basic Usage

# Get first page of 4K content
curl "https://mappletv.uk/api/4k_media"

# Get second page with 10 items per page
curl "https://mappletv.uk/api/4k_media?page=2&perPage=10"


### Search Examples

```bash
# Search for movies with "zombie" in the title
curl "https://mappletv.uk/api/4k_media?search=zombie"

# Search for TV shows with "walking" in the title
curl "https://mappletv.uk/api/4k_media?search=walking&mediaType=tv"

# Search for content from 2025
curl "https://mappletv.uk/api/4k_media?search=2025"

# Search for content from 2024 with "marvel" in title
curl "https://mappletv.uk/api/4k_media?search=2024&mediaType=movie"

Filtering Examples

# Get only movies
curl "https://mappletv.uk/api/4k_media?mediaType=movie"

# Get only TV shows
curl "https://mappletv.uk/api/4k_media?mediaType=tv"

# Get TV shows with pagination
curl "https://mappletv.uk/api/4k_media?mediaType=tv&page=1&perPage=15"

Year Filtering Examples

# Get movies from 2023
curl "https://mappletv.uk/api/4k_media?year=2023&mediaType=movie"

# Get TV shows from 2024
curl "https://mappletv.uk/api/4k_media?year=2024&mediaType=tv"

# Get all 4K content from 2022
curl "https://mappletv.uk/api/4k_media?year=2022"

Combined Examples

# Search for action movies from 2023 with pagination
curl "https://mappletv.uk/api/4k_media?search=action&mediaType=movie&year=2023&page=2&perPage=25"

# Search for recent TV shows from 2024
curl "https://mappletv.uk/api/4k_media?search=2024&mediaType=tv&year=2024&perPage=30"

# Get all movies with "marvel" in title from 2023
curl "https://mappletv.uk/api/4k_media?search=marvel&mediaType=movie&year=2023"

JavaScript/TypeScript Examples

Using Fetch API

// Basic fetch
const response = await fetch('/api/4k_media?page=1&perPage=20');
const data = await response.json();

// Search with filters
const searchResponse = await fetch('/api/4k_media?search=marvel&mediaType=movie');
const searchData = await searchResponse.json();

Using Axios

import axios from 'axios';

// Get 4K movies
const getMovies = async (page = 1) => {
  const response = await axios.get('/api/4k_media', {
    params: {
      mediaType: 'movie',
      page,
      perPage: 20
    }
  });
  return response.data;
};

// Search 4K content
const searchContent = async (query, mediaType = null) => {
  const params = { search: query };
  if (mediaType) params.mediaType = mediaType;
  
  const response = await axios.get('/api/4k_media', { params });
  return response.data;
};

Error Handling

The API returns appropriate HTTP status codes:

200 - Success
500 - Server error

Error response format:

{
  "error": "Failed to fetch 4K media",
  "items": [],
  "total": 0,
  "page": 1,
  "perPage": 20,
  "totalPages": 0,
  "hasNextPage": false,
  "hasPrevPage": false
}

Rate Limiting

Please be mindful of API usage and implement appropriate rate limiting in your applications. The API is designed to handle reasonable request volumes.

Notes

All content returned is in 4K (2160p) quality
TV shows are automatically deduplicated (only one entry per show)
Search is case-insensitive and matches partial titles or years
Results are sorted by release date (newest first)

PreviousEndpoints

NextImplementation

Embed API Docs