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()
![dependabot[bot]](https://avatars.githubusercontent.com/u/49699333?size=120)
