API Changelog

Removal of order_by from GET /photos

September 19, 2024

The photos Editorial feed will no longer support the order_by parameter, instead only returning photos in the latest order (the existing default).

Unsplash Source sunset

June 11, 2024

Unsplash Source has been officially unsupported since its deprecation in 2021. As part of the final sunsetting, we will first wind down by disabling the search feature, and in the coming weeks turn off the application entirely.

Existing uses of Source - particularly production-level ones - should migrate as soon as possible to the full Unsplash API.

Unsplash Source being deprecated

November 25, 2021

Unsplash Source is being deprecated. Existing uses will continue to work, however for new projects use the full Unsplash API.

Tags property from search endpoints deprecation

July 12, 2021

The tags property from the /search and /search/photos endpoint is deprecated and will eventually be removed.
This was an undocumented field and is superseded by tags_preview

GET /collections/featured removal

April 30, 2021

Following up on its deprecation in September, GET /collections/featured has been removed.

Query string added to photo download_location URL

March 09, 2021

Query string parameters have been added to the photo’s download_location URL. This may cause issues for client implementations adding their access token to the URL via string concatenation.

BlurHash added to photo objects

September 28, 2020

All photo objects from the Unsplash API now include a blur_hash string.
This is a compact representation of an image which can be used as a placeholder before the real image loads.

For more information on BlurHash and how to use it on your application, check its official page.

Added topic endpoints

September 23, 2020

We have added new endpoints for topics:

• GET /topics to obtain a list of all the topics.
• GET /topics/:id_or_slug to retrieve a single topic details.
• GET /topic/:id_or_slug/photos to retrieve a topic’s photos.

For more information on these endpoints and their available params, see the API documentation on topics.

Collections ID change and featured deprecation

September 18, 2020

Two changes to the Collections API:

• IDs returned are currently integers, but will be changing to alphanumeric strings.

• GET /collections/featured has been deprecated. Clients should switch to GET /collections; these endpoints already return identical results.

Support for languages beta

August 21, 2020

We are adding support for non-english input languages to the search endpoint.

It is currently in beta, so access is restricted to certain API applications. To access the beta, email api@unsplash.com with your application ID.

Currently we are adding support for 108 languages:

For more information, see the API documentation.

Dynamic Client Registration Support Added

July 31, 2020

For decentralized applications, like open source CMSs WordPress and Ghost, we’ve added support for dynamic client registration, which allows developers to grant individual API keys to users with a user-friendly signup process.

This or the use of a proxy is required for applications where a single API key can’t be shared between all installations due to the code being publicly distributed.

Since this is not a typical use case, please reach out to the Unsplash Team to let us know about your use case and we will enable the ability for your application.

For more information, see the API documentation on dynamic client registration.

User likes statistics deprecation

July 28, 2020

The ‘likes’ data in the /users/:username/statistics response has been deprecated. The total value will be returning 0 going forward, with the entire fragment (i.e., including historical info) to be removed in the near future.

Deprecation of ordering by ‘popular’

July 09, 2020

We are deprecating the option to order photos by popular on all endpoints (e.g., GET /photos). While the functionality will still exist in the immediate future, it will be soon be removed.

Content filtering

March 15, 2020

We’ve added a new section to the API documentation to publicly clarify our content safety guidelines:

By default, endpoints set the content_filter to low, which guarantees that no content violating our submission guidelines (like images containing nudity or violence) will be returned in results.

To give you flexibility in filtering content further, set the content_filter to high (on endpoints that support it) to further remove content that may be unsuitable for younger audiences. Note that we can’t guarantee that all potentially unsuitable content is removed.

We’ve added support for content filtering to GET /search/photos and GET /random.

Note: if you were previously using the experimental and undocumented safe boolean param, this has been deprecated and replaced by the content_filter param. safe=true corresponds to content_filter=high and safe=false corresponds to content_filter=low. We will be removing support for safe in a future update.

New filtering and ordering options

March 04, 2020

GET /search/photos adds support for orientation, dominant color filtering, and relevancy vs latest ordering:

GET /collections/:id/photos adds support for orientation filtering:

GET /users/:username/photos adds support for orientation filtering:

GET /users/:username/likes adds support for orientation filtering:

Deprecated endpoint EOL: curated photos, old search, photo stats

October 22, 2019

Three deprecated endpoints have been removed:

• GET /photos/curated Use GET /photos
• GET /photos/search Use GET /search/photos
• GET /photos/:id/stats Use GET /photos/:id/statistics

Curated Collections removal

