A Universal JavaScript wrapper for the Unsplash API .
Latest ✔
Latest ✔
Latest ✔
Latest ✔
10+ ✔
$ npm i --save unsplash-js
This library depends on fetch to make requests to the Unsplash API. For browsers 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
.
let unsplash = new Unsplash ( {
applicationId : "{APP_ID}" ,
secret : "{APP_SECRET}" ,
callbackUrl : "{CALLBACK_URL}"
} ) ;
If you already have a bearer token, you can also provide it to the constructor.
let unsplash = new Unsplash ( {
applicationId : "{APP_ID}" ,
secret : "{APP_SECRET}" ,
callbackUrl : "{CALLBACK_URL}" ,
bearerToken : "{USER_BEARER_TOKEN}"
} ) ;
Credentials can be obtained from Unsplash Developers .
Generate an authentication url with the scopes your app requires.
let 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
} ) ;
auth.getAuthenticationUrl(scopes)
Build an OAuth url with requested scopes.
Arguments
Argument
Type
Opt/Required
Default
scopes
Array
Optional
["public"]
Example
let 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
} ) ;
Get a list of photos uploaded by a user.
Arguments
Argument
Type
Opt/Required
username
string
Required
Example
unsplash . users . photos ( "naoufal" )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
users.likes(username, page, perPage)
Get a list of photos liked by a user.
Arguments
Argument
Type
Opt/Required
username
string
Required
page
number
Optional
perPage
number
Optional
Example
unsplash . users . likes ( "naoufal" , 2 , 15 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
photos.listPhotos(page, perPage)
Get a single page from the list of all photos.
Arguments
Argument
Type
Opt/Required
page
number
Optional
perPage
number
Optional
Example
unsplash . photos . listPhotos ( 2 , 15 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
photos.searchPhotos(query, category, page, perPage)
Get a single page from a photo search. Optionally limit your search to a set of categories by supplying the category ID’s.
Arguments
Argument
Type
Opt/Required
query
string
Optional
category
Array
Optional
page
number
Optional
perPage
number
Optional
Example
unsplash . photos . searchPhotos ( "cats" , [ 11 , 88 ] , 1 , 15 )
. 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
} ) ;
photos.getRandomPhoto(category, featured, username, query, width, height)
Retrieve a single random photo, given optional filters.
Arguments
Argument
Type
Opt/Required
category
Array
Optional
featured
boolean
Optional
username
string
Optional
query
string
Optional
width
number
Optional
height
number
Optional
Example
unsplash . photos . getRandomPhoto ( [ 88 ] , true , "naoufal" , "cats" , 1920 , 1080 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
photos.uploadPhoto(photo)
Upload a photo on behalf of the logged-in user. This requires the write_photos
scope.
Arguments
Argument
Type
Opt/Required
photo
Image Binary
Required
Example
import { createReadStream } from "fs" ;
unsplash . photos . uploadPhoto ( createReadStream ( __dirname + "path/to/image" ) )
. 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
} ) ;
categories.listCategories()
Get a list of all photo categories.
Arguments
N/A
Example
unsplash . categories . listCategories ( )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
Retrieve a single category.
Arguments
Argument
Type
Opt/Required
id
string
Required
Example
unsplash . categories . category ( 4 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
categories.categoryPhotos(id, page, perPage)
Retrieve a single category’s photos.
Arguments
Argument
Type
Opt/Required
id
string
Required
page
number
Optional
perPage
number
Optional
Example
unsplash . categories . categoryPhotos ( 4 , 3 , 15 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
curatedBatches.listCuratedBatches()
Get a single page from the list of all curated batches.
Arguments
N/A
Example
unsplash . curatedBatches . listCuratedBatches ( )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
curatedBatches.curatedBatch(id)
Retrieve a single batch.
Arguments
Argument
Type
Opt/Required
id
string
Required
Example
unsplash . curatedBatches . curatedBatch ( 88 )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
curatedBatches.curatedBatchPhotos(id)
Retrieve a single batch’s ten photos.
Arguments
Argument
Type
Opt/Required
id
string
Required
Example
unsplash . curatedBatches . curatedBatchPhotos ( 88 )
. 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" ;
let unsplash = new Unsplash ( {
applicationId : "{YOUR_APPLICATION_ID}" ,
secret : "{YOUR_SECRET_KEY}" ,
callbackUrl : "{YOUR_CALLBACK_URL}"
} ) ;
unsplash . stats . total ( )
. then ( toJson )
. then ( json => {
// Your code
} ) ;
Copyright (c) 2015, Naoufal Kadhom
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.