Skip to content

TV Episodes

Bases: TMDB

TV Episodes functionality.

See: https://developers.themoviedb.org/3/tv-episodes

Source code in src/tmdb_client_py/tv.py 
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
class TV_Episodes(TMDB):
    """
    TV Episodes functionality.

    See: https://developers.themoviedb.org/3/tv-episodes
    """

    BASE_PATH = "tv/{tv_id}/season/{season_number}/episode/{episode_number}"
    URLS = {
        "info": "",
        "account_states": "/account_states",
        "credits": "/credits",
        "external_ids": "/external_ids",
        "images": "/images",
        "translations": "/translations",
        "rating": "/rating",
        "videos": "/videos",
    }

    def __init__(self, tv_id, season_number, episode_number):
        super().__init__()
        self.tv_id = tv_id
        self.season_number = season_number
        self.episode_number = episode_number

    def info(self, **kwargs):
        """
        Get the TV episode details by id.

        Supports append_to_response. Read more about this at
        https://developers.themoviedb.org/3/getting-started/append-to-response.

        Args:
            language: (optional) ISO 639 code.
            append_to_response: (optional) Append requests within the same
                namespace to the response.

        Returns:
            A dict representation of the JSON returned from the API.
        """
        path = self._get_tv_id_season_number_episode_number_path("info")

        response = self._GET(path, kwargs)
        self._set_attrs_to_values(response)
        return response

    def account_states(self, **kwargs):
        """
        Get your rating for an episode.

        Args:
            session_id: (required) See Authentication.
            guest_session_id: (optional) See Authentication.

        Returns:
            A dict representation of the JSON returned from the API.
        """
        path = self._get_tv_id_season_number_episode_number_path("account_states")

        response = self._GET(path, kwargs)
        self._set_attrs_to_values(response)
        return response

    def credits(self, **kwargs):
        """
        Get the credits (cast, crew and guest stars) for a TV episode.

        Args:
            None

        Returns:
            A dict representation of the JSON returned from the API.
        """
        path = self._get_tv_id_season_number_episode_number_path("credits")

        response = self._GET(path, kwargs)
        self._set_attrs_to_values(response)
        return response

    def external_ids(self, **kwargs):
        """
        Get the external ids for a TV episode. We currently support the
        following external sources.

        External Sources: IMDb ID, TVDB ID, Freebase MID*, Freebase ID*, TVRage
        ID*

        *Defunct or no longer available as a service.

        Args:
            None

        Returns:
            A dict representation of the JSON returned from the API.
        """
        path = self._get_tv_id_season_number_episode_number_path("external_ids")

        response = self._GET(path, kwargs)
        self._set_attrs_to_values(response)
        return response

    def images(self, **kwargs):
        """
        Get the images that belong to a TV episode.

        Querying images with a language parameter will filter the results. If
        you want to include a fallback language (especially useful for
        backdrops) you can use the include_image_language parameter. This
        should be a comma separated value like so:
        include_image_language=en,null.

        Args:
            None

        Returns:
            A dict representation of the JSON returned from the API.
        """
        path = self._get_tv_id_season_number_episode_number_path("images")

        response = self._GET(path, kwargs)
        self._set_attrs_to_values(response)
        return response

    def translations(self, **kwargs):
        """
        Get the translation data for an episode.

        Args:
            None

        Returns:
            A dict representation of the JSON returned from the API.
        """
        path = self._get_tv_id_season_number_episode_number_path("translations")

        response = self._GET(path, kwargs)
        self._set_attrs_to_values(response)
        return response

    def rating(self, **kwargs):
        """
        Rate a TV episode.

        A valid session or guest session ID is required. You can read more
        about how this works at
        https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id.

        Args:
            session_id: (optional) See Authentication.
            guest_session_id: (optional) See Authentication.
            value: (required) This is the value of the rating you want to
                submit. The value is expected to be between 0.5 and 10.0.

        Returns:
            A dict representation of the JSON returned from the API.
        """
        path = self._get_tv_id_season_number_episode_number_path("rating")

        payload = {
            "value": kwargs.pop("value", None),
        }

        response = self._POST(path, kwargs, payload)
        self._set_attrs_to_values(response)
        return response

    def rating_delete(self, **kwargs):
        """
        Remove your rating for a TV episode.

        A valid session or guest session ID is required. You can read more
        about how this works at
        https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id.

        Args:
            session_id: (optional) See Authentication.
            guest_session_id: (optional) See Authentication.

        Returns:
            A dict representation of the JSON returned from the API.
        """
        path = self._get_tv_id_season_number_episode_number_path("rating")

        payload = {
            "value": kwargs.pop("value", None),
        }

        response = self._DELETE(path, kwargs, payload)
        self._set_attrs_to_values(response)
        return response

    def videos(self, **kwargs):
        """
        Get the videos that have been added to a TV episode.

        Args:
            language: (optional) ISO 639 code.

        Returns:
            A dict representation of the JSON returned from the API.
        """
        path = self._get_tv_id_season_number_episode_number_path("videos")

        response = self._GET(path, kwargs)
        self._set_attrs_to_values(response)
        return response

    def _get_tv_id_season_number_episode_number_path(self, key):
        return self._get_path(key).format(
            tv_id=self.tv_id,
            season_number=self.season_number,
            episode_number=self.episode_number,
        )

