Skip to content

Search

Bases: TMDB

Search functionality

See: https://developers.themoviedb.org/3/search

Source code in src/tmdb_client_py/search.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
class Search(TMDB):
    """
    Search functionality

    See: https://developers.themoviedb.org/3/search
    """

    BASE_PATH = "search"
    URLS = {
        "company": "/company",
        "collection": "/collection",
        "keyword": "/keyword",
        "movie": "/movie",
        "multi": "/multi",
        "person": "/person",
        "tv": "/tv",
    }

    def company(self, **kwargs):
        """
        Search for companies.

        Args:
            query: (required) Pass a text query to search. This value should be
                URI encoded.
            page: (optional) Minimum 1, maximum 1000, default 1.

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

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

    def collection(self, **kwargs):
        """
        Search for collections.

        Args:
            language: (optional) (optional) ISO 639-1 code.
            query: (required) Pass a text query to search. This value should be
                URI encoded.
            page: (optional) Minimum 1, maximum 1000, default 1.

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

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

    def keyword(self, **kwargs):
        """
        Search for keywords.

        Args:
            query: (required) Pass a text query to search. This value should be
                URI encoded.
            page: (optional) Minimum 1, maximum 1000, default 1.

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

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

    def movie(self, **kwargs):
        """
        Search for movies.

        Args:
            language: (optional) (optional) ISO 639-1 code.
            query: (required) Pass a text query to search. This value should be
                URI encoded.
            page: (optional) Minimum 1, maximum 1000, default 1.
            include_adult: (optional) Choose whether to include adult
                (pornography) content in the results.
            region: (optional) Specify a ISO 3166-1 code to filter release
                dates. Must be uppercase.
            year: (optional) A filter to limit the results to a specific year
                (looking at all release dates).
            primary_release_year: (optional) A filter to limit the results to a
                specific primary release year.

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

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

    def multi(self, **kwargs):
        """
        Search multiple models in a single request. Multi search currently
        supports searching for movies, tv shows and people in a single request.

        Args:
            language: (optional) (optional) ISO 639-1 code.
            query: (required) Pass a text query to search. This value should be
                URI encoded.
            page: (optional) Minimum 1, maximum 1000, default 1.
            include_adult: (optional) Choose whether to include adult
                (pornography) content in the results.
            region: (optional) Specify a ISO 3166-1 code to filter release
                dates. Must be uppercase.

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

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

    def person(self, **kwargs):
        """
        Search for people.

        Args:
            language: (optional) (optional) ISO 639-1 code.
            query: (required) Pass a text query to search. This value should be
                URI encoded.
            page: (optional) Minimum 1, maximum 1000, default 1.
            include_adult: (optional) Choose whether to include adult
                (pornography) content in the results.
            region: (optional) Specify a ISO 3166-1 code to filter release
                dates. Must be uppercase.

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

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

    def tv(self, **kwargs):
        """
        Search for a TV show.

        Args:
            language: (optional) (optional) ISO 639-1 code.
            query: (required) Pass a text query to search. This value should be
                URI encoded.
            page: (optional) Minimum 1, maximum 1000, default 1.
            include_adult: (optional) Choose whether to include adult
                (pornography) content in the results.
            first_air_date_year: (optional) Filter the results to only match
                shows that have an air date with with value.

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

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

collection(**kwargs)

Search for collections.

Parameters:

Name Type Description Default
language

(optional) (optional) ISO 639-1 code.

 required
query

(required) Pass a text query to search. This value should be URI encoded.

 required
page

(optional) Minimum 1, maximum 1000, default 1.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/search.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def collection(self, **kwargs):
    """
    Search for collections.

    Args:
        language: (optional) (optional) ISO 639-1 code.
        query: (required) Pass a text query to search. This value should be
            URI encoded.
        page: (optional) Minimum 1, maximum 1000, default 1.

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

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

company(**kwargs)

Search for companies.

Parameters:

Name Type Description Default
query

(required) Pass a text query to search. This value should be URI encoded.

 required
page

(optional) Minimum 1, maximum 1000, default 1.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/search.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def company(self, **kwargs):
    """
    Search for companies.

    Args:
        query: (required) Pass a text query to search. This value should be
            URI encoded.
        page: (optional) Minimum 1, maximum 1000, default 1.

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

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

keyword(**kwargs)

Search for keywords.

Parameters:

Name Type Description Default
query

(required) Pass a text query to search. This value should be URI encoded.

 required
page

(optional) Minimum 1, maximum 1000, default 1.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/search.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def keyword(self, **kwargs):
    """
    Search for keywords.

    Args:
        query: (required) Pass a text query to search. This value should be
            URI encoded.
        page: (optional) Minimum 1, maximum 1000, default 1.

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

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

