Documentation › Changelog

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.

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:

ISO 639-1 Language Code Language
af Afrikaans
am Amharic
ar Arabic
az Azerbaijani
be Belarusian
bg Bulgarian
bn Bengali
bs Bosnian
ca Catalan
ceb Cebuano
co Corsican
cs Czech
cy Welsh
da Danish
de German
el Greek
en English
eo Esperanto
es Spanish
et Estonian
eu Basque
fa Persian
fi Finnish
fr French
fy Frisian
ga Irish
gd Scots Gaelic
gl Galician
gu Gujarati
ha Hausa
haw Hawaiian
hi Hindi
hmn Hmong
hr Croatian
ht Haitian Creole
hu Hungarian
hy Armenian
id Indonesian
ig Igbo
is Icelandic
it Italian
iw Hebrew
ja Japanese
jw Javanese
ka Georgian
kk Kazakh
km Khmer
kn Kannada
ko Korean
ku Kurdish
ky Kyrgyz
la Latin
lb Luxembourgish
lo Lao
lt Lithuanian
lv Latvian
mg Malagasy
mi Maori
mk Macedonian
ml Malayalam
mn Mongolian
mr Marathi
ms Malay
mt Maltese
my Myanmar
ne Nepali
nl Dutch
no Norwegian
ny Nyanja
or Oriya
pa Punjabi
pl Polish
ps Pashto
pt Portuguese
ro Romanian
ru Russian
rw Kinyarwanda
sd Sindhi
si Sinhala
sk Slovak
sl Slovenian
sm Samoan
sn Shona
so Somali
sq Albanian
sr Serbian
st Sesotho
su Sundanese
sv Swedish
sw Swahili
ta Tamil
te Telugu
tg Tajik
th Thai
tk Turkmen
tl Filipino
tr Turkish
tt Tatar
ug Uighur
uk Ukrainian
ur Urdu
uz Uzbek
vi Vietnamese
xh Xhosa
yi Yiddish
yo Yoruba
zh Chinese Simplified
zh-TW Chinese Traditional
zu Zulu

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.

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.

param Description
content_filter Limit results by content safety. (Optional; default: low). Valid values are low and high.

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:

param Description
order_by How to sort the photos. (Optional; default: relevant). Valid values are latest and relevant.
color Filter results by color. Valid values are: black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, and blue.
orientation Filter search results by photo orientation. Valid values are landscape, portrait, and squarish.

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

param Description
orientation Filter collection results by photo orientation. Valid values are landscape, portrait, and squarish.

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

param Description
orientation Filter a user’s photo results by photo orientation. Valid values are landscape, portrait, and squarish.

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

param Description
orientation Filter a user’s likes by photo orientation. Valid values are landscape, portrait, and squarish.

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

October 22, 2019

Three deprecated endpoints have been removed:

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: