unsplash.py

Installation

Python 3.8 or higher is required.

To install the stable version, do the following:

# Unix / macOS
python3 -m pip install "unsplash.py"

# Windows
py -m pip install "unsplash.py"

To install the development version, do the following:

$ git clone https://github.com/Ombucha/unsplash.py

Make sure you have the latest version of Python installed, or if you prefer, a Python version of 3.8 or greater.

If you have have any other issues feel free to search for duplicates and then create a new issue on GitHub with as much detail as possible. Include the output in your terminal, your OS details and Python version.

Client

class unsplash.Client(access_key: str, secret_key: str | None = None)

A client for interacting with the Unsplash API.

Parameters:

  • access_key (str) – Your Unsplash API access key.

  • secret_key (Optional[str]) – Your Unsplash API secret key.

add_photo_to_collection(collection_id: str, photo_id: str) → UnsplashObject

Add a photo to a collection.

Note

This action requires the write_collections scope.

Parameters:

  • collection_id (str) – The ID of the collection to add the photo to.

  • photo_id (str) – The ID of the photo to add to the collection.

create_collection(title: str, description: str | None = None, private: bool | None = False) → UnsplashObject

Create a new collection.

Note

This action requires the write_collections scope.

Parameters:

  • title (str) – The title of the collection.

  • description (Optional[str]) – The description of the collection.

  • private (Optional[bool]) – Whether the collection is private.

delete_collection(collection_id: str) → None

Delete a collection.

Note

This action requires the write_collections scope.

Parameters:

collection_id (str) – The ID of the collection to delete.

get_collection(collection_id: str) → UnsplashObject

Get a collection by its ID.

Parameters:

collection_id (str) – The ID of the collection to retrieve.

get_collection_photos(collection_id: str, *, page: int | None = 1, per_page: int | None = 10, orientation: Literal['landscape', 'portrait', 'squarish'] | None = None) → List[UnsplashObject]

Get photos from a collection.

Parameters:

  • collection_id (str) – The ID of the collection to retrieve photos from.

  • page (Optional[int]) – The page number to retrieve.

  • per_page (Optional[int]) – The number of photos to retrieve per page. Must be between 1 and 30.

  • orientation (Optional[Literal["landscape", "portrait", "squarish"]]) – The orientation of the photos to retrieve.

get_current_user() → UnsplashObject

Get the current authenticated user.

Note

To access private user data, you must authenticate with the read_user scope.

get_monthly_stats() → UnsplashObject

Get the overall statistics for the Unsplash API for the past 30 days.

get_photo(photo_id: str) → UnsplashObject

Get a photo by its ID.

Parameters:

photo_id (str) – The ID of the photo to retrieve.

get_photo_statistics(photo_id: str, *, resolution: str | None = 'days', quantity: int | None = 30) → UnsplashObject

Get statistics for a photo.

Parameters:

  • photo_id (str) – The ID of the photo to retrieve statistics for.

  • resolution (Optional[str]) – The frequency of the statistics to retrieve.

  • quantity (Optional[int]) – The number of statistics to retrieve.

get_random_photo(*, collection_ids: List[str] | None = None, topic_ids: List[str] | None = None, username: str | None = None, query: str | None = None, orientation: Literal['landscape', 'portrait', 'squarish'] | None = None, content_filter: Literal['low', 'high'] | None = 'low', count: int | None = 1) → List[UnsplashObject]

Get a random photo or photos.

Parameters:

  • collection_ids (Optional[List[str]]) – A list of collection IDs to filter the random photo from.

  • topic_ids (Optional[List[str]]) – A list of topic IDs to filter the random photo from.

  • username (Optional[str]) – The username of the user to filter the random photo from.

  • query (Optional[str]) – A search query to filter the random photo.

  • orientation (Optional[Literal["landscape", "portrait", "squarish"]]) – The orientation of the random photo.

  • content_filter (Optional[Literal["low", "high"]]) – The content filter level for the random photo.

  • count (Optional[int]) – The number of random photos to retrieve. Must be between 1 and 30.

