A library that provides a Python interface to the Unsplash API.
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.
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) Get the user’s profile.
api.user.me() 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) 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") Retrieve a single user’s portfolio link.
| param | Description | |
|---|---|---|
| username | Username | required |
api.user.portfolio("yakupa") 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") 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") 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") 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() 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() 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") 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() 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") 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") 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") 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") 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") 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") 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() 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() 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() 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") 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") 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") 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") Retrieve a list of collections related to this one.
| param | Description | |
|---|---|---|
| id | The collection’s ID. | required |
api.collection.related("547584") 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") 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") 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") 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") 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") Get a list of counts for all of Unsplash.
api.stat.total() Get the overall Unsplash stats for the past 30 days.
api.stat.month()