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 toGET /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.
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
tolow
, 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
tohigh
(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:
GET /photos/curated
Use GET /photosGET /photos/search
Use GET /search/photosGET /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 parameterscurated_batches
endpoints (replaced by/collections/curated
)/photos/search
(replaced by/search/photos
)/photos/:id/stats
(replaced by/photos/:id/statistics
)