A Universal JavaScript wrapper for the Unsplash API .
Before using the Unsplash API, you need to register as a developer and read the API Guidelines .
Latest ✔
Latest ✔
Latest ✔
Latest ✔
Latest ✔
10+ ✔
Quick links to methods you're likely to care about:
Note: Every application must abide by the API Guidelines . Specifically, remember to hotlink images and trigger a download when appropriate .
$ npm i --save unsplash-js
This library depends on fetch to make requests to the Unsplash API. For environments that don't support fetch, you'll need to provide a poly fill .
To create an instance, simply provide an Object with your applicationId
, secret
and callbackUrl
.
// ES Modules syntax
import Unsplash from 'unsplash-js' ;
// require syntax
const Unsplash = require ( 'unsplash-js' ) . default ;
const unsplash = new Unsplash ( {
applicationId : "{APP_ACCESS_KEY}" ,
secret : "{APP_SECRET}" ,
callbackUrl : "{CALLBACK_URL}"
} ) ;
If you already have a bearer token, you can also provide it to the constructor.
const unsplash = new Unsplash ( {
applicationId : "{APP_ACCESS_KEY}" ,
secret : "{APP_SECRET}" ,
callbackUrl : "{CALLBACK_URL}" ,
bearerToken : "{USER_BEARER_TOKEN}"
} ) ;
You can also provide headers that will be set on every request by providing them to the constructor.
const unsplash = new Unsplash ( {
applicationId : "{APP_ACCESS_KEY}" ,
secret : "{APP_SECRET}" ,
callbackUrl : "{CALLBACK_URL}" ,
headers : {
"X-Custom-Header" : "foo"
}
} ) ;
Credentials can be obtained from Unsplash Developers .
For use with React Native, import from unsplash-js/native
instead.
import Unsplash from 'unsplash-js/native' ;
Generate an authentication url with the scopes your app requires.
const authenticationUrl = unsplash . auth . getAuthenticationUrl ( [
"public" ,
"read_user" ,
"write_user" ,
"read_photos" ,
"write_photos"
] ) ;
Now that you have an authentication url, you'll want to redirect the user to it.
location . assign ( authenticationUrl ) ;
After the user authorizes your app she'll be redirected to your callback url with a code
querystring present. Request an access token using that code.
// The OAuth code will be passed to your callback url as a querystring
unsplash . auth . userAuthentication ( query . code )
. then ( toJson )
. then ( json => {
unsplash . auth . setBearerToken ( json . access_token ) ;
} ) ;
For more information on the authroization workflow, consult the Unsplash Documentation .
unsplash . users . profile ( "naoufal" )
. catch ( err => {
// Your flawless error handling code
} ) ;
All the instance methods below make use of the toJson
helper method described below
auth.getAuthenticationUrl(scopes)
Build an OAuth url with requested scopes.
Arguments
Argument
Type
Opt/Required
Default
scopes
Array
Optional
["public"]
Example
const authenticationUrl = unsplash . auth . getAuthenticationUrl ( [
"public" ,
"read_user" ,
"write_user" ,
"read_photos" ,
"write_photos"
] ) ;
auth.userAuthentication(code)
Retrieve a user's access token.
Arguments
Argument
Type
Opt/Required
code
string
Required
Example
unsplash . auth . userAuthentication ( "{OAUTH_CODE}" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
auth.setBearerToken(accessToken)
Set a bearer token on the instance.
Arguments
Argument
Type
Opt/Required
accessToken
string
Required
Example
unsplash . auth . setBearerToken ( "{BEARER_TOKEN}" ) ;
Get the user’s profile.
Arguments
N/A
Example
unsplash . currentUser . profile ( )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
currentUser.updateProfile(options)
Update the current user’s profile.
Arguments
Argument
Type
Opt/Required
Notes
options
Object
Required
Object with the following optional keys: username
, firstName
, lastName
, email
, url
, location
, bio
, instagramUsername
Example
unsplash . currentUser . updateProfile ( {
username : "drizzy" ,
firstName : "Aubrey" ,
lastName : "Graham" ,
email : "drizzy@octobersveryown.com" ,
url : "http://octobersveryown.com" ,
location : "Toronto, Ontario, Canada" ,
bio : "Views from the 6" ,
instagramUsername : "champagnepapi"
} )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
Retrieve public details on a given user.
Arguments
Argument
Type
Opt/Required
username
string
Required
Example
unsplash . users . profile ( "naoufal" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
users.statistics(username, resolution, quantity)
Retrieve statistics for a given user.
Arguments
Argument
Type
Opt/Required
Notes
Default
username
string
Required
resolution
string
Optional
Currently only days
days
quantity
string
Optional
30
Example
unsplash . users . statistics ( "naoufal" , "days" , 30 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
users.photos(username, page, perPage, orderBy, stats)
Get a list of photos uploaded by a user.
Arguments
Argument
Type
Opt/Required
Notes
Default
username
string
Required
page
number
Optional
1
perPage
number
Optional
10
orderBy
string
Optional
latest
, popular
or oldest
latest
stats
boolean
Optional
false
Example
unsplash . users . photos ( "naoufal" , 1 , 10 , "popular" , false )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
users.likes(username, page, perPage, orderBy)
Get a list of photos liked by a user.
Arguments
Argument
Type
Opt/Required
Notes
username
string
Required
page
number
Optional
perPage
number
Optional
orderBy
string
Optional
latest
, popular
or oldest
Example
unsplash . users . likes ( "naoufal" , 2 , 15 , "popular" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
users.collections(username, page, perPage, orderBy)
Get a list of collections created by the user.
Arguments
Argument
Type
Opt/Required
Notes
username
string
Required
page
number
Optional
perPage
number
Optional
orderBy
string
Optional
published
or updated
Example
unsplash . users . collections ( "naoufal" , 2 , 15 , "updated" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
photos.listPhotos(page, perPage, orderBy)
Get a single page from the list of all photos.
Arguments
Argument
Type
Opt/Required
page
number
Optional
perPage
number
Optional
orderBy
string
Optional
Example
unsplash . photos . listPhotos ( 2 , 15 , "latest" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
photos.listCuratedPhotos(page, perPage, orderBy)
Get a single page from the list of the curated photos.
Arguments
Argument
Type
Opt/Required
page
number
Optional
perPage
number
Optional
orderBy
string
Optional
Example
unsplash . photos . listCuratedPhotos ( 2 , 15 , "latest" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
photos.getPhoto(id, width, height, rectangle)
Retrieve a single photo.
Arguments
Argument
Type
Opt/Required
id
string
Required
width
number
Optional
height
number
Optional
rectangle
Array
Optional
Example
unsplash . photos . getPhoto ( "mtNweauBsMQ" , 1920 , 1080 , [ 0 , 0 , 1920 , 1080 ] )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
Retrieve a single photo's stats.
Arguments
Argument
Type
Opt/Required
id
string
Required
Example
unsplash . photos . getPhotoStats ( "mtNweauBsMQ" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
photos.getRandomPhoto({ width, height, query, username, featured })
Retrieve a single random photo, given optional filters.
When using this function, It is recommended to double check the types of the parameters,
in particular for the parameters of type Array.
Arguments
Argument 1:
An Object containing the follow keys:
Argument
Type
Opt/Required
width
number
Optional
height
number
Optional
query
string
Optional
username
string
Optional
featured
boolean
Optional
collections
Array
Optional
count
string
Optional
Example
unsplash . photos . getRandomPhoto ( { username : "naoufal" } )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
Like a photo on behalf of the logged-in user. This requires the write_likes
scope.
Arguments
Argument
Type
Opt/Required
id
string
Required
Example
unsplash . photos . likePhoto ( "mtNweauBsMQ" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
Remove a user’s like of a photo.
Arguments
Argument
Type
Opt/Required
id
string
Required
Example
unsplash . photos . unlikePhoto ( "mtNweauBsMQ" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
photos.downloadPhoto(photo)
Trigger a download of a photo as per the download tracking requirement of API Guidelines .
Note : this accepts a photo JSON object, not a URL string or photo ID. See the example below for how to pair it with other calls to trigger it.
Arguments
Argument
Type
Opt/Required
photo
json
Required
Example
unsplash . photos . getPhoto ( "mtNweauBsMQ" )
. then ( toJson )
. then ( json => {
unsplash . photos . downloadPhoto ( json ) ;
} ) ;
// or if working with an array of photos
unsplash . search . photos ( "dogs" , 1 )
. then ( toJson )
. then ( json => {
unsplash . photos . downloadPhoto ( json [ "results" ] [ 0 ] ) ;
} ) ;
collections.listCollections(page, perPage, orderBy)
Get a single page from the list of all collections.
Arguments
Argument
Type
Opt/Required
Notes
page
number
Optional
perPage
number
Optional
orderBy
string
Optional
latest
, popular
or oldest
Example
unsplash . collections . listCollections ( 1 , 10 , "popular" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.listCuratedCollections(page, perPage)
Get a single page from the list of curated collections.
Arguments
Argument
Type
Opt/Required
page
number
Optional
perPage
number
Optional
Example
unsplash . collections . listCuratedCollections ( 1 , 10 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.listFeaturedCollections(page, perPage)
Get a single page from the list of featured collections.
Arguments
Argument
Type
Opt/Required
page
number
Optional
perPage
number
Optional
Example
unsplash . collections . listFeaturedCollections ( 1 , 10 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.getCollection(id)
Retrieve a single collection. To view a user’s private collections, the read_collections
scope is required.
Arguments
Argument
Type
Opt/Required
id
number
Required
Example
unsplash . collections . getCollection ( 123456 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.getCuratedCollection(id)
Or, for a curated collection:
Arguments
Argument
Type
Opt/Required
id
number
Required
Example
unsplash . collections . getCuratedCollection ( 88 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.getCollectionPhotos(id, orderBy)
Retrieve a collection’s photos.
Arguments
Argument
Type
Opt/Required
Notes
id
number
Required
page
number
Optional
perPage
number
Optional
orderBy
string
Optional
latest
, popular
or oldest
Example
unsplash . collections . getCollectionPhotos ( 123456 , 1 , 10 , "popular" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.getCuratedCollectionPhotos(id, orderBy)
Or, for a curated collection:
Arguments
Argument
Type
Opt/Required
Notes
id
number
Required
page
number
Optional
perPage
number
Optional
orderBy
string
Optional
latest
, popular
or oldest
Example
unsplash . collections . getCuratedCollectionPhotos ( 88 , 1 , 10 , "popular" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.createCollection(title, description, private)
Create a new collection. This requires the write_collections
scope.
Arguments
Argument
Type
Opt/Required
title
string
Required
description
string
Optional
private
boolean
Optional
Example
unsplash . collections . createCollection ( "Birds" , "Wild birds from 'round the world" , true )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.updateCollection(id, title, description, private)
Update an existing collection belonging to the logged-in user. This requires the write_collections
scope.
Arguments
Argument
Type
Opt/Required
id
number
Required
title
string
Optional
description
string
Optional
private
boolean
Optional
Example
unsplash . collections . updateCollection ( 12345 , "Wild Birds" , "Wild birds from around the world" , false )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.deleteCollection(id)
Delete a collection belonging to the logged-in user. This requires the write_collections
scope.
Arguments
Argument
Type
Opt/Required
id
number
Required
Example
unsplash . collections . deleteCollection ( 88 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.addPhotoToCollection(collectionId, photoId)
Add a photo to one of the logged-in user’s collections. Requires the write_collections
scope.
Arguments
Argument
Type
Opt/Required
collectionId
number
Required
photoId
string
Required
Example
unsplash . collections . addPhotoToCollection ( 88 , 'abc1234' )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.removePhotoFromCollection(collectionId, photoId)
Remove a photo from one of the logged-in user’s collections. Requires the write_collections
scope.
Arguments
Argument
Type
Opt/Required
collectionId
number
Required
photoId
string
Required
Example
unsplash . collections . removePhotoFromCollection ( 88 , 'abc1234' )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
collections.listRelatedCollections(collectionId)
Lists collections related to the provided one.
Arguments
Argument
Type
Opt/Required
collectionId
number
Required
Example
unsplash . collections . listRelatedCollections ( 88 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
search.photos(keyword, page, per_page)
Get a list of photos matching the keyword.
Arguments
Argument
Type
Opt/Required
Default
keyword
string
Required
page
number
Optional
per_page
number
Optional
10
Example
unsplash . search . photos ( "dogs" , 1 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
search.users(keyword, page, per_page)
Get a list of users matching the keyword.
Arguments
Argument
Type
Opt/Required
Default
keyword
string
Required
page
number
Optional
per_page
number
Optional
10
Example
unsplash . search . users ( "steve" , 1 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
search.collections(keyword, page, per_page)
Get a list of collections matching the keyword.
Arguments
Argument
Type
Opt/Required
Default
keyword
string
Required
page
number
Optional
per_page
number
Optional
10
Example
unsplash . search . collections ( "dogs" , 1 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
Get a list of download counts for all of Unsplash.
Arguments
N/A
Example
unsplash . stats . total ( )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
Arguments
Argument
Type
Opt/Required
res
Object
Required
Example
import Unsplash , { toJson } from "unsplash-js" ;
const unsplash = new Unsplash ( {
applicationId : "{YOUR_ACCESS_KEY}" ,
secret : "{YOUR_SECRET_KEY}" ,
callbackUrl : "{YOUR_CALLBACK_URL}"
} ) ;
unsplash . stats . total ( )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
Shoutout to all the contributors for lending a helping hand.
Shoutout to BrowserStack for letting us use their service to run automated browser tests.
Copyright (c) 2015, Unsplash
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.