-
Unsplash Source being deprecated
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
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 bytags_preview
-
GET /collections/featured removal
Following up on its deprecation in September,
GET /collections/featured
has been removed. -
Query string added to photo download_location URL
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
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
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
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
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
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
The ‘likes’ data in the
/users/:username/statistics
response has been deprecated. Thetotal
value will be returning 0 going forward, with the entire fragment (i.e., includinghistorical
info) to be removed in the near future. -
Deprecation of ordering by 'popular'
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
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
andGET /random
.param Description content_filter
Limit results by content safety. (Optional; default: low
). Valid values arelow
andhigh
.Note: if you were previously using the experimental and undocumented
safe
boolean param, this has been deprecated and replaced by thecontent_filter
param.safe=true
corresponds tocontent_filter=high
andsafe=false
corresponds tocontent_filter=low
. We will be removing support forsafe
in a future update. -
New filtering and ordering options
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 arelatest
andrelevant
.color
Filter results by color. Valid values are: black_and_white
,black
,white
,yellow
,orange
,red
,purple
,magenta
,green
,teal
, andblue
.orientation
Filter search results by photo orientation. Valid values are landscape
,portrait
, andsquarish
.GET /collections/:id/photos adds support for orientation filtering:
param Description orientation
Filter collection results by photo orientation. Valid values are landscape
,portrait
, andsquarish
.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
, andsquarish
.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
, andsquarish
. -
Deprecated endpoint EOL: curated photos, old search, photo stats
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
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
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
For performance reasons we are removing some of the deeply-nested photo objects returned in the
search/users
andusers/: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
Categories endpoints have been removed.
-
Curated Collections deprecation
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
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 theuser
orcover_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
Categories endpoints won’t yet 404, but are returning empty data structures. e.g.,
/categories/:id/photos
=>[]
-
Instagram username now public
Both full and abbreviated user responses now include the
instagram_username
attribute without requiring theread_user
scope. -
Filter photo search results by orientation
The
/search
and/search/photos/
endpoints will now accept anorientation
parameter, and return photos only matching that. Valid values arelandscape
,portrait
, andsquarish
. -
Updated API Guidelines
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 →
- All API uses must use the hotlinked image URLs returned by the API under the
-
Existing deprecations
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
)
-
Reactor online. Initializing API changelog.
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