aguilarlagunasarturo/pexels-api

Using Pexels API v1 with Python

Using Pexels API v1 with Python

Use pexels_api to search photos from Pexels.

Dependencies:

• requests

Installation:

pip install pexels-api

Usage:

The following code shows you how to import the package and make a simple query to Pexels API v1. See more examples or the documentation.

# Import API class from pexels_api package
from pexels_api import API
# Type your Pexels API
PEXELS_API_KEY = 'YOUR-PEXELS-API-KEY'
# Create API object
api = API(PEXELS_API_KEY)
# Search five 'kitten' photos
api.search('kitten', page=1, results_per_page=5)
# Get photo entries
photos = api.get_entries()
# Loop the five photos
for photo in photos:
  # Print photographer
  print('Photographer: ', photo.photographer)
  # Print url
  print('Photo url: ', photo.url)
  # Print original size url
  print('Photo original size: ', photo.original)

Examples:

• search.py:
  Specify a query to search photos.
• popular.py:
  Search popular photos.
• curated.py:
  Search curated photos.

Documentation:

• Class: API
  • Methods
  • Properties
• Class: Photo
  • Properties

Class: API

API(PEXELS_API_KEY)

Creates an instance of a API object.

Parameter	Required	Type	Description
PEXELS_API_KEY	Yes	String	Your Pexels API key

Returns:

An instance of a API object.

Methods:

search(query, photos_per_page=15, page=1)

Given a query requests data using Pexels API v1.

Parameter	Required	Type	Description
query	Yes	String	The topic to search
photos_per_page	No. (Default value: 15)	Integer	Number of photos per page 1 minimum 80 maximum
page	No. (Default value: 1)	Integer	Specify the page to search

Returns:

A dictionary containing json data of the results of the query in the specified page, None if the request fails.

popular(photos_per_page=15, page=1)

Requests popular data using Pexels API v1.

Parameter	Required	Type	Description
photos_per_page	No. (Default value: 15)	Integer	Number of photos per page 1 minimum 80 maximum
page	No. (Default value: 1)	Integer	Specify the page to search

Returns:

A dictionary containing json data of the results of Pexels popular page in the specified page, None if the request fails.

curated(photos_per_page=15, page=1)

Requests curated data using Pexels API v1.

Parameter	Required	Type	Description
photos_per_page	No. (Default value: 15)	Integer	Number of photos per page 1 minimum 80 maximum
page	No. (Default value: 1)	Integer	Specify the page to search

Returns:

A dictionary containing json data of the results of Pexels curated page in the specified page, None if the request fails.

search_next_page()

Search the next page if available.

Returns:

A dictionary containing json data of the next page, None if page not found.

search_previous_page()

Search the previous page if available.

Returns:

A dictionary containing json data of the previous page, None if page not found.

get_entries()

Creates an instance of a Photo object for each photo in the current page.

Returns:

A list of Photo objects.

Properties:

By default the API properties are None. When seacrh(), popular() or curated() is performed the API properties are updated.

Property	Type	Description
request	Object (requests)	Current request, None if request fails
json	Dictionary	A dictionary with the data of the current page
page	Integer	Number of the page
total_results	Integer	Number of total results. (None in popular and curated page)
page_results	Integer	Number of results in the current page
has_next_page	Boolean	True if there is a next page else False
has_previous_page	Boolean	True if there is a previous page else False
next_page	String	Url to the next page. (None if there is no next page)
prev_page	String	Url to the previous page. (None if there is no previous page)

Class: Photo

Photo(json_photo)

Parameter	Required	Type	Description
json_photo	Yes	Dictionary	A dictionary containing json data of the photo of which you want the properties

Returns:

An instance of a Photo object.

Properties:

Property	Type	Description
id	Integer	Unique Pexels identifier
width	Integer	Width of the original photo
height	Integer	Height of the original photo
photographer	String	Photo's photographer
url	String	Photo's photographer
description	String	Photo's description
original	String	Photo's original size url
compressed	String	Photo's compressed size url
large2x	String	Photo's large2x size url
large	String	Photo's large size url
medium	String	Photo's medium size url
small	String	Photo's small size url
portrait	String	Photo's portrait size url
landscape	String	Photo's landscape size url
tiny	String	Photo's tiny size url
extension	String	Photo's extension

pexels-api's Issues

Video support

GET https://api.pexels.com/videos/search

Mismatch between search() function parameters in example and in documentation

Hi Aguillar,

In the code example for searching for photos, the code is:

api.search(query, page=, results_per_page=)

but under the Methods header in the documentation, the code for the same function is:
search(query, photos_per_page=, page=

Are these separate functions or is there perhaps a mismatch in the order of the parameters
between the code example and the documentation?

Support of "orientation" tag on search

orientation

search query contains a white space

I found that a video search query contains a white space, such as 'dancing couple', cause issue.
The api search result is different than manually search from pexels website.

I've tried 'dancing+couple' and 'dancing%20couple', but still can not align the search results.

Maybe I miss something, so hope to hear your expertise on the issue.

Thanks.

extend to video

Dear AguilarLagunasArturo,

It's great to find your pexels api in python. So far it works nice with getting photos from pexels.
We were wondering if you have a plan to extend the api to include searching and download video.

Thanks!