Unsplash

A server-side Javascript wrapper for working with the Unsplash API.

Before using the Unsplash API, you need to register as a developer and read the API Guidelines.

Quick start

Quick links to methods you're likely to care about:

Note: Every application must abide by the API Guidelines. Specifically, remember to hotlink images, attribute photographers, and trigger a download when appropriate.

Documentation

Installation

$ npm i --save unsplash-js

Dependencies

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 polyfill.

// ES Modules syntax
import fetch from 'node-fetch';
global.fetch = fetch;

// require syntax
const fetch = require('node-fetch');
global.fetch = fetch;

Note: we recommend using a version of node-fetch higher than 2.4.0 to benefit from Brotli compression.

Usage

If you're using unsplash-js publicly in the browser, you'll need to proxy your requests through your server to sign the requests with the Access Key and/or Secret Key to abide by the API Guideline to keep keys confidential.

Creating an instance

To create an instance, simply provide an Object with your accessKey:

// ES Modules syntax
import Unsplash from 'unsplash-js';
// require syntax
const Unsplash = require('unsplash-js').default;

const unsplash = new Unsplash({ accessKey: "{APP_ACCESS_KEY}" });

const unsplash = new Unsplash({
  accessKey: "{APP_ACCESS_KEY}",
  // Optionally you can also configure a custom header to be sent with every request
  headers: {
    "X-Custom-Header": "foo"
  },
  // Optionally if using a node-fetch polyfill or a version of fetch which supports the timeout option, you can configure the request timeout for all requests
  timeout: 500 // values set in ms
});

Credentials can be obtained from Unsplash Developers.

Error handling

unsplash.users.profile("naoufal")
  .catch(err => {
    // Your flawless error handling code
  });

Instance Methods

All the instance methods below make use of the toJson helper method described below

search.photos(keyword, page, per_page, filters)

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
`filters`	object	Optional
`filters.orientation`	string	Optional
`filters.collections`	array	Optional

Example

unsplash.search.photos("dogs", 1, 10, { orientation: "portrait" })
  .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
  });

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.getPhoto(id)

Retrieve a single photo.

Arguments

Argument	Type	Opt/Required
`id`	string	Required

Example

unsplash.photos.getPhoto("mtNweauBsMQ")
  .then(toJson)
  .then(json => {
    // Your code
  });

photos.getPhotoStats(id)

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({ 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
`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
  });

photos.likePhoto(id)

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
  });

photos.unlikePhoto(id)

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]);
  });

users.profile(username)

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
  });

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.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.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.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
  });

stats.total()

Get a list of download counts for all of Unsplash.

Arguments

N/A

Example

unsplash.stats.total()
  .then(toJson)
  .then(json => {
    // Your code
  });

When initializing an instance of Unsplash, you'll need to include your application's secretKey and callbackUrl as defined in the API documentation:

const unsplash = new Unsplash({
  accessKey: "{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({
  accessKey: "{APP_ACCESS_KEY}",
  secret: "{APP_SECRET}",
  callbackUrl: "{CALLBACK_URL}",
  bearerToken: "{USER_BEARER_TOKEN}"
});

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.

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}");

currentUser.profile()

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
  });

Helpers

toJson(res)

Arguments

Argument	Type	Opt/Required
`res`	Object	Required

Example

import Unsplash, { toJson } from "unsplash-js";

const unsplash = new Unsplash({
  accessKey: "{YOUR_ACCESS_KEY}",
  secret: "{YOUR_SECRET_KEY}"
});

unsplash.stats.total()
  .then(toJson)
  .then(json => {
    // Your code
  });

May	JUN	Jul
	14
2019	2020	2021

Name	Latest commit message	Commit time
Failed to load latest commit information.
.github	Add default Unsplash contributing guidelines	Dec 12, 2016
examples	Update examples	Oct 25, 2019
src	Encode search keywords (Closes #99 ) (#119 )	Oct 15, 2019
test	Encode search keywords (Closes #99 ) (#119 )	Oct 15, 2019
.babelrc	Upgrade babel & flow	Jan 13, 2016
.eslintrc	Add auth methods and fix a few bugs	Nov 8, 2015
.flowconfig	Update babel-eslint and ignore babel libraries from flow	Feb 16, 2016
.gitignore	Add ES6 code coverage	Nov 8, 2015
.npmignore	Fix react-native .babelrc errors	Apr 12, 2016
.travis.yml	[6.0] Remove karma and browserstack from testing suite (#113 )	Oct 4, 2019
CHANGELOG.md	[6.0] Update search methods to support new parameters (#116 )	Oct 15, 2019
LICENSE	Initial commit	Oct 27, 2015
README.md	Add note about node-fetch version to enable brotli compression	Apr 16, 2020
native.js	Fix react-native .babelrc errors	Apr 12, 2016
package-lock.json	Add note about node-fetch version to enable brotli compression	Apr 16, 2020
package.json	Add note about node-fetch version to enable brotli compression	Apr 16, 2020
tests.webpack.js	Setup local browser tests	Mar 4, 2016
webpack.config.base.js	Remove node-fetch dependency	Apr 12, 2016
webpack.config.development.js	Remove node-fetch dependency	Apr 12, 2016
webpack.config.production.js	Remove node-fetch dependency	Apr 12, 2016
yarn.lock	Update the yarn file too. Why can't JS just have one dependency manager	Apr 16, 2020

unsplash / unsplash-js

Join GitHub today

Clone with HTTPS

Downloading

Launching GitHub Desktop

Launching GitHub Desktop

Launching Xcode

Launching Visual Studio

Latest commit

Files

README.md

Unsplash

Quick start

Documentation

Installation

Dependencies

Usage

Creating an instance

Error handling

Instance Methods

search.photos(keyword, page, per_page, filters)

search.users(keyword, page, per_page)

search.collections(keyword, page, per_page)

photos.listPhotos(page, perPage, orderBy)

photos.getPhoto(id)

photos.getPhotoStats(id)

photos.getRandomPhoto({ query, username, featured })

photos.likePhoto(id)

photos.unlikePhoto(id)

photos.downloadPhoto(photo)

users.profile(username)

users.statistics(username, resolution, quantity)

users.photos(username, page, perPage, orderBy, stats)

users.likes(username, page, perPage, orderBy)

users.collections(username, page, perPage, orderBy)

collections.listCollections(page, perPage, orderBy)

collections.getCollection(id)

collections.getCollectionPhotos(id, orderBy)

collections.createCollection(title, description, private)

collections.updateCollection(id, title, description, private)

collections.deleteCollection(id)

collections.addPhotoToCollection(collectionId, photoId)

collections.removePhotoFromCollection(collectionId, photoId)

collections.listRelatedCollections(collectionId)

stats.total()

auth.getAuthenticationUrl(scopes)

auth.userAuthentication(code)

auth.setBearerToken(accessToken)

currentUser.profile()

currentUser.updateProfile(options)

Helpers

toJson(res)