PyPexels

An open source Python wrapper for the Pexels REST API.

The source code is available on GitHub at https://github.com/salvoventura/pypexels.

Installation

PyPexels is available on PyPI and thus can be installed with pip on most platforms.

$ pip install pypexels

Dependencies

This library depends on Requests to make - well - requests to the Pexels API. This additional package should be automatically installed at installation time, or you can simply install it by:

$ pip install requests

Usage

Creating an instance

import pypexels
pp = pypexels.PyPexels(api_key='YOUR_API_KEY')

API keys can be obtained from Pexels API page.

Library logging

The PyPexels library internal logging subsystem is driven by the application. The default logging level of the library is set to be logging.ERROR. If you want to access the library logging subsystem, you can fine-tune the logger with id PyPexels.logger_name as per the following example:

from pypexels import PyPexels

# Initialize app logging
logger = logging.getLogger()
logging.basicConfig(filename='app.log', level=logging.DEBUG)

# pypexels logger defaults to level logging.ERROR
# If you need to change that, use getLogger/setLevel
# on the module logger, like this:
logging.getLogger(PyPexels.logger_name).setLevel(logging.DEBUG)

py_pexels = PyPexels(api_key='YOUR_API_KEY')
# ... continue

Examples

These example shows how the interaction with the paging functionality of the Pexels API is greatly abstracted and simplified.

Random

The code below will return random images. Use the parameter per_page to specify how many random images the iterator will allow.

from pypexels import PyPexels
api_key = 'YOUR_API_KEY'

# instantiate PyPexels object
py_pexel = PyPexels(api_key=api_key)

random_photos_page = py_pexel.random(per_page=3)
for photo in random_photos_page.entries:
    print(photo.id, photo.photographer, photo.url)

Single Photo

The code below will return an image object. Use the parameter photo_id to specify the ID of the image.

from pypexels import PyPexels
api_key = 'YOUR_API_KEY'

# instantiate PyPexels object
py_pexel = PyPexels(api_key=api_key)

# access single photo by its ID
photo = py_pexel.single_photo(photo_id=415071)
print(photo.id, photo.photographer, photo.url)

Search Videos

The code below will perform a search of videos based on a query string, then iterate through all the results pages of 40 videos each, retrieve each video in there, and print some of their attributes.

from pypexels import PyPexels
api_key = 'YOUR_API_KEY'

# instantiate PyPexels object
py_pexel = PyPexels(api_key=api_key)

search_videos_page = py_pexel.videos_search(query="red+flower", per_page=40)
while True:
    for video in search_videos_page.entries:
        print(video.id, video.user.get('name'), video.url)
    if not search_videos_page.has_next:
        break
    search_videos_page = search_videos_page.get_next_page()

Single Video

The code below will return a video object. Use the parameter video_id to specify the ID of the video.

from pypexels import PyPexels
api_key = 'YOUR_API_KEY'

# instantiate PyPexels object
py_pexel = PyPexels(api_key=api_key)

# access single video by its ID
video = py_pexel.single_video(video_id=1448735)
print(video.id, video.user.get('name'), video.url)

API: Class PyPexels

This is the main class used to interact with the Pexels REST API.

PyPexels(api_key)

Create an instance of class PyPexels. The api_key parameter is required. API keys can be obtained from Pexels API page.

Parameters

Argument Type Optional/Required Notes
api_key string required Your API key
api_version string optional API version to use. Default: ‘v1’

Returns

Object Instance of class PyPexels

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

Methods

Methods exposed by the PyPexels class.

API: Class Curated

This class is used to access the curated photos on the PyPexels /curated/ REST API.

It is returned as result from a call to PyPexels.curated(page, per_page)

Properties

Properties exposed by the Curated class.

Curated.entries

Iterator for the returned objects contained in this Curated instance. Each entry will be an instance of class Photo.

iterator each time an instance of class Photo

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
curated_photos_page = py_pexel.curated(per_page=40)
for photo in curated_photos_page.entries:
    print(photo.id, photo.photographer, photo.url)
    # no need to specify per_page: will take from original object
    curated_photos_page = curated_photos_page.get_next_page()
curated_results = py_pexel.curated(per_page=40)
for photo in curated_results.entries:
    print(photo.id, photo.photographer, photo.url)

Curated.page

Current curated photos page number.

int current curated photos page number

Curated.per_page

Current curated photos per_page value.

int current curated photos per_page value

Curated.has_previous

Returns boolean True or False depending on whether the current results page has a previous page to navigate to or not.

boolean presence of previous page results

Curated.has_next

Returns boolean True or False depending on whether the current results page has a next page to navigate to or not.

boolean presence of next page results

Curated.body

Returns JSON body of curated photos page.

JSON JSON converted body of results page

Curated.headers

Returns response headers of curated photos page.