movie(**kwargs)

Search for movies.

Parameters:

Name Type Description Default
language

(optional) (optional) ISO 639-1 code.

 required
query

(required) Pass a text query to search. This value should be URI encoded.

 required
page

(optional) Minimum 1, maximum 1000, default 1.

 required
include_adult

(optional) Choose whether to include adult (pornography) content in the results.

 required
region

(optional) Specify a ISO 3166-1 code to filter release dates. Must be uppercase.

 required
year

(optional) A filter to limit the results to a specific year (looking at all release dates).

 required
primary_release_year

(optional) A filter to limit the results to a specific primary release year.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/search.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def movie(self, **kwargs):
    """
    Search for movies.

    Args:
        language: (optional) (optional) ISO 639-1 code.
        query: (required) Pass a text query to search. This value should be
            URI encoded.
        page: (optional) Minimum 1, maximum 1000, default 1.
        include_adult: (optional) Choose whether to include adult
            (pornography) content in the results.
        region: (optional) Specify a ISO 3166-1 code to filter release
            dates. Must be uppercase.
        year: (optional) A filter to limit the results to a specific year
            (looking at all release dates).
        primary_release_year: (optional) A filter to limit the results to a
            specific primary release year.

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

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

multi(**kwargs)

Search multiple models in a single request. Multi search currently supports searching for movies, tv shows and people in a single request.

Parameters:

Name Type Description Default
language

(optional) (optional) ISO 639-1 code.

 required
query

(required) Pass a text query to search. This value should be URI encoded.

 required
page

(optional) Minimum 1, maximum 1000, default 1.

 required
include_adult

(optional) Choose whether to include adult (pornography) content in the results.

 required
region

(optional) Specify a ISO 3166-1 code to filter release dates. Must be uppercase.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/search.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def multi(self, **kwargs):
    """
    Search multiple models in a single request. Multi search currently
    supports searching for movies, tv shows and people in a single request.

    Args:
        language: (optional) (optional) ISO 639-1 code.
        query: (required) Pass a text query to search. This value should be
            URI encoded.
        page: (optional) Minimum 1, maximum 1000, default 1.
        include_adult: (optional) Choose whether to include adult
            (pornography) content in the results.
        region: (optional) Specify a ISO 3166-1 code to filter release
            dates. Must be uppercase.

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

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

person(**kwargs)

Search for people.

Parameters:

Name Type Description Default
language

(optional) (optional) ISO 639-1 code.

 required
query

(required) Pass a text query to search. This value should be URI encoded.

 required
page

(optional) Minimum 1, maximum 1000, default 1.

 required
include_adult

(optional) Choose whether to include adult (pornography) content in the results.

 required
region

(optional) Specify a ISO 3166-1 code to filter release dates. Must be uppercase.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/search.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def person(self, **kwargs):
    """
    Search for people.

    Args:
        language: (optional) (optional) ISO 639-1 code.
        query: (required) Pass a text query to search. This value should be
            URI encoded.
        page: (optional) Minimum 1, maximum 1000, default 1.
        include_adult: (optional) Choose whether to include adult
            (pornography) content in the results.
        region: (optional) Specify a ISO 3166-1 code to filter release
            dates. Must be uppercase.

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

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

tv(**kwargs)

Search for a TV show.

Parameters:

Name Type Description Default
language

(optional) (optional) ISO 639-1 code.

 required
query

(required) Pass a text query to search. This value should be URI encoded.

 required
page

(optional) Minimum 1, maximum 1000, default 1.

 required
include_adult

(optional) Choose whether to include adult (pornography) content in the results.

 required
first_air_date_year

(optional) Filter the results to only match shows that have an air date with with value.

 required

Returns:

Type Description

A dict representation of the JSON returned from the API.
Source code in src/tmdb_client_py/search.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
def tv(self, **kwargs):
    """
    Search for a TV show.

    Args:
        language: (optional) (optional) ISO 639-1 code.
        query: (required) Pass a text query to search. This value should be
            URI encoded.
        page: (optional) Minimum 1, maximum 1000, default 1.
        include_adult: (optional) Choose whether to include adult
            (pornography) content in the results.
        first_air_date_year: (optional) Filter the results to only match
            shows that have an air date with with value.

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

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