Client module#

Client class for the Pexels Unofficial API Wrapper Author: Joker Hacker

class Pexels.client.Client(token: str, base_endpoint: str = 'https://api.pexels.com/v1/', video_endpoint: str = 'https://api.pexels.com/videos')#

Bases: object

This object represents Client.

client = Client(token="abcde12345")

Note

Whenever you are doing an API request make sure to show a prominent link to Pexels.

You can use a text link (e.g. “Photos provided by Pexels”) or a link with our logo.

Always credit our photographers when possible (e.g. “Photo by John Doe on Pexels” with a link to the photo page on Pexels).
Most Pexels API requests return multiple records at once. All of these endpoints are paginated,

and can return a maximum of 80 requests at one time. Each paginated request accepts the same parameters and returns the same pagination data in the response.

The prev_page and next_page response attributes will only be returned if there is a corresponding page.

Warning

You may not copy or replicate core functionality of Pexels (including making Pexels content available as a wallpaper app).
Do not abuse the API. By default, the API is rate-limited to 200 requests per hour and 20,000 requests per month.

Parameters:

token (str) – Unique authentication token.
base_endpoint (str, optional) – Base endpoint of the API, defaults to https://api.pexels.com/v1/
video_endpoint (str, optional) – Video endpoint of the API, defaults to https://api.pexels.com/videos

get_collection_media(id: str, type: Optional[str] = '', page: Optional[int] = 1, per_page: Optional[int] = 15, **kwargs) → CollectionMediaResponse#

This method returns all featured collections on Pexels.

Parameters:

type (str, optional) – The type of media you are requesting, If not given or if given with an invalid value, all media will be returned. Supported values are photos and videos
page (int, optional) – The page number you are requesting. Default: 1
per_page (int, optional) – The number of results you are requesting per page. Default: 15 Max: 80

Returns:

Pexels.types.CollectionResponse

Raises:

PexelsError – When per_page is above 80.

get_featured_collections(page: Optional[int] = 1, per_page: Optional[int] = 15, **kwargs) → CollectionResponse#

This method returns all featured collections on Pexels.

Parameters:

page (int, optional) – The page number you are requesting. Default: 1
per_page (int, optional) – The number of results you are requesting per page. Default: 15 Max: 80

Returns:

Pexels.types.CollectionResponse

Raises:

PexelsError – When per_page is above 80.

get_my_collections(page: Optional[int] = 1, per_page: Optional[int] = 15, **kwargs) → CollectionResponse#

This method returns all of your collections.

Parameters:

page (int, optional) – The page number you are requesting. Default: 1
per_page (int, optional) – The number of results you are requesting per page. Default: 15 Max: 80

Returns:

Pexels.types.CollectionResponse

Raises:

PexelsError – When per_page is above 80.

get_photo(id: int) → Photo#

Retrieve a specific Photo from its id.

Parameters:: id (int) – The id of the photo you are requesting.
Returns:: Pexels.types.Photo

get_popular_videos(min_width: Optional[int], min_height: Optional[int], min_duration: Optional[int], max_duration: Optional[int], page: Optional[int] = 1, per_page: Optional[int] = 15, **kwargs) → VideoResponse#

This method enables you to receive the current popular Pexels videos.

Parameters:

min_width (int, optional) – The minimum width in pixels of the returned videos.
min_height (int, optional) – The maximum height in pixels of the returned videos.
min_duration (int, optional) – The minimum duration in seconds of the returned videos.
max_duration (int, optional) – The maximum duration in seconds of the returned videos.
page (int, optional) – The page number you are requesting. Default: 1
per_page (int, optional) – The number of results you are requesting per page. Default: 15 Max: 80

Returns:

Pexels.types.VideoResponse

Raises:

PexelsError – When per_page is above 80.

get_video(id: int) → Video#

Retrieve a specific Video from its id.

Parameters:: id (int) – The id of the video you are requesting.
Returns:: Pexels.types.Video

search_curated_photo(page: Optional[int] = 1, per_page: Optional[int] = 15) → PhotoResponse#

This method enables you to receive real-time photos curated by the Pexels team. We add at least one new photo per hour to our curated list so that you always get a changing selection of trending photos.

Parameters:

page (int, optional) – The page number you are requesting. Default: 1
per_page (int, optional) – The number of results you are requesting per page. Default: 15 Max: 80

Returns:

Pexels.types.PhotoResponse

Raises:

PexelsError – When per_page is above 80.

search_photos(query: str, orientation: Optional[str] = '', size: Optional[str] = '', color: Optional[str] = '', locale: Optional[str] = '', page: Optional[int] = 1, per_page: Optional[int] = 15, **kwargs) → PhotoResponse#

This method enables you to search photos for any topic that you would like. For example your query could be something broad like Nature, Tigers, People. Or it could be something specific like Group of people working.

Parameters:

query (str) – The search query. Ocean, Tigers, Pears, etc.
orientation (str, optional) – Desired photo orientation. list of supported orientations are available at Pexels.constants.ORIENTATION.
size (str, optional) – Minimum photo size. list of supported sizes are available at Pexels.constants.SIZE.
color (str, optional) – Desired photo color. list of supported colors are available at Pexels.constants.COLOR.
locale (str, optional) – The locale of the search you are performing. list of supported locales are available at Pexels.constants.LOCALE_SUPPORTED.
page (int, optional) – The page number you are requesting. Default: 1
per_page (int, optional) – The number of results you are requesting per page. Default: 15 Max: 80

Returns:

Pexels.types.PhotoResponse

Raises:

PexelsError – When invalid orientation or color or size or locale given or when per_page is above 80.

search_videos(query: str, orientation: str = '', size: str = '', locale: str = '', page: Optional[int] = 3, per_page: Optional[int] = 15, **kwargs) → VideoResponse#

This method enables you to search Videos for any topic that you would like. For example your query could be something broad like Nature, Tigers, People. Or it could be something specific like Group of people working.

Parameters:

query (str) – The search query. Ocean, Tigers, Pears, etc.
orientation (str, optional) – Desired Video orientation. list of supported orientations are available at Pexels.constants.ORIENTATION.
size (str, optional) – Minimum Video size. list of supported sizes are available at Pexels.constants.SIZE.
locale (str, optional) – The locale of the search you are performing. list of supported locales are available at Pexels.constants.LOCALE_SUPPORTED.
page (int, optional) – The page number you are requesting. Default: 1
per_page (int, optional) – The number of results you are requesting per page. Default: 15 Max: 80

Returns:

Pexels.types.VideoResponse

Raises:

PexelsError – When invalid orientation or size or locale given or when per_page is above 80.