account_states(**kwargs)

Get your rating for an episode.

Parameters:

Name Type Description Default
session_id

(required) See Authentication.

 required
guest_session_id

(optional) See Authentication.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/tv.py 
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
def account_states(self, **kwargs):
    """
    Get your rating for an episode.

    Args:
        session_id: (required) See Authentication.
        guest_session_id: (optional) See Authentication.

    Returns:
        A dict representation of the JSON returned from the API.
    """
    path = self._get_tv_id_season_number_episode_number_path("account_states")

    response = self._GET(path, kwargs)
    self._set_attrs_to_values(response)
    return response

credits(**kwargs)

Get the credits (cast, crew and guest stars) for a TV episode.

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/tv.py 
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
def credits(self, **kwargs):
    """
    Get the credits (cast, crew and guest stars) for a TV episode.

    Args:
        None

    Returns:
        A dict representation of the JSON returned from the API.
    """
    path = self._get_tv_id_season_number_episode_number_path("credits")

    response = self._GET(path, kwargs)
    self._set_attrs_to_values(response)
    return response

external_ids(**kwargs)

Get the external ids for a TV episode. We currently support the following external sources.

External Sources: IMDb ID, TVDB ID, Freebase MID, Freebase ID, TVRage ID*

*Defunct or no longer available as a service.

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/tv.py 
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
def external_ids(self, **kwargs):
    """
    Get the external ids for a TV episode. We currently support the
    following external sources.

    External Sources: IMDb ID, TVDB ID, Freebase MID*, Freebase ID*, TVRage
    ID*

    *Defunct or no longer available as a service.

    Args:
        None

    Returns:
        A dict representation of the JSON returned from the API.
    """
    path = self._get_tv_id_season_number_episode_number_path("external_ids")

    response = self._GET(path, kwargs)
    self._set_attrs_to_values(response)
    return response

images(**kwargs)

Get the images that belong to a TV episode.

Querying images with a language parameter will filter the results. If you want to include a fallback language (especially useful for backdrops) you can use the include_image_language parameter. This should be a comma separated value like so: include_image_language=en,null.

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/tv.py 
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
def images(self, **kwargs):
    """
    Get the images that belong to a TV episode.

    Querying images with a language parameter will filter the results. If
    you want to include a fallback language (especially useful for
    backdrops) you can use the include_image_language parameter. This
    should be a comma separated value like so:
    include_image_language=en,null.

    Args:
        None

    Returns:
        A dict representation of the JSON returned from the API.
    """
    path = self._get_tv_id_season_number_episode_number_path("images")

    response = self._GET(path, kwargs)
    self._set_attrs_to_values(response)
    return response