dict headers of results page

Methods

Methods exposed by the Curated class.

Curated.get_page()

Returns the requested curated photos page with the current query and per_page parameters. The returned page may not contain entries if the page is out of boundaries.

Parameters

Argument Type Optional/Required Notes
page number required Page number to retrieve.

Returns

Object Instance of class Curated

Curated.get_next_page()

Returns next available curated photos page with the current query, page, and per_page parameters. Returns None if no page is available.

Returns

Object Instance of class Curated or None

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
search_results = py_pexel.curated(query='red flowers', per_page=40)
while search_results is not None:
    print 'Current page number %s' % search_results.page
    search_results = search_results.get_next_page()

Curated.get_previous_page()

Returns previous available curated photos page with the current query, page, and per_page parameters. Returns None if no page is available.

Returns

Object Instance of class Curated or None

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
search_results = py_pexel.curated(query='red flowers', page=3, per_page=40)
while search_results is not None:
    print 'Current page number %s' % search_results.page
    search_results = search_results.get_previous_page()

Curated.get_first_page()

Returns first curated photos page with the current query, page, and per_page parameters. Returns None if no page is available.

Returns

Object Instance of class Curated or None

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
search_results = py_pexel.curated(query='red flowers', page=3, per_page=40)
print 'Current page number %s' % search_results.page
# To something with search_results

# Go back to first page
search_results = search_results.get_first_page():
print 'Current page number %s' % search_results.page

Note

curated.get_last_page() always returns the first page.

API: Class Random

This class is used to emulate a random API using the PyPexels /curated/ REST API.

It is returned as result from a call to PyPexels.random(per_page)

Properties

Properties exposed by the Random class.

Random.entries

Returns an iterator for the returned objects contained in this Random instance. Each entry will be an instance of class Photo.

iterator each time an instance of class Photo

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
random_results = py_pexel.random(per_page=10)
for photo in random_results.entries:
    print(photo.id, photo.photographer, photo.url)

Random.per_page

Current random results per_page value.

int current random results per_page value

Random.has_previous

Returns always boolean False

boolean presence of previous page results

Random.has_next

Returns always boolean True

boolean presence of next page results

IMPORTANT NOTE

Although this class will expose additional methods and properties from the PyPexels.Curated class, you should only rely upon and make use of the methods and properties listed above. Remember, this is a convenience class that provides some uniformity in behavior while emulating a random image generator. If you need to fully control the content and behavior of the classes, then revert to use PyPexels.Curated class, with per_page=1 and page=randint() value directly.

API: Class SinglePhoto

This class is used to create an individual SinglePhoto objects from its ID.

Properties

Properties exposed by the SinglePhoto class.

‘entries’

SinglePhoto.entries

Iterator for the returned objects contained in this SinglePhoto instance. Each entry will be an instance of class Photo.

Note You should not use this class directly. Use PyPexels.single_photo() instead.

iterator each time an instance of class Photo

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
photo = py_pexel.single_photo(photo_id=<ID>)
print(photo.id, photo.photographer, photo.url)

API: Class Photo

This class is used to interact with individual Photo objects typically returned by PyPexels as part of either Search or Popular object entries.

Properties

Properties exposed by the Photo class.

‘id’, ‘width’, ‘height’, ‘url’, ‘photographer’, ‘photographer_url’, ‘photographer_id’, ‘src’, ‘liked’

Photo.id

Unique identifier for this photo

int Unique identifier for this photo

Photo.width

Original image size width

int Original image size width

Photo.height

Original image size height

int Original image size height

Photo.url

URL location of Pexels web page for this photo

str Pexels.com page for this photo

Photo.photographer

Name of photographer or photo source

str Name of photographer or photo source

Photo.photographer_url

URL of photographer page on Pexels

str URL of photographer page on Pexels

Photo.photographer_id

Unique identifier for this photographer

int Unique identifier for this photographer

Photo.src

Dictionary with direct links to the image in different sizes and resolutions.

dict links to the image in different sizes and resolutions

The next table details the key and their corresponding image size attributes.

Image formats

Key Description
original The size of the original image is given with the attributes width and height.
large2x This image has a maximum width of 1880px and a maximum height of 1300px. It has the aspect ratio of the original image.
large This image has a maximum width of 940px and a maximum height of 650px. It has the aspect ratio of the original image.
medium This image has a height of 350px and a flexible width. It has the aspect ratio of the original image.
small This image has a height of 130px and a flexible width. It has the aspect ratio of the original image.
portrait This image has a width of 800px and a height of 1200px.
landscape This image has a width of 1200px and height of 627px.
tiny This image has a width of 280px and height of 200px.

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

search_results = py_pexel.search(query='red flowers', per_page=40)
for photo in search_results.entries:
    print(photo.id, photo.photographer, photo.url)
    print photo.src.get('large')
    print photo.src.get('tiny')