Get collections related to a specific collection.

Parameters:

collection_id (str) – The ID of the collection to retrieve related collections for.

get_topic(topic_id_or_slug: str) → UnsplashObject

Get a topic by its ID or slug.

Parameters:

topic_id_or_slug (str) – The ID or slug of the topic to retrieve.

get_topic_photos(topic_id_or_slug: str, *, page: int | None = 1, per_page: int | None = 10, order_by: Literal['latest', 'oldest', 'popular'] = 'latest', orientation: Literal['landscape', 'portrait', 'squarish'] | None = None) → List[UnsplashObject]

Get photos from a topic.

Parameters:

  • topic_id_or_slug (str) – The ID or slug of the topic to retrieve photos from.

  • page (Optional[int]) – The page number to retrieve.

  • per_page (Optional[int]) – The number of photos to retrieve per page. Must be between 1 and 30.

  • order_by (Literal["latest", "oldest", "popular"]) – The order in which to retrieve the photos.

  • orientation (Optional[Literal["landscape", "portrait", "squarish"]]) – The orientation of the photos to retrieve.

get_total_stats() → UnsplashObject

Get the total statistics for the Unsplash API.

get_user(username: str) → UnsplashObject

Get a user by their username.

Parameters:

username (str) – The username of the user to retrieve.

get_user_collections(username: str, *, page: int | None = 1, per_page: int | None = 10) → List[UnsplashObject]

Get a user’s collections.

Parameters:

  • username (str) – The username of the user whose collections to retrieve.

  • page (Optional[int]) – The page number to retrieve.

  • per_page (Optional[int]) – The number of collections to retrieve per page. Must be between 1 and 30.

get_user_likes(username: str, *, page: int | None = 1, per_page: int | None = 10, order_by: Literal['latest', 'oldest', 'popular'] = 'latest', orientation: Literal['landscape', 'portrait', 'squarish'] | None = None) → List[UnsplashObject]

Get a user’s liked photos.

Parameters:

  • username (str) – The username of the user whose liked photos to retrieve.

  • page (Optional[int]) – The page number to retrieve.

  • per_page (Optional[int]) – The number of photos to retrieve per page. Must be between 1 and 30.

  • order_by (Literal["latest", "oldest", "popular", "views", "downloads"]) – The order in which to retrieve the photos.

  • orientation (Optional[Literal["landscape", "portrait", "squarish"]]) – The orientation of the photos to retrieve.

get_user_photos(username: str, *, page: int | None = 1, per_page: int | None = 10, order_by: Literal['latest', 'oldest', 'popular', 'views', 'downloads'] = 'latest', stats: bool = False, resolution: str | None = 'days', quantity: int | None = 30, orientation: Literal['landscape', 'portrait', 'squarish'] | None = None) → List[UnsplashObject]

Get a user’s photos.

Parameters:

  • username (str) – The username of the user whose photos to retrieve.

  • page (Optional[int]) – The page number to retrieve.

  • per_page (Optional[int]) – The number of photos to retrieve per page. Must be between 1 and 30.

  • order_by (Literal["latest", "oldest", "popular", "views", "downloads"]) – The order in which to retrieve the photos.

  • stats (bool) – Whether to include photo statistics.

  • resolution (Optional[str]) – The frequency of the statistics to retrieve.

  • quantity (Optional[int]) – The number of statistics to retrieve.

  • orientation (Optional[Literal["landscape", "portrait", "squarish"]]) – The orientation of the photos to retrieve.

get_user_portfolio(username: str) → str

Get a user’s portfolio URL by their username.

Parameters:

username (str) – The username of the user whose portfolio to retrieve.

get_user_statistics(username: str, *, resolution: str | None = 'days', quantity: int | None = 30) → UnsplashObject

Get a user’s statistics.

Parameters:

  • username (str) – The username of the user whose statistics to retrieve.

  • resolution (Optional[str]) – The frequency of the statistics to retrieve.

  • quantity (Optional[int]) – The number of statistics to retrieve.