info(**kwargs)

Get the TV episode details by id.

Supports append_to_response. Read more about this at https://developers.themoviedb.org/3/getting-started/append-to-response.

Parameters:

Name Type Description Default
language

(optional) ISO 639 code.

 required
append_to_response

(optional) Append requests within the same namespace to the response.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/tv.py 
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
def info(self, **kwargs):
    """
    Get the TV episode details by id.

    Supports append_to_response. Read more about this at
    https://developers.themoviedb.org/3/getting-started/append-to-response.

    Args:
        language: (optional) ISO 639 code.
        append_to_response: (optional) Append requests within the same
            namespace to the response.

    Returns:
        A dict representation of the JSON returned from the API.
    """
    path = self._get_tv_id_season_number_episode_number_path("info")

    response = self._GET(path, kwargs)
    self._set_attrs_to_values(response)
    return response

rating(**kwargs)

Rate a TV episode.

A valid session or guest session ID is required. You can read more about how this works at https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id.

Parameters:

Name Type Description Default
session_id

(optional) See Authentication.

 required
guest_session_id

(optional) See Authentication.

 required
value

(required) This is the value of the rating you want to submit. The value is expected to be between 0.5 and 10.0.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/tv.py 
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
def rating(self, **kwargs):
    """
    Rate a TV episode.

    A valid session or guest session ID is required. You can read more
    about how this works at
    https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id.

    Args:
        session_id: (optional) See Authentication.
        guest_session_id: (optional) See Authentication.
        value: (required) This is the value of the rating you want to
            submit. The value is expected to be between 0.5 and 10.0.

    Returns:
        A dict representation of the JSON returned from the API.
    """
    path = self._get_tv_id_season_number_episode_number_path("rating")

    payload = {
        "value": kwargs.pop("value", None),
    }

    response = self._POST(path, kwargs, payload)
    self._set_attrs_to_values(response)
    return response

rating_delete(**kwargs)

Remove your rating for a TV episode.

A valid session or guest session ID is required. You can read more about how this works at https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id.

Parameters:

Name Type Description Default
session_id

(optional) See Authentication.

 required
guest_session_id

(optional) See Authentication.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/tv.py 
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
def rating_delete(self, **kwargs):
    """
    Remove your rating for a TV episode.

    A valid session or guest session ID is required. You can read more
    about how this works at
    https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id.

    Args:
        session_id: (optional) See Authentication.
        guest_session_id: (optional) See Authentication.

    Returns:
        A dict representation of the JSON returned from the API.
    """
    path = self._get_tv_id_season_number_episode_number_path("rating")

    payload = {
        "value": kwargs.pop("value", None),
    }

    response = self._DELETE(path, kwargs, payload)
    self._set_attrs_to_values(response)
    return response

translations(**kwargs)

Get the translation data for an episode.

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/tv.py 
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
def translations(self, **kwargs):
    """
    Get the translation data for an episode.

    Args:
        None

    Returns:
        A dict representation of the JSON returned from the API.
    """
    path = self._get_tv_id_season_number_episode_number_path("translations")

    response = self._GET(path, kwargs)
    self._set_attrs_to_values(response)
    return response

videos(**kwargs)

Get the videos that have been added to a TV episode.

Parameters:

Name Type Description Default
language

(optional) ISO 639 code.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/tv.py 
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
def videos(self, **kwargs):
    """
    Get the videos that have been added to a TV episode.

    Args:
        language: (optional) ISO 639 code.

    Returns:
        A dict representation of the JSON returned from the API.
    """
    path = self._get_tv_id_season_number_episode_number_path("videos")

    response = self._GET(path, kwargs)
    self._set_attrs_to_values(response)
    return response