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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

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

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

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

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.

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 endpoints have been removed.

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.

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 endpoints won’t yet 404, but are returning empty data structures. e.g., /categories/:id/photos => []

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

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.

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 →

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)

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