Shows

A show object represents a movie or a series. Type of the show is determined by the showType property, which is either movie or series. Based on this type, some properties are omitted, for example a movie does not have seasonCount and episodeCount properties.

Show object contains the details such as the title, overview, genres, cast, rating and images. You can find the streaming availability information under streamingOptions property. Each streaming option contains the service info, deep link, video quality, available audios and subtitles and more. It also includes the price if the show is available to buy or rent; and addon info if the show is available via an addon (such as Apple TV Channels, Prime Video Channels etc.).

You can also find the seasons of the series under the seasons property, and the episodes of a season under the episodes property of the season object. Via the streamingOptions property of seasons and episodes, you can get the individual streaming options of them. These streaming options include the same set of properties as the show streaming options, so you can use them to get deep links to episodes and seasons, and to see available audios and subtitles.

Note that seasons and episodes are not included in the search results unless you set the series_granularity parameter to seasons or episodes. For more info, check out the series_granularity parameter of the search endpoints.

There are multiple ways to retrieve shows. You can retrieve a show by its IMDb or TMDB id via /shows/{id} endpoint; you can search shows by their title via /shows/search/title endpoint; and you can search shows by filters such as genres, release year, rating etc. via /shows/search/filters endpoint. This endpoint also supports pagination and offers advanced ordering options such as ordering by popularity, rating, release year etc.


The Shows object

Properties

  • Name
    itemType
    Type
    string
    Description

    Type of the item. Always show.

  • Name
    showType
    Type
    string enum
    Description

    Type of the show. Based on the type, some properties might be omitted.

    Enum values
  • Name
    id
    Type
    string
    Description

    Id of the show.

  • Name
    imdbId
    Type
    string
    Description

    IMDb id of the show.

  • Name
    tmdbId
    Type
    string
    Description

    TMDB id of the show.

  • Name
    title
    Type
    string
    Description

    Title of the show.

  • Name
    overview
    Type
    string
    Description

    A brief overview of the overall plot of the show.

  • Name
    releaseYear
    Type
    nullable integer
    Description

    The year that the movie was released.

  • Name
    firstAirYear
    Type
    nullable integer
    Description

    The first year that the series aired.

  • Name
    lastAirYear
    Type
    nullable integer
    Description

    The last year that the series aired.

  • Name
    originalTitle
    Type
    string
    Description

    Original title of the show.

  • Name
    genres
    Type
    array of genre objects
    Description

    Array of the genres of the show.

    Child properties
  • Name
    directors
    Type
    nullable array of strings
    Description

    Array of the directors of the movie.

  • Name
    creators
    Type
    nullable array of strings
    Description

    Array of the creators of the series.

  • Name
    cast
    Type
    array of strings
    Description

    Array of the cast of the show.

  • Name
    rating
    Type
    integer
    Description

    Rating of the show. This is calculated by taking the average of ratings found online from multiple sources.

    Minimum value:
    0
    Maximum value:
    100
  • Name
    seasonCount
    Type
    nullable integer
    Description

    Number of seasons that are either aired or announced for a series.

  • Name
    episodeCount
    Type
    nullable integer
    Description

    Number of episodes that are either aired or announced for a series.

  • Name
    runtime
    Type
    nullable integer
    Description

    Runtime of the movie in minutes.

  • Name
    imageSet
    Type
    object
    Description

    Image set of the show.

    Child properties
  • Name
    streamingOptions
    Type
    map of arrays of streamingOption objects
    Description

    Map of the streaming options by the country code.

    Child properties
  • Name
    seasons
    Type
    nullable array of season objects
    Description

    Array of the seasons belong to the series.

    Child properties

