python-unsplash
A library that provides a Python interface to the Unsplash API.
Installation
The easiest way to install the latest version is by using pip/easy_install to pull it from PyPI:
pip install python-unsplash
You may also use Git to clone the repository from Github and install it manually:
git clone https://github.com/yakupadakli/python-unsplash.git
cd python-unsplash
python setup.py install
Python 2.7, 3.7, 3.8, 3.9 and 3.11 is supported for now.
Usage
Code is required for authenticated actions
from unsplash.api import Api
from unsplash.auth import Auth
client_id = ""
client_secret = ""
redirect_uri = ""
code = ""
auth = Auth(client_id, client_secret, redirect_uri, code=code)
api = Api(auth)
User
User me
Require authentication.
Get the user’s profile.
api.user.me()
User update
Require authentication.
Update the current user’s profile
param | Description | |
---|---|---|
username | Username | optional |
first_name | First name. | optional |
last_name | Last name. | optional |
Email. | optional | |
url | Portfolio/personal URL. | optional |
bio | About/bio. | optional |
instagram_username | First | optional |
first_name | First | optional |
first_name | Instagram username. | optional |
kwargs = {"first_name": "Yakup"}
api.user.update(**kwargs)
User get
Retrieve public details on a given user.
param | Description | |
---|---|---|
username | Username | required |
w | Profile image width in pixels. | optional |
h | Profile image height in pixels. | optional |
api.user.get("yakupa")
User portfolio
Retrieve a single user’s portfolio link.
param | Description | |
---|---|---|
username | Username | required |
api.user.portfolio("yakupa")
User photos
Get a list of photos uploaded by a user.
param | Description | |
---|---|---|
username | Username | required |
page | Page number to retrieve. (default: 1) | optional |
per_page | Number of items per page. (default: 10) | optional |
order_by | How to sort the photos. Optional. (Valid values: latest, oldest, popular; default: latest) | optional |
stats | Show the stats for each user’s photo. (default: false) | optional |
resolution | The frequency of the stats. (default: “days”) | optional |
quantity | The amount of for each stat. (default: 30) | optional |
api.user.portfolio("yakupa")
User likes
Get a list of photos liked by a user.
param | Description | |
---|---|---|
username | Username | required |
page | Page number to retrieve. (default: 1) | optional |
per_page | Number of items per page. (default: 10) | optional |
order_by | How to sort the photos. Optional. (Valid values: latest, oldest, popular; default: latest) | optional |
api.user.likes("yakupa")
User collections
Get a list of collections created by the user.
param | Description | |
---|---|---|
username | Username | required |
page | Page number to retrieve. (default: 1) | optional |
per_page | Number of items per page. (default: 10) | optional |
api.user.collections("yakupa")
Photo
Photo all
Get a single page from the list of all photos.
param | Description | |
---|---|---|
page | Page number to retrieve. (default: 1) | optional |
per_page | Number of items per page. (default: 10) | optional |
order_by | How to sort the photos. Optional. (Valid values: latest, oldest, popular; default: latest) | optional |
api.photo.all()
Photo curated
Get a single page from the list of the curated photos.
param | Description | |
---|---|---|
page | Page number to retrieve. (default: 1) | optional |
per_page | Number of items per page. (default: 10) | optional |
order_by | How to sort the photos. Optional. (Valid values: latest, oldest, popular; default: latest) | optional |
api.photo.curated()
Photo get
Get a single page from the list of the curated photos.
param | Description | |
---|---|---|
id | The photo’s ID. | required |
w | Image width in pixels. | optional |
h | Image height in pixels. | optional |
rect | 4 comma-separated integers representing x, y, width, height of the cropped rectangle. | optional |
api.photo.get("Dwu85P9SOIk")
Photo random
Retrieve a single random photo, given optional filters.
Note: You can’t use the collections and query parameters in the same request
Note: When supplying a count parameter - and only then - the response will be an array of photos, even if the value of count is 1.
param | Description | |
---|---|---|
collections | Public collection ID(‘s) to filter selection. If multiple, comma-separated | optional |
featured | Limit selection to featured photos. | optional |
username | Limit selection to a single user. | optional |
query | Limit selection to photos matching a search term. | optional |
w | Image width in pixels. | optional |
h | Image height in pixels. | optional |
orientation | Filter search results by photo orientation. Valid values are landscape, portrait, and squarish. | optional |
count | The number of photos to return. (Default: 1; max: 30) | optional |
api.photo.random()
Photo stats
Retrieve total number of downloads, views and likes of a single photo, as well as the historical breakdown of these stats in a specific timeframe (default is 30 days).
param | Description | |
---|---|---|
id | The public id of the photo. | required |
resolution | The frequency of the stats. | optional |
quantity | The amount of for each stat. | optional |
api.photo.stats("LF8gK8-HGSg")
Photo like
Like a photo on behalf of the logged-in user. This requires the write_likes scope.
Note: This action is idempotent; sending the POST request to a single photo multiple times has no additional effect.
param | Description | |
---|---|---|
id | The photo’s ID. | required |
api.photo.like("LF8gK8-HGSg")
Photo unlike
Remove a user’s like of a photo.
Note: This action is idempotent; sending the DELETE request to a single photo multiple times has no additional effect.
param | Description | |
---|---|---|
id | The photo’s ID. | required |
api.photo.unlike("LF8gK8-HGSg")
Search
Search photos
Get a single page of photo results for a query.
param | Description | |
---|---|---|
query | Search terms. | required |
page | Page number to retrieve. | optional |
per_page | Number of items per page. | optional |
collections | Collection ID(‘s) to narrow search. If multiple, comma-separated. | optional |
api.search.photos("office")
Search collections
Get a single page of collection results for a query.
param | Description | |
---|---|---|
query | Search terms. | required |
page | Page number to retrieve. | optional |
per_page | Number of items per page. | optional |
api.search.collections("office")
Search users
Get a single page of user results for a query.
param | Description | |
---|---|---|
query | Search terms. | required |
page | Page number to retrieve. | optional |
per_page | Number of items per page. | optional |
api.search.users("yakupa")
Collections
Collections all
Get a single page from the list of all collections.
param | Description | |
---|---|---|
page | Page number to retrieve. | optional |
per_page | Number of items per page. | optional |
api.collection.all()
Collections featured
Get a single page from the list of featured collections.
param | Description | |
---|---|---|
page | Page number to retrieve. | optional |
per_page | Number of items per page. | optional |
api.collection.featured()
Collections curated
Get a single page from the list of curated collections.
param | Description | |
---|---|---|
page | Page number to retrieve. | optional |
per_page | Number of items per page. | optional |
api.collection.curated()
Collections get
Retrieve a single collection. To view a user’s private collections, the read_collections scope is required.
param | Description | |
---|---|---|
id | The collections’s ID. | required |
api.collection.get("547584")
Collections get curated
Retrieve a single curated collection. To view a user’s private collections, the read_collections scope is required.
param | Description | |
---|---|---|
id | The curated collections’s ID. | required |
api.collection.get_curated("547584")
Collections photos
Retrieve a collection’s photos.
param | Description | |
---|---|---|
id | The collections’s ID. | required |
page | Page number to retrieve. | optional |
per_page | Number of items per page. | optional |
api.collection.photos("547584")
Collections curated photos
Retrieve a curated collection’s photos.
param | Description | |
---|---|---|
id | The curated collections’s ID. | required |
page | Page number to retrieve. | optional |
per_page | Number of items per page. | optional |
api.collection.curated_photos("547584")
Collections related
Retrieve a list of collections related to this one.
param | Description | |
---|---|---|
id | The collection’s ID. | required |
api.collection.related("547584")
Collections create
Create a new collection. This requires the write_collections scope.
param | Description | |
---|---|---|
title | The title of the collection. | required |
description | The collection’s description. | optional |
private | Whether to make this collection private. | optional |
api.collection.create("New Test Collection")
Collections update
Update an existing collection belonging to the logged-in user. This requires the write_collections scope.
param | Description | |
---|---|---|
id | The collection’s ID. | required |
title | The title of the collection. | optional |
description | The collection’s description. | optional |
private | Whether to make this collection private. | optional |
api.collection.update("547584")
Collections delete
Delete a collection belonging to the logged-in user. This requires the write_collections scope.
param | Description | |
---|---|---|
id | The collection’s ID. | required |
api.collection.delete("547584")
Collections add photo
Add a photo to one of the logged-in user’s collections. Requires the write_collections scope.
param | Description | |
---|---|---|
collection_id | The collection’s ID. | required |
photo_id | The photo’s ID. | required |
api.collection.add_photo("547584", "KSap1iDftvQ")
Collections remove photo
Remove a photo from one of the logged-in user’s collections. Requires the write_collections scope.
param | Description | |
---|---|---|
collection_id | The collection’s ID. | required |
photo_id | The photo’s ID. | required |
api.collection.remove_photo("547584", "KSap1iDftvQ")
Stats
Stats total
Get a list of counts for all of Unsplash.
api.stat.total()
Stats total
Get the overall Unsplash stats for the past 30 days.
api.stat.month()