Photo.liked

Unique identifier for this photographer

bool Whether liked or not by this API user

Methods

Methods exposed by the Photo class.

‘get_attribution()’

Photo.get_attribution(_format=’str’)

Generate and return a standard attribution string according to ‘_format’ parameter.

Parameters

Argument Type Optional/Required Notes
_format string optional Valid values: ‘txt’, ‘html’

Returns

string Text or HTML standard attribution string.

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

# Retrieve a single photo, known by its ID
photo = py_pexel.single_photo(photo_id=<ID>)
print(photo.get_attribution('txt'))
print(photo.get_attribution('html'))

API: Class VideoPopular

This class is used to access the popular videos on the PyPexels /videos/popular/ REST API.

It is returned as result from a call to PyPexels.videos_popular(page, per_page)

Properties

Properties exposed by the VideosPopular class.

VideosPopular.entries

Iterator for the returned objects contained in this VideosPopular instance. Each entry will be an instance of class Video.

iterator each time an instance of class Videos

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
popular_videos_page = py_pexel.videos_popular(per_page=40)
while True:
    for video in popular_videos_page.entries:
        print(video.id, video.user.get('name'), video.url)
    if not popular_videos_page.has_next:
        break
    popular_videos_page = popular_videos_page.get_next_page()

VideosPopular.page

Current popular photos page number.

int current popular photos page number

VideosPopular.per_page

Current popular photos per_page value.

int current popular photos per_page value

VideosPopular.has_previous

Returns boolean True or False depending on whether the current results page has a previous page to navigate to or not.

boolean presence of previous page results

VideosPopular.has_next

Returns boolean True or False depending on whether the current results page has a next page to navigate to or not.

boolean presence of next page results

VideosPopular.body

Returns JSON body of popular photos page.

JSON JSON converted body of results page

VideosPopular.headers

Returns response headers of popular photos page.

dict headers of results page

Methods

Methods exposed by the VideosPopular class.

VideosPopular.get_page()

Returns the requested popular photos page with the current query and per_page parameters. The returned page may not contain entries if the page is out of boundaries.

Parameters

Argument Type Optional/Required Notes
page number required Page number to retrieve.

Returns

Object Instance of class VideosPopular

VideosPopular.get_next_page()

Returns next available popular photos page with the current query, page, and per_page parameters. Returns None if no page is available.

Returns

Object Instance of class VideosPopular or None

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
search_results = py_pexel.videos_popular(query='red flowers', per_page=40)
while search_results is not None:
    print 'Current page number %s' % search_results.page
    search_results = search_results.get_next_page()

VideosPopular.get_previous_page()

Returns previous available popular photos page with the current query, page, and per_page parameters. Returns None if no page is available.

Returns

Object Instance of class VideosPopular or None

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
search_results = py_pexel.videos_popular(query='red flowers', page=3, per_page=40)
while search_results is not None:
    print 'Current page number %s' % search_results.page
    search_results = search_results.get_previous_page()

VideosPopular.get_first_page()

Returns first popular photos page with the current query, page, and per_page parameters. Returns None if no page is available.

Returns

Object Instance of class VideosPopular or None

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
search_results = py_pexel.videos_popular(query='red flowers', page=3, per_page=40)
print 'Current page number %s' % search_results.page
# To something with search_results

# Go back to first page
search_results = search_results.get_first_page():
print 'Current page number %s' % search_results.page

Note

VideosPopular.get_last_page() always returns the first page.

API: Class VideosSearch

This class is used to access the results of a search on the PyPexels /videos/search/ REST API.

It is returned as result from a call to PyPexels.videos_search(query, page, per_page)

Properties

Properties exposed by the VideosSearch class.

VideoSearch.entries

Returns an iterator for the returned objects contained in this VideosSearch instance. Each entry will be an instance of class Video.

iterator each time an instance of class Video

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
search_results = py_pexel.video_search(query='red flowers', per_page=40)
for video in search_results.entries:
    print(video.id, video.user.get('name'), video.url)

VideoSearch.page

Current search results page number.

int current search results page number

VideoSearch.per_page

Current search results per_page value.

int current search results per_page value

VideoSearch.total_results

Total results count, number of photos found

int total results count, number of photos found

VideoSearch.has_previous

Returns boolean True or False depending on whether the current results page has a previous page to navigate to or not.

boolean presence of previous page results

VideoSearch.has_next

Returns boolean True or False depending on whether the current results page has a next page to navigate to or not.

boolean presence of next page results

VideoSearch.body

Returns JSON body of search results page.

JSON JSON converted body of results page

VideoSearch.headers

Returns response headers of search results page.

dict headers of results page

Methods

Methods exposed by the VideosSearch class.