September 23, 2019

The deprecated Curated Collection endpoints have been removed. This includes:

• GET /collections/curated
• GET /collections/curated/:id
• GET /collections/curated/:id/photos

API parameter resizing deprecation

March 18, 2019

The custom cropping and resizing parameters accepted by the get a photo, get a random photo, and get a user endpoints are being deprecated and replaced instead with dynamic image URLs which are capable of more resizing and cropping options.

The photo.url.custom attribute is also being deprecated, as it is no longer needed.

Abbreviation of top photos in users search and user endpoints

November 16, 2018

For performance reasons we are removing some of the deeply-nested photo objects returned in the search/users and users/:username endpoints.

Previously, the user object contained an array of the top 3 photos, which included a full photo response for each photo:

{
  "id": "s6-TQxOxDSA",
  "created_at": "2016-01-27T07:55:40-05:00",
  "width": 2448,
  "height": 2448,
  "color": "#E8F4F9",
  "likes": 0,
  "liked_by_user": false,
  "description": "A man drinking a coffee.",
  "current_user_collections": [],
  "urls": {
      "raw": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8",
      "full": "https://hd.unsplash.com/photo-1453899242646-c74d86b5b8e8",
      "regular": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max&s=05993ddfa31268c29b2e7e253d9b112b",
      "small": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=400&fit=max&s=2d0bd4cef8c2955243273764ca953dcf",
      "thumb": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=200&fit=max&s=a1d5d225a733ed19574b97b701d9e20f"
    },
  "links": {
    "self": "https://api.unsplash.com/photos/s6-TQxOxDSA",
    "html": "http://unsplash.com/photos/s6-TQxOxDSA",
    "download": "http://unsplash.com/photos/s6-TQxOxDSA/download"
  }
}

Going forward, the new shape of these top 3 photos will be abbreviated to:

{
  "id": "s6-TQxOxDSA",
  "urls": {
    "raw": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8",
    "full": "https://hd.unsplash.com/photo-1453899242646-c74d86b5b8e8",
    "regular": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max&s=05993ddfa31268c29b2e7e253d9b112b",
    "small": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=400&fit=max&s=2d0bd4cef8c2955243273764ca953dcf",
    "thumb": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=200&fit=max&s=a1d5d225a733ed19574b97b701d9e20f"
  }
}

To get a list of full photo objects for a user, instead hit the users/:username/photos endpoint.

Categories removal

September 28, 2018

Categories endpoints have been removed.

Curated Collections deprecation

September 27, 2018

Curated Collections are now deprecated. This includes endpoints:

• GET /collections/curated
• GET /collections/curated/:id
• GET /collections/curated/:id/photos
• GET /photos/curated

Existing curated collections will continue to be returned from these endpoints, but no new data will be added. They are now also included in the regular /collections endpoints.

Abbreviation of current_user_collections

June 18, 2018

For performance reasons we are removing some of the deeply-nested objects returned in the current_user_collections photo attribute. current_user_collections returns a list of collection objects, which will no longer include the user or cover_photo information.

This change only affects requests made by logged-in users. Logged-out requests (i.e., those made with Client-ID authorization) will see no change.

Categories EOL

April 20, 2018

Categories endpoints won’t yet 404, but are returning empty data structures. e.g., /categories/:id/photos => []

Instagram username now public

February 26, 2018

Both full and abbreviated user responses now include the instagram_username attribute without requiring the read_user scope.

Filter photo search results by orientation

January 03, 2018

The /search and /search/photos/ endpoints will now accept an orientation parameter, and return photos only matching that. Valid values are landscape, portrait, and squarish.

Updated API Guidelines

December 06, 2017

We’ve updated the official Unsplash API Guidelines to include two new technical guidelines for all API applications:

• All API uses must use the hotlinked image URLs returned by the API under the photo.urls properties. More info & examples →
• When your application performs something similar to a download (like when a user chooses the image to include in a blog post, set as a wallpaper, etc.), you must send a request to the download endpoint returned under the photo.links.download_location property. More info & examples →

View more about the API Guidelines →

Reactor online. Initializing API changelog.

October 05, 2017

We’ll be posting changes to the API starting from here. You can always find the current state of our API at https://unsplash.com/documentation

Existing deprecations

October 05, 2017

Some endpoints and behaviour have already been deprecated, and are no longer officially supported:

• categories endpoints and related parameters
• curated_batches endpoints (replaced by /collections/curated)
• /photos/search (replaced by /search/photos)
• /photos/:id/stats (replaced by /photos/:id/statistics)