Unsplash

A Universal JavaScript wrapper for the Unsplash API.

Browser Support


Latest ✔	Latest ✔	Latest ✔	Latest ✔	10+ ✔

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 poly fill.

Usage

Creating an instance

To create an instance, simply provide an Object with your applicationId, secret and callbackUrl.

import Unsplash from 'unsplash-js';

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

const unsplash = new Unsplash({
  applicationId: "{APP_ID}",
  secret: "{APP_SECRET}",
  callbackUrl: "{CALLBACK_URL}",
  bearerToken: "{USER_BEARER_TOKEN}"
});

Credentials can be obtained from Unsplash Developers.

React Native

For use with React Native, import from unsplash-js/native instead.

import Unsplash from 'unsplash-js/native';

Authorization workflow

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.

Error handling

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

Sidenote

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

Instance Methods

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

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

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.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.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({ width, height, query, username, featured, category })

Retrieve a single random photo, given optional filters.

The category parameter is deprecated and should not be used.

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
`category` (deprecated)	Array	Optional
`collections`	Array	Optional
`count`	string	Optional

Example

unsplash.photos.getRandomPhoto({ username: "naoufal" })
  .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
  });

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

categories.listCategories()

Get a list of all photo categories.

Arguments

N/A

Example

unsplash.categories.listCategories()
  .then(toJson)
  .then(json => {
    // Your code
  });

categories.category(id)

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

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.all(keyword, page, per_page)

Get a list of photos, collections, and users matching the keyword.

Arguments

Argument	Type	Opt/Required	Default
`keyword`	number	Required
`page`	number	Optional
`per_page`	number	Optional	10

Example

unsplash.search.all("dogs", 2)
  .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`	number	Required
`page`	number	Optional
`per_page`	number	Optional	10

Example

unsplash.search.users("steve", 1)
  .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`	number	Required
`page`	number	Optional
`per_page`	number	Optional	10

Example

unsplash.search.photos("dogs", 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`	number	Required
`page`	number	Optional
`per_page`	number	Optional	10

Example

unsplash.search.collections("dogs", 1)
  .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
  });

Helpers

toJson(res)

Arguments

Argument	Type	Opt/Required
`res`	Object	Required

Example

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

const unsplash = new Unsplash({
  applicationId: "{YOUR_APPLICATION_ID}",
  secret: "{YOUR_SECRET_KEY}",
  callbackUrl: "{YOUR_CALLBACK_URL}"
});

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

Shoutouts

Shoutout to all the contributors for lending a helping hand.
Shoutout to BrowserStack for letting us use their service to run automated browser tests.

License

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.

Name		Name	Last commit message	Last commit date
Latest commit History 142 Commits
.github		.github
examples		examples
src		src
test		test
.babelrc		.babelrc
.eslintrc		.eslintrc
.flowconfig		.flowconfig
.gitignore		.gitignore
.npmignore		.npmignore
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
karma.conf.js		karma.conf.js
native.js		native.js
package.json		package.json
tests.webpack.js		tests.webpack.js
webpack.config.base.js		webpack.config.base.js
webpack.config.development.js		webpack.config.development.js
webpack.config.production.js		webpack.config.production.js
yarn.lock		yarn.lock

License

beruic/unsplash-js

Folders and files

Latest commit

History

Repository files navigation

Unsplash

Browser Support

Documentation

Installation

Dependencies

Usage

Creating an instance

React Native

Authorization workflow

Error handling

Sidenote

Instance Methods

auth.getAuthenticationUrl(scopes)

auth.userAuthentication(code)

auth.setBearerToken(accessToken)

currentUser.profile()

currentUser.updateProfile(options)

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)

photos.listPhotos(page, perPage, orderBy)

photos.listCuratedPhotos(page, perPage, orderBy)

photos.searchPhotos(query, category, page, perPage)

photos.getPhoto(id, width, height, rectangle)

photos.getPhotoStats(id)

photos.getRandomPhoto({ width, height, query, username, featured, category })

photos.uploadPhoto(photo)

photos.likePhoto(id)

photos.unlikePhoto(id)

categories.listCategories()

categories.category(id)

categories.categoryPhotos(id, page, perPage)

collections.listCollections(page, perPage, orderBy)

collections.listCuratedCollections(page, perPage)

collections.listFeaturedCollections(page, perPage)

collections.getCollection(id)

collections.getCuratedCollection(id)

collections.getCollectionPhotos(id, orderBy)

collections.getCuratedCollectionPhotos(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)

search.all(keyword, page, per_page)

search.users(keyword, page, per_page)

search.photos(keyword, page, per_page)

search.collections(keyword, page, per_page)

stats.total()

Helpers

toJson(res)

Shoutouts

License

About

Resources

License

Stars

Watchers

Forks

Languages