Pexels Ruby Library

The Pexels Ruby library is a convenient wrapper around the Pexels API that you can use to browse the incredible content uploaded by our talented contributors.


gem install pexels

Or add it to your Gemfile and run bundle install.


See the API docs here

Basic usage

Create a client

# If you don't specify one, the environment variable PEXELS_API_KEY is used by default
client ='your-access-key')

Search for photos'Cloud')

Search for photos with filters'Dog', color: :yellow, size: :large, orientation: :square)

Find a specific photo[2014422]
# or

Browse curated photos

Search for videos'waves')

Search for videos with filters'Beach', size: :medium, orientation: :landscape)

Find a specific photo

# or

List all collections

Note: this is limited to collections belonging to the API user.


Get all media for a collection

# or

You can also filter for only photos or videos.

client.collections['collection-id', type: 'photos'].media
client.collections['collection-id', type: 'videos'].media

Rate Limiting

After performing a request, you can access your remaining rate limit via the client.



Requests that return multiple objects are paginated. You can pass in page and per_page options to these requests to get a specific page. You can also access the total number of results by accessing total_results on the response.

Note: The Pexels API returns a maximum of 80 records for one request.

response ='dog', page: 2, per_page: 50)
response.total_results #=> 1000
response.total_pages #= 20

If there are further pages, you can also paginate through the API client:

response ='dog', page: 2, per_page: 50)
response.prev_page # queries page 1
response.next_page # queries page 3

Running the test suite

You'll need your own API key to run the test suite, you can get one on the Pexels API Key management page

For ease of use, you'll probably want to copy the provided .env.sample into your own .env file and substitute the PEXELS_API_KEY variable with your own.

cp .env.sample .env
vim .env              #=> Change PEXELS_API_KEY
source .env           #=> Load the environment

make test