like_photo(photo_id: str) → UnsplashObject

Like a photo.

Note

This action requires the write_likes scope.

Parameters:

photo_id (str) – The ID of the photo to like.

list_collections(*, page: int | None = 1, per_page: int | None = 10) → List[UnsplashObject]

Get a single page from the list of all collections.

Parameters:

  • page (Optional[int]) – The page number to retrieve.

  • per_page (Optional[int]) – The number of collections to retrieve per page. Must be between 1 and 30.

list_photos(*, page: int | None = 1, per_page: int | None = 10) → List[UnsplashObject]

List photos on a single page from the Editorial feed.

Parameters:

  • page (Optional[int]) – The page number to retrieve.

  • per_page (Optional[int]) – The number of photos to retrieve per page. Must be between 1 and 30.

list_topics(*, page: int | None = 1, per_page: int | None = 10, order_by: Literal['featured', 'latest', 'oldest', 'position'] = 'position') → List[UnsplashObject]

List topics on a single page.

Parameters:

  • page (Optional[int]) – The page number to retrieve.

  • per_page (Optional[int]) – The number of topics to retrieve per page. Must be between 1 and 30.

  • order_by (Literal["featured", "latest", "oldest", "position"]) – The order in which to retrieve the topics.

remove_photo_from_collection(collection_id: str, photo_id: str) → UnsplashObject

Remove a photo from a collection.

Note

This action requires the write_collections scope.

Parameters:

  • collection_id (str) – The ID of the collection to remove the photo from.

  • photo_id (str) – The ID of the photo to remove from the collection.

search_collections(query: str, *, page: int | None = 1, per_page: int | None = 10) → List[UnsplashObject]

Search for collections.

Parameters:

  • query (str) – The search query.

  • page (Optional[int]) – The page number to retrieve.

  • per_page (Optional[int]) – The number of collections to retrieve per page. Must be between 1 and 30.

search_photos(query: str, *, page: int | None = 1, per_page: int | None = 10, order_by: Literal['latest', 'relevant'] = 'relevant', collection_ids: List[str] | None = None, content_filter: Literal['low', 'high'] | None = 'low', color: Literal['black_and_white', 'black', 'white', 'yellow', 'orange', 'red', 'purple', 'magenta', 'green', 'teal', 'blue'] | None = None, orientation: Literal['landscape', 'portrait', 'squarish'] | None = None, language: str | None = 'en') → List[UnsplashObject]

Search for photos.

Parameters:

  • query (str) – The search query.

  • page (Optional[int]) – The page number to retrieve.

  • per_page (Optional[int]) – The number of photos to retrieve per page. Must be between 1 and 30.

  • order_by (Literal["latest", "relevant"]) – The order in which to retrieve the photos.

  • collection_ids (Optional[List[str]]) – A list of collection IDs to filter the search results.

  • content_filter (Optional[Literal["low", "high"]]) – The content filter level for the search results.

  • color (Optional[Literal["black_and_white", "black", "white", "yellow", "orange", "red", "purple", "magenta", "green", "teal", "blue"]]) – The color filter for the search results.

  • orientation (Optional[Literal["landscape", "portrait", "squarish"]]) – The orientation of the photos to retrieve.

  • language (Optional[str]) – The ISO 639-1 language code for the search results (for access this beta parameter, email api@unsplash.com with your application ID)

search_users(query: str, *, page: int | None = 1, per_page: int | None = 10) → List[UnsplashObject]

Search for users.

Parameters:

  • query (str) – The search query.

  • page (Optional[int]) – The page number to retrieve.

  • per_page (Optional[int]) – The number of users to retrieve per page. Must be between 1 and 30.

trigger_photo_download(photo_id: str) → str

Trigger a download for a photo.

Note

This is purely an event endpoint used to increment the number of downloads a photo has. This endpoint is not to be used to embed the photo, it is for tracking purposes only.