Examples

    • "show"
    • "movie"
    • "82"
    • "tt0068646"
    • "movie/238"
    • "The Godfather"
    • "Winner of three Academy Awards including Best Picture, Francis Ford Coppola's epic masterpiece paints a chilling portrait of the Corleone family, balancing the story between their family life and the ugly crime business in which they are engaged."
    • 1972
    • "The Godfather"
    • [] 2 items
      • [] 1 item
        • [] 7 items
          • 88
          • 176
          • {} 4 keys
            • {} 52 keys

            GET/shows/{id}

            Get a Show

            Get the details of a show via id, imdbId or tmdbId, including the global streaming availability info.

            Path parameters

            • Name
              id
              Type
              string
              Description

              id of the show. You can also pass an IMDb Id or a TMDB Id as an id. The endpoint will automatically detect the type of the id and fetch the show accordingly.

              When passing an IMDb Id, it should be in the format of tt<numerical_id>. (e.g. tt0120338 for Titanic)

              When passing a TMDB Id, it should be in the format of movie/<numerical_id> for movies and tv/<numerical_id> for series. (e.g. tv/1396 for Breaking Bad and movie/597 for Titanic)

              Example values

            Optional parameters

            • Name
              country
              Type
              string
              Description

              ISO 3166-1 alpha-2 code of the optional target country. If this parameter is not supplied, global streaming availability across all the countries will be returned. If it is supplied, only the streaming availability info from the given country will be returned. If you are only interested in the streaming availability in a single country, then it is recommended to use this parameter to reduce the size of the response and increase the performance of the endpoint. See /countries endpoint to get the list of supported countries.

              Example values
            • Name
              series_granularity
              Type
              string enum
              Description

              series_granularity determines the level of detail for series. It does not affect movies.

              If series_granularity is show, then the output will not include season and episode info.

              If series_granularity is season, then the output will include season info but not episode info.

              If series_granularity is episode, then the output will include season and episode info.

              If you do not need season and episode info, then it is recommended to set series_granularity as show to reduce the size of the response and increase the performance of the endpoint.

              If you need deep links for individual seasons and episodes, then you should set series_granularity as episode. In this case response will include full streaming info for seasons and episodes, similar to the streaming info for movies and series; including deep links into seasons and episodes, individual subtitle/audio and video quality info etc.

              Default value:
              episode
              Enum values
            • Name
              output_language
              Type
              string enum
              Description

              ISO 639-1 code of the output language. Determines in which language the output will be in.

              Default value:
              en
              Enum values

            Request

            GET
            /shows/tt0068646
            curl -G https://streaming-availability.p.rapidapi.com/shows/tt0068646 \
            	-H "X-RapidAPI-Key: {YOUR_API_KEY}"

            Response

            200

              • "show"
              • "movie"
              • "82"
              • "tt0068646"
              • "movie/238"
              • "The Godfather"
              • "Winner of three Academy Awards including Best Picture, Francis Ford Coppola's epic masterpiece paints a chilling portrait of the Corleone family, balancing the story between their family life and the ugly crime business in which they are engaged."
              • 1972
              • "The Godfather"
              • [] 2 items
                • [] 1 item
                  • [] 7 items
                    • 88
                    • 176
                    • {} 4 keys
                      • {} 52 keys

                      GET/shows/search/filters

                      Search Shows by filters

                      Search through the catalog of the given streaming services in the given country. Provides filters such as show language, genres, keyword and release year. Output includes all the information about the shows, such as title, IMDb ID, TMDb ID, release year, deep links to streaming services, available subtitles, audios, available video quality and many more! Apart from the info about the given country-service combinations, output also includes information about streaming availability in the other services for the given country. Streaming availability info from the other countries are not included in the response.

                      When show_type is movie or series_granularity is show, items per page is 20. When show_type is series and series_granularity is episode items per page is 10. Otherwise, items per page is 15.

                      Required parameters

                      • Name
                        country
                        Type
                        string
                        Description

                        ISO 3166-1 alpha-2 code of the target country. See /countries endpoint to get the list of supported countries.

                        Example values

                      Optional parameters

                      • Name
                        catalogs
                        Type
                        array of strings
                        Description

                        A comma separated list of up to 32 catalogs to search in. See /countries endpoint to get the supported services in each country and their ids.

                        When multiple catalogs are passed as a comma separated list, any show that is in at least one of the catalogs will be included in the result.

                        If no catalogs are passed, the endpoint will search in all the available catalogs in the country.

                        Syntax of the catalogs supplied in the list can be as the followings:

                        • <sevice_id>: Searches in the entire catalog of that service, including (if applicable) rentable, buyable shows or shows available through addons e.g. netflix, prime, apple

                        • <sevice_id>.<streaming_option_type>: Only returns the shows that are available in that service with the given streaming option type. Valid streaming option types are subscription, free, rent, buy and addon e.g. peacock.free only returns the shows on Peacock that are free to watch, prime.subscription only returns the shows on Prime Video that are available to watch with a Prime subscription. hulu.addon only returns the shows on Hulu that are available via an addon, prime.rent only returns the shows on Prime Video that are rentable.

                        • <sevice_id>.addon.<addon_id>: Only returns the shows that are available in that service with the given addon. Check /countries endpoint to fetch the available addons for a service in each country. Some sample values are: hulu.addon.hbo, prime.addon.hbomaxus.

                        Example values
                      • Name
                        output_language
                        Type
                        string enum
                        Description

                        ISO 639-1 code of the output language. Determines in which language the output will be in.

                        Default value:
                        en
                        Enum values
                      • Name
                        show_type
                        Type
                        string enum
                        Description

                        Type of shows to search in. If not supplied, both movies and series will be included in the search results.

                        Enum values
                      • Name
                        genres
                        Type
                        array of strings
                        Description

                        A comma seperated list of genre ids to only search within the shows in those genre. See /genres endpoint to see the available genres and their ids. Use genres_relation parameter to specify between returning shows that have at least one of the given genres or returning shows that have all of the given genres.

                        Example values
                      • Name
                        genres_relation
                        Type
                        string enum
                        Description

                        Only used when there are multiple genres supplied in genres parameter.

                        When or, the endpoint returns any show that has at least one of the given genres. When and, it only returns the shows that have all of the given genres.

                        Default value:
                        and
                        Enum values
                      • Name
                        show_original_language
                        Type
                        string
                        Description

                        ISO 639-1 language code to only search within the shows whose original language matches with the provided language.

                        Example values
                      • Name
                        year_min
                        Type
                        integer
                        Description

                        Minimum release/air year of the shows.

                        Example values
                      • Name
                        year_max
                        Type
                        integer
                        Description

                        Maximum release/air year of the shows.

                        Example values
                      • Name
                        rating_min
                        Type
                        integer
                        Description

                        Minimum rating of the shows.

                        Minimum value:
                        0
                        Maximum value:
                        100
                        Example values
                      • Name
                        rating_max
                        Type
                        integer
                        Description

                        Maximum rating of the shows.

                        Minimum value:
                        0
                        Maximum value:
                        100
                        Example values
                      • Name
                        keyword
                        Type
                        string
                        Description

                        A keyword to only search within the shows have that keyword in their overview or title.

                        Example values
                      • Name
                        series_granularity
                        Type
                        string enum
                        Description

                        series_granularity determines the level of detail for series. It does not affect movies.

                        If series_granularity is show, then the output will not include season and episode info.

                        If series_granularity is season, then the output will include season info but not episode info.

                        If series_granularity is episode, then the output will include season and episode info.

                        If you do not need season and episode info, then it is recommended to set series_granularity as show to reduce the size of the response and increase the performance of the endpoint.

                        If you need deep links for individual seasons and episodes, then you should set series_granularity as episode. In this case response will include full streaming info for seasons and episodes, similar to the streaming info for movies and series; including deep links into seasons and episodes, individual subtitle/audio and video quality info etc.

                        Default value:
                        show
                        Enum values
                      • Name
                        order_by
                        Type
                        string enum
                        Description

                        Determines the ordering of the shows.

                        You can switch between ascending and descending order by using the order_direction parameter.

                        Default value:
                        original_title
                        Enum values
                      • Name
                        order_direction
                        Type
                        string enum
                        Description

                        Determines whether to order the results in ascending or descending order.

                        Default value when ordering alphabetically or based on dates/times is asc.

                        Default value when ordering by rating or popularity is desc.

                        Enum values
                      • Name
                        cursor
                        Type
                        string
                        Description

                        Cursor is used for pagination. After each request, the response includes a hasMore boolean field to tell if there are more results that did not fit into the returned list. If it is set as true, to get the rest of the result set, send a new request (with the same parameters for other fields), and set the cursor parameter as the nextCursor value of the response of the previous request. Do not forget to escape the cursor value before putting it into a query as it might contain characters such as ?and &.

                        The first request naturally does not require a cursor parameter.

                      Request

                      GET
                      /shows/search/filters
                      curl -G https://streaming-availability.p.rapidapi.com/shows/search/filters \
                      	-H "X-RapidAPI-Key: {YOUR_API_KEY}" \
                      	--data-urlencode country="us" \
                      	--data-urlencode catalogs="netflix" \
                      	--data-urlencode keyword="zombie" \
                      	--data-urlencode show_type="movie"

                      Response

                      200

                        • [] 20 items
                          • true
                          • "5459413:鬼武者"

                        GET/shows/search/title

                        Search Shows by title

                        Search for movies and series by a title. Maximum amount of items returned are 20 unless there are more than 20 shows with the exact given title input. In that case all the items have 100% match with the title will be returned.

                        Streaming availability info for the target country is included in the response, but not for the other countries.

                        Results might include shows that are not streamable in the target country. Only criteria for the search are the title and the show type.

                        No pagination is supported.

                        Required parameters

                        • Name
                          title
                          Type
                          string
                          Description

                          Title phrase to search for.

                          Example values
                        • Name
                          country
                          Type
                          string
                          Description

                          ISO 3166-1 alpha-2 code of the target country. See /countries endpoint to get the list of supported countries.

                          Example values

                        Optional parameters

                        • Name
                          show_type
                          Type
                          string enum
                          Description

                          Type of shows to search in. If not supplied, both movies and series will be included in the search results.

                          Enum values
                        • Name
                          series_granularity
                          Type
                          string enum
                          Description

                          series_granularity determines the level of detail for series. It does not affect movies.

                          If series_granularity is show, then the output will not include season and episode info.

                          If series_granularity is season, then the output will include season info but not episode info.

                          If series_granularity is episode, then the output will include season and episode info.

                          If you do not need season and episode info, then it is recommended to set series_granularity as show to reduce the size of the response and increase the performance of the endpoint.

                          If you need deep links for individual seasons and episodes, then you should set series_granularity as episode. In this case response will include full streaming info for seasons and episodes, similar to the streaming info for movies and series; including deep links into seasons and episodes, individual subtitle/audio and video quality info etc.

                          Default value:
                          show
                          Enum values
                        • Name
                          output_language
                          Type
                          string enum
                          Description

                          ISO 639-1 code of the output language. Determines in which language the output will be in.

                          Default value:
                          en
                          Enum values

                        Request

                        GET
                        /shows/search/title
                        curl -G https://streaming-availability.p.rapidapi.com/shows/search/title \
                        	-H "X-RapidAPI-Key: {YOUR_API_KEY}" \
                        	--data-urlencode title="Batman"

                        Response

                        200

                          • {} 16 keys
                            • {} 18 keys
                              • {} 16 keys
                                • {} 18 keys
                                  • {} 18 keys
                                    • {} 18 keys
                                      • {} 16 keys
                                        • {} 16 keys
                                          • {} 16 keys
                                            • {} 16 keys
                                              • {} 16 keys
                                                • {} 16 keys
                                                  • {} 16 keys
                                                    • {} 16 keys
                                                      • {} 16 keys
                                                        • {} 16 keys
                                                          • {} 16 keys
                                                            • {} 16 keys
                                                              • {} 16 keys
                                                                • {} 18 keys

                                                                GET/shows/top

                                                                Get Top Shows

                                                                Get the official top shows in a service. Top shows are determined by the streaming service itself.

                                                                Supported streaming services are:

                                                                • Netflix: netflix
                                                                • Amazon Prime Video: prime
                                                                • Apple TV: apple
                                                                • Max: hbo

                                                                For unsupported services, this endpoint will return an empty list.

                                                                Series granularity is always show for this endpoint, meaning that the output will not include season and episode info.

                                                                Required parameters

                                                                • Name
                                                                  country
                                                                  Type
                                                                  string
                                                                  Description

                                                                  ISO 3166-1 alpha-2 code of the target country. See /countries endpoint to get the list of supported countries.

                                                                  Example values
                                                                • Name
                                                                  service
                                                                  Type
                                                                  string
                                                                  Description

                                                                  Id of the target service.

                                                                  Example values

                                                                Optional parameters

                                                                • Name
                                                                  output_language
                                                                  Type
                                                                  string enum
                                                                  Description

                                                                  ISO 639-1 code of the output language. Determines in which language the output will be in.

                                                                  Default value:
                                                                  en
                                                                  Enum values
                                                                • Name
                                                                  show_type
                                                                  Type
                                                                  string enum
                                                                  Description

                                                                  Type of shows to search in. If not supplied, both movies and series will be included in the search results.

                                                                  Enum values

                                                                Request

                                                                GET
                                                                /shows/top
                                                                curl -G https://streaming-availability.p.rapidapi.com/shows/top \
                                                                	-H "X-RapidAPI-Key: {YOUR_API_KEY}" \
                                                                	--data-urlencode country="us" \
                                                                	--data-urlencode service="netflix" \
                                                                	--data-urlencode show_type="series"

                                                                Response

                                                                200

                                                                  • {} 18 keys
                                                                    • {} 18 keys
                                                                      • {} 18 keys
                                                                        • {} 18 keys
                                                                          • {} 18 keys
                                                                            • {} 18 keys
                                                                              • {} 18 keys
                                                                                • {} 18 keys
                                                                                  • {} 18 keys
                                                                                    • {} 18 keys

                                                                                    Was this page helpful?