VideoSearch.get_page()

Returns the requested search results page with the current query and per_page parameters. The returned page may not contain entries if the page is out of boundaries.

Parameters

Argument Type Optional/Required Notes
page number required Page number to retrieve.

Returns

Object Instance of class VideosSearch

VideoSearch.get_next_page()

Returns next available search results page with the current query, page, and per_page parameters. Returns None if no page is available.

Returns

Object Instance of class VideosSearch or None

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
search_results = py_pexel.video_search(query='red flowers', per_page=40)
while search_results is not None:
    print 'Current page number %s' % search_results.page
    search_results = search_results.get_next_page()

VideoSearch.get_previous_page()

Returns previous available search results page with the current query, page, and per_page parameters. Returns None if no page is available.

Returns

Object Instance of class VideosSearch or None

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
search_results = py_pexel.video_search(query='red flowers', page=3, per_page=40)
while search_results is not None:
    print 'Current page number %s' % search_results.page
    search_results = search_results.get_previous_page()

VideoSearch.get_first_page()

Returns first search results page with the current query, page, and per_page parameters. Returns None if no page is available.

Returns

Object Instance of class VideosSearch or None

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
search_results = py_pexel.video_search(query='red flowers', page=3, per_page=40)
print 'Current page number %s' % search_results.page
# To something with search_results

# Go back to first page
search_results = search_results.get_first_page():
print 'Current page number %s' % search_results.page

VideoSearch.get_last_page()

Returns last search results page with the current query, page, and per_page parameters. Returns None if no page is available.

Returns

Object Instance of class VideosSearch or None

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
search_results = py_pexel.video_search(query='red flowers', per_page=40)

# Go to last results page
search_results = search_results.get_last_page():
print 'Current page number %s' % search_results.page

API: Class SingleVideo

This class is used to create an individual SingleVideo objects from its ID.

Properties

Properties exposed by the SingleVideo class.

‘entries’

SingleVideo.entries

Iterator for the returned objects contained in this SingleVideo instance. Each entry will be an instance of class Video.

Note You should not use this class directly. Use PyPexels.single_video() instead.

iterator each time an instance of class Video

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

#
#
video = py_pexel.single_video(video_id=<ID>)
print(video.id, video.user.get('name'), video.url)

API: Class Video

This class is used to interact with individual Video objects typically returned by PyPexels as part of either VideosSearch or VideosPopular object entries.

Properties

Properties exposed by the Video class.

‘id’, ‘width’, ‘height’, ‘url’, ‘image’, ‘full_res’, ‘tags’, ‘duration’, ‘user’, ‘video_files’, ‘video_pictures’.

Video.id

Unique identifier for this photo

int Unique identifier for this video

Video.width

Original video size width

int Original video size width

Video.height

Original video size height

int Original video size height

Video.url

URL location of Pexels web page for this video

str Pexels.com page for this video

Video.image

URL location of Pexels front image for this video

str Pexels.com front image for this video

Video.full_res

Full resolution

null Undocumented/unused

Video.tags

Tags (unused?)

list List of tags (str)

Video.duration

Duration of video in seconds

int Duration of video in seconds

Video.user

Information about the user uploading this video.

dict Information of user uploading the video

Video.video_files

List of videos generated from resampling/resizing the original. Each entry is a dict with keys (id, quality, file_type, width, height, link).

list List of resampled video files

Video.video_pictures

DEPRECATED

Methods

Methods exposed by the Video class.

‘get_attribution()’

Video.get_attribution(_format=’str’)

Generate and return a standard attribution string according to ‘_format’ parameter.

Parameters

Argument Type Optional/Required Notes
_format string optional Valid values: ‘txt’, ‘html’

Returns

string Text or HTML standard attribution string.

Example

import pypexels
py_pexel = pypexels.PyPexels(api_key='YOUR_API_KEY')

# Retrieve a single video, known by its ID
video = py_pexel.single_video(video_id=<ID>)
print(video.get_attribution('txt'))
print(video.get_attribution('html'))

Version

PyPexels v1.0.0rc1 (release candidate, v1)

This is the first release candidate for production ready 1.0.0 of PyPexels. Thanks to all the early adopters, there have been a number of improvements and bugfixes and now should be a good time to start the rc process.

This release introduces some good functionality, in particular:

  • Support for Videos API: search, popular
  • Introduction of SinglePhoto and SingleVideo * This allows instantiating a Photo or Video object using a photo_id or video_id
  • Introduction of get_attribution() method on Photo and Video classes * This simplifies crediting the author
  • Fix some documentation issues
  • Extend Travis and Tox test coverage to include Python 3.6, 3.7 and 3.8

Note that using this library you still need to abide to Pexels Guidelines, which are explained on Pexels API page

License

PyPexels is released under the MIT License.