Subtitles Search API Documentation (beta)

Overview

The Subtitles Search API allows users to search for movie or TV show subtitles based on various criteria such as film name, file name, specific IDs (IMDB, TMDB, SubDL), season and episode numbers, type (movie or TV), release year, and languages.

Endpoint: https://api.subdl.com/api/v1/subtitles Method: GET

Request Parameters

Send these one of these variables as GET URL

  • api_key (Required): the api key from subdl account
  • film_name (optional): Text search by film name.
  • file_name (optional): Search by file name.
  • sd_id (optional): Search by SubDL ID.
  • imdb_id (optional): Search by IMDb ID.
  • tmdb_id (optional): Search by TMDB ID.
  • season_number (optional): Specific season number for TV shows.
  • episode_number (optional): Specific episode number for TV shows.
  • type (optional): Type of the content, either movie or tv.
  • year (optional): Release year of the movie or TV show.
  • languages (optional): Comma-separated language codes for subtitle languages.
  • subs_per_page (optional): limit of subtitles will see in the results default is 10, (max can be 30)
  • comment (optional): send comment=1 to get author comment on subtitle
  • releases (optional): send releases=1 to get releases list on subtitle
  • hi (optional): send hi=1 to get is Hearing Impaired on subtitle
  • full_season (optional): send full_season=1 to get all full season subtitles

Successful Response

A successful response will return a JSON object with the following fields:

  • status: A boolean indicating the success status (true).
  • results: An array of movies or TV shows matching the search criteria.
  • subtitles: An array of subtitles matching the search criteria for the first movie/TV show in the results.

Error Response

An error response is returned as a JSON object with the following fields:

  • status: A boolean indicating the success status (false).
  • error: Error message indicating the reason for failure.

Download link example

Add subtitle link to dl.subdl.com endpoint like this example:

https://dl.subdl.com/subtitle/3197651-3213944.zip

Download raw srt file will coming soon...

Usage Example

Request

{
  "query": {
    "api_key": "abcdefghisubdl",
    "film_name": "Inception",
    "type": "movie",
    "languages": "EN,FR"
  }
}

Response Body

{
  "status": true,
  "results": [
    {
      "imdb_id": "tt1375666",
      "tmdb_id": 27205,
      "type": "movie",
      "name": "Inception",
      "sd_id": 123456,
      "first_air_date": null,
      "year": 2010
    }
  ],
  "subtitles": [
    {
      // Subtitle details
    }
  ]
}

Notes

  • API rate limiting is applied; ensure to manage the number of requests as per your API key's allowance.
  • The search is optimized to first look for exact matches in the database and then proceed with broader criteria if necessary.
  • The language codes should follow the specific format provided in the API documentation to ensure accurate filtering of subtitles.

This API provides a powerful tool for developers to integrate subtitle search functionality into their applications, offering extensive filtering options to cater to a wide range of user preferences.

CURL Example Request

curl -X GET "https://api.subdl.com/api/v1/subtitles?api_key=example-api-key&film_name=Inception&type=movie&languages=EN"

JavaScript code Example Request

fetch(
  "https://api.subdl.com/api/v1/subtitles?api_key=example-api-key&film_name=Inception&type=movie&languages=ar",
  {
    method: "GET",
    headers: {
      Accept: "application/json",
    },
  }
)
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));