Parameters:

photo_id (str) – The ID of the photo to trigger the download for.

unlike_photo(photo_id: str) → UnsplashObject

Unlike a photo.

Note

This action requires the write_likes scope.

Parameters:

photo_id (str) – The ID of the photo to unlike.

update_collection(collection_id: str, *, title: str | None = None, description: str | None = None, private: bool | None = None) → UnsplashObject

Update a collection’s metadata.

Note

This action requires the write_collections scope.

Parameters:

  • collection_id (str) – The ID of the collection to update.

  • title (Optional[str]) – The new title for the collection.

  • description (Optional[str]) – The new description for the collection.

  • private (Optional[bool]) – Whether the collection is private.

update_current_user(username: str | None = None, first_name: str | None = None, last_name: str | None = None, email: str | None = None, url: str | None = None, location: str | None = None, bio: str | None = None, instagram_username: str | None = None) → UnsplashObject

Update the current user’s profile information.

Note

This action requires the write_user scope.

update_photo(photo_id: str, *, description: str | None = None, show_on_profile: bool | None = None, tags: List[str] | None = None, latitude: float | None = None, longitude: float | None = None, location: str | None = None, city: str | None = None, country: str | None = None, make: str | None = None, model: str | None = None, exposure_time: str | None = None, aperture: str | None = None, focal_length: str | None = None, iso: int | None = None) → UnsplashObject

Update a photo’s metadata.

Note

This action requires the write_photos scope.

Parameters:

  • photo_id (str) – The ID of the photo to update.

  • description (Optional[str]) – The new description for the photo.

  • show_on_profile (Optional[bool]) – Whether to show the photo on the user’s profile.

  • tags (Optional[List[str]]) – A list of tags to associate with the photo.

  • latitude (Optional[float]) – The latitude of the photo’s location (rounded to 6 decimals).

  • longitude (Optional[float]) – The longitude of the photo’s location (rounded to 6 decimals).

  • location (Optional[str]) – The name of the location of the photo (including city and country).

  • city (Optional[str]) – The city where the photo was taken.

  • country (Optional[str]) – The country where the photo was taken.

  • make (Optional[str]) – The camera make used to take the photo.

  • model (Optional[str]) – The camera model used to take the photo.

  • exposure_time (Optional[str]) – The exposure time of the camera when the photo was taken.

  • aperture (Optional[str]) – The aperture value of the camera when the photo was taken.

  • focal_length (Optional[str]) – The focal length of the camera when the photo was taken.

  • iso (Optional[int]) – The ISO speed rating of the camera when the photo was taken.

Models

class unsplash.UnsplashObject(_data: dict)

A class that represents a custom object for the library.

Functions

unsplash.modify_image_url(url: str, *, width: float | None = None, height: float | None = None, file_format: str | None = None, auto_format: bool | None = None, quality: float | None = None, fit: str | None = None, crop: str | None = None, pixel_ratio: float | None = None) → str

Modify an Unsplash image URL with various parameters.

Parameters:

  • url (str) – The original Unsplash image URL.

  • width (Optional[float]) – Desired width of the image.

  • height (Optional[float]) – Desired height of the image.

  • file_format (Optional[str]) – Desired image format.

  • auto_format (Optional[bool]) – Whether to automatically select format.

  • quality (Optional[float]) – Desired image quality.

  • fit (Optional[str]) – Fit mode for the image.

  • crop (Optional[str]) – Crop mode for the image.

  • pixel_ratio (Optional[float]) – Pixel ratio for the image.

unsplash.get_all_pages(client: Client, function: Callable, *args, **kwargs)

Fetch all pages of results from a paginated API endpoint.

. note:

This function assumes that the API endpoint supports pagination.
Parameters:

  • client (unsplash.Client) – The Unsplash client instance.

  • function (Callable) – The function to call for fetching each page.

  • args – Positional arguments for the function.

  • kwargs – Keyword arguments for the function.

Returns:

A list of all results